Refactor the ASTBuilder to get rid of the currentAttr attribute. #585
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
This attribute was used to attach the right docstring node to the right Attribute object. Now it uses AST node navigation (with the .parent attribute) instead for fetching the docstring node for an ast.Assign. This change might not be worth it, on the one hand it removes a attribute beeing mutated at different palces in the code, but replaces this kind of "unsafe" state tracking (meaning not with pop() and push()) by some more verbose solution that involves adding the .parent attribute on all nodes. The zopeinferface extension needed to be adjusted as well because it relied on the docstring assigment feature in an implicit way, now it's explicit what we're doing.
Codecov Report
@@ Coverage Diff @@
## master #585 +/- ##
==========================================
- Coverage 90.88% 90.82% -0.07%
==========================================
Files 45 45
Lines 7711 7756 +45
Branches 1670 1679 +9
==========================================
+ Hits 7008 7044 +36
- Misses 438 442 +4
- Partials 265 270 +5
Continue to review full report at Codecov.
|
|
After a second though, I believe it’s worth it. Mainly because:
|
tristanlatr
commented
May 26, 2022
pydoctor/astbuilder.py
Outdated
| def _reduceNameInContext(self, target:ast.expr) -> Tuple[List[str], model.Documentable]: | ||
| """ | ||
| If the current context is a method, strip the C{'self.'} part of assignment names and return | ||
| the right L{Class} context in which to use the new name. The new name maybe dotted. |
There was a problem hiding this comment.
Suggested change
| the right L{Class} context in which to use the new name. The new name maybe dotted. | |
| the right L{Class} context in which to use the new name. The new name maybe dotted. |
tristanlatr
commented
May 26, 2022
tristanlatr
commented
Jun 11, 2022
|
|
||
| @returns: Tuple C{(dottedname, context)} or just the parsed target with the current | ||
| context if the target is not using C{self.}. | ||
| @raises: L{InvalidName} or L{UsingSelfInUnknownContext}. |
There was a problem hiding this comment.
Suggested change
| @raises: L{InvalidName} or L{UsingSelfInUnknownContext}. | |
| @raises InvalidName or UsingSelfInUnknownContext: If there is an issue while trying to determine the actual name and context of the expression. |
|
|
||
| def _reduceNameInContext(self, target:ast.expr) -> Tuple[List[str], model.Documentable]: | ||
| """ | ||
| If the current context is a method, strip the C{'self.'} part of assignment names and return |
There was a problem hiding this comment.
Suggested change
| If the current context is a method, strip the C{'self.'} part of assignment names and return | |
| If the current context is a method and the the target is starting with C{self.}, strips the C{self.} part of assignment name and return |
| @@ -40,6 +47,12 @@ def _maybeAttribute(cls: model.Class, name: str) -> bool: | |||
| obj = cls.find(name) | |||
| return obj is None or isinstance(obj, model.Attribute) | |||
|
|
|||
| class SkipInlineDocstring(Exception): | |||
| ... | |||
| class InvalidName(Exception): | |||
There was a problem hiding this comment.
This is a better name for this exception:
Suggested change
| class InvalidName(Exception): | |
| class NotAName(Exception): |
| parent = maybe_parent | ||
| return dottedname, parent | ||
|
|
||
| def _handleInlineDocstrings(self, assign:Union[ast.Assign, ast.AnnAssign], target:ast.expr) -> None: |
There was a problem hiding this comment.
I should add a test case for the following usage:
class C:
def __init__(self, x):
self.x = b = range(x)
"doc of C.x"
|
@tristanlatr sorry to punt on this, but can you address the conflicts and then re-request from @twisted/twisted-contributors rather than me personally? |
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.
Refactor the ASTBuilder to get rid of the currentAttr attribute.
This attribute was used to attach the right docstring node to the right Attribute object. Now it uses AST node navigation (with the .parent attribute) instead for fetching the docstring node for an ast.Assign.
This change might not be worth it, on the one hand it removes a attribute being mutated at different places in the code, but replaces this kind of "unsafe" state tracking (meaning not with pop() and push()) by some more verbose solution that involves adding the .parent attribute on all nodes.
The zopeinferface extension needed to be adjusted as well because it relied on the docstring assignment feature in an implicit way, now it's explicit what we're doing.