numpy / numpy/numpydoc

BUG: Object references that start with a tilde in "See Also" section cause a `ValueError`

Open
#519 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
355
Forks
181
Avg merge
1d 9h
Merged PRs (30d)
3

Description

Description

When I ran the docstring validator on a docstring with a "See Also" section that contains an object reference starting with a tilde, I got a ValueError that caused the validator to crash.

This might be related to #232.

Expected behavior

Ideally, an object reference starting with a tilde would be recognized as valid.

Otherwise, if a "See Also" section is not able to be parsed, the validator would ideally keep running and instead report the problem with a specific error code.

It would also have been helpful for the traceback to say which file the error occurred in.

Minimum reproducible example

Using numpydoc 1.6.0:

def test_something():
    """
    Sample docstring.

    See Also
    --------
    ~astropy.units.Quantity
    """
    ...

When I run validate-docstrings on a file containing this function/docstring, then I get the following error:

Traceback (most recent call last):
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/bin/validate-docstrings", line 8, in <module>
sys.exit(main())
^^^^^^
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/hooks/validate_docstrings.py", line 400, in main
findings.extend(process_file(file, config_options))
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/hooks/validate_docstrings.py", line 339, in process_file
docstring_visitor.visit(module_node)
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/hooks/validate_docstrings.py", line 221, in visit
self.generic_visit(node)
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/ast.py", line 426, in generic_visit
self.visit(item)
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/hooks/validate_docstrings.py", line 219, in visit
self._get_numpydoc_issues(node)
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/hooks/validate_docstrings.py", line 188, in _get_numpydoc_issues
report = validate.validate(
^^^^^^^^^^^^^^^^^^
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/validate.py", line 613, in validate
doc = validator_cls(obj_name=obj_name, **validator_kwargs)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/hooks/validate_docstrings.py", line 44, in __init__
self.doc: docscrape.NumpyDocString = docscrape.NumpyDocString(self.raw_doc)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/docscrape.py", line 149, in __init__
self._parse()
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/docscrape.py", line 425, in _parse
self["See Also"] = self._parse_see_also(content)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/docscrape.py", line 344, in _parse_see_also
self._error_location(f"Error parsing See Also entry {line!r}")
File "/run/media/namurphy/d423d80e-c227-4a33-b50f-545b44160ce3/namurphy/Applications/miniconda3/envs/pldev/lib/python3.11/site-packages/numpydoc/docscrape.py", line 453, in _error_location
raise ValueError(msg)
ValueError: Error parsing See Also entry '~astropy.units.Quantity'

Thank you!

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in numpydoc/docscrape.py, especially _parse_see_also and _error_location, using the traceback and minimum reproducible example to reproduce the crash. Check the validator path in numpydoc/hooks/validate_docstrings.py; done means tilde-prefixed references are handled without crashing, or an actionable validation error is reported instead.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.