Unify the type preprocessing logic in Napoleon #13146
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
cbarrick
force-pushed
the
napoleon-preprocess
branch
5 times, most recently
from
8856704 to
223a7cb
Compare
This puts all preprocessing code above both docstring classes, rather than in between. This is in preparation to making both docstring classes share the same preprocessing.
Previously, there were two type preprocessing functions: `_convert_type_spec` (used in Google-style docstrings) and `_convert_numpy_type_spec` (used in Numpy-style docstrings). The Google version simply applied type-alias translations or wrapped the text in a `:py:class:` role. The Numpy version does the same, plus adds special handling for keywords `optional` and `default` and delimiter words `or`, `of`, and `and`. This allows one to write in natural language, like `Array of int` instead of `Array[int]` or `Widget, optional` instead of `Optional[Widget]` or `Widget | None`. Numpy style is described in full at: https://numpydoc.readthedocs.io/en/latest/format.html#parameters This commit eliminates the distinction and allows Google-style docstrings to use these preprocessing rules.
cbarrick
force-pushed
the
napoleon-preprocess
branch
from
223a7cb to
8f2a345
Compare
|
Friendly ping! Any concerns with this change? |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Subject: Unify the type preprocessing logic in Napoleon
Feature or Bugfix
Purpose
Allow Google-style docstrings to use the
optionalanddefaultkeywords described at https://numpydoc.readthedocs.io/en/latest/format.html#parametersDetail
Previously, there were two separate type preprocessing functions:
_convert_type_spec(used in Google-style docstrings) and_convert_numpy_type_spec(used in Numpy-style docstrings).The Google version simply applied type-alias translations or wrapped the text in a
:py:class:role.The Numpy version does the same, plus adds special handling for keywords
optionalanddefaultand delimiter wordsor,of, andand. This allows one to write in natural language, likeArray of intinstead ofArray[int]orWidget, optionalinstead ofOptional[Widget]orWidget | None. Numpy style is described in full at: https://numpydoc.readthedocs.io/en/latest/format.html#parametersThis commit eliminates the distinction and allows Google-style docstrings to use these preprocessing rules.
More details
The Numpy-style preprocessing code lived between the GoogleDocstring and NumpyDocstring classes. This was kinda an awkward location when the code would become shared by both classes.
This PR is broken into two commits. The first moves the code to a more palatable location. The second migrates GoogleDocstring to use the previously-named
_convert_numpy_type_spec.I think it will be much easier to review the diffs individually rather than the diff for the whole PR.