Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rework reparenting #739

Draft
wants to merge 18 commits into
base: master
Choose a base branch
from
Draft

Rework reparenting #739

wants to merge 18 commits into from

Conversation

tristanlatr
Copy link
Contributor

@tristanlatr tristanlatr commented Oct 1, 2023

Rework reparenting (aka re-exporting) in post-processing and add the necessary logic and warnings to fix #184. It ensures that for all time of visiting the ASTs, the model represent the real code structure, since no reparenting is done before post processing. Then the re-exports are groupped by target and the most suitable location of the object is choosen.

This patch changes some of the core pydoctor logic, so it should be carefully reviewed.

This PR implements the required structural changes to takle issue #295.

Introduces the Module.imports attribute holding a list of resolved imports (like ast.alias but with full module names), this is required by the re-exporting process since only imported names should be reparented.

Introduces the System.modules attribute that is a dict from the module full names to the Module instances. This dict is not changed during reparenting. It's populated when the modules are added to the system. This behaviour better matches the python import system and makes us differentiate a module vs an object with the same fullname as the module in the parent package __init__.py for instance.

Finally CanContainImportsDocumentable.exported is a dict used to remember a particular name is re-exported from the module (or class, yes we can currently re-export stuff from classes via an alias) so that it can still show up in the origin page and avoid confusions when seeing an empty implementation module.

tristanlatr and others added 7 commits September 29, 2023 13:29
- Call handleDuplicate when re-exporting process introduces a new duplicate object.
Introduce.
Module.elsewhere_contents
Give priority to public modules in the re-export sorting.
@codecov
Copy link

codecov bot commented Oct 1, 2023

Codecov Report

Attention: Patch coverage is 91.17647% with 18 lines in your changes missing coverage. Please review.

Project coverage is 92.69%. Comparing base (fe29bb7) to head (43276e0).
Report is 14 commits behind head on master.

Files Patch % Lines
pydoctor/astbuilder.py 88.96% 5 Missing and 11 partials ⚠️
pydoctor/model.py 93.10% 2 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master     #739      +/-   ##
==========================================
- Coverage   92.69%   92.69%   -0.01%     
==========================================
  Files          47       47              
  Lines        8337     8456     +119     
  Branches     1846     1881      +35     
==========================================
+ Hits         7728     7838     +110     
- Misses        349      352       +3     
- Partials      260      266       +6     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@tristanlatr
Copy link
Contributor Author

As a side effect, any link to CramMD5ClientAuthenticator will broke with 404.

It might make sens to add symbolic links for all page object (module and functions) that get reparented. For attribute and functions, it's another story since they are not documented in their own page, but we might be able to hack a redirection using JS, like in this post.

I'll try to fix this...

@tristanlatr
Copy link
Contributor Author

Any opinion @glyph ?

pydoctor/astbuilder.py Outdated Show resolved Hide resolved
pydoctor/astbuilder.py Outdated Show resolved Hide resolved

This comment has been minimized.

@tristanlatr tristanlatr marked this pull request as draft November 19, 2023 21:08

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

…ect() symbol. The new objForFullName() implementation relies on old find_object() code.

This comment has been minimized.

Copy link

github-actions bot commented Apr 3, 2024

Diff from pydoctor_primer, showing the effect of this PR on open source code:

attrs (https://github.com/python-attrs/attrs)
-     attr.define
+     attr.mutable

astroid (https://github.com/pylint-dev/astroid)
- /projects/astroid/astroid/manager.py:420: Cannot find link target for "astroid.nodes.Module", resolved from "astroid.Module"
- /projects/astroid/astroid/nodes/_base_nodes.py:195: ambiguous ref to body, could be astroid.nodes.ExceptHandler.body, astroid.nodes.For.body, astroid.nodes.If.body, astroid.nodes.IfExp.body, astroid.nodes.MatchCase.body, astroid.nodes.Try.body, astroid.nodes.TryStar.body, astroid.nodes.While.body, astroid.nodes.With.body
+ /projects/astroid/astroid/nodes/_base_nodes.py:195: ambiguous ref to body, could be astroid.nodes.ExceptHandler.body, astroid.nodes.For.body, astroid.nodes.If.body, astroid.nodes.IfExp.body, astroid.nodes.MatchCase.body, astroid.nodes.Try.body, astroid.nodes.TryStar.body, astroid.nodes.While.body, astroid.nodes.With.body, astroid.nodes.ClassDef.body, astroid.nodes.FunctionDef.body, astroid.nodes.Lambda.body, astroid.nodes.Module.body
- /projects/astroid/astroid/nodes/node_ng.py:187: ambiguous ref to name, could be astroid.nodes.AssignName.name, astroid.nodes.DelName.name, astroid.nodes.EvaluatedObject.name, astroid.nodes.ExceptHandler.name, astroid.nodes.MatchAs.name, astroid.nodes.MatchStar.name, astroid.nodes.Name.name, astroid.nodes.ParamSpec.name, astroid.nodes.TypeAlias.name, astroid.nodes.TypeVar.name, astroid.nodes.TypeVarTuple.name, astroid.nodes.Unknown.name
+ /projects/astroid/astroid/nodes/node_ng.py:187: ambiguous ref to name, could be astroid.nodes.AssignName.name, astroid.nodes.DelName.name, astroid.nodes.EvaluatedObject.name, astroid.nodes.ExceptHandler.name, astroid.nodes.MatchAs.name, astroid.nodes.MatchStar.name, astroid.nodes.Name.name, astroid.nodes.ParamSpec.name, astroid.nodes.TypeAlias.name, astroid.nodes.TypeVar.name, astroid.nodes.TypeVarTuple.name, astroid.nodes.Unknown.name, astroid.nodes.ClassDef.name, astroid.nodes.FunctionDef.name, astroid.nodes.Lambda.name, astroid.nodes.Module.name
- /projects/astroid/astroid/nodes/node_classes.py:3713: ambiguous ref to getitem, could be astroid.nodes.Const.getitem, astroid.nodes.Dict.getitem, astroid.nodes.List.getitem, astroid.nodes.Tuple.getitem
+ /projects/astroid/astroid/nodes/node_classes.py:3713: ambiguous ref to getitem, could be astroid.nodes.Const.getitem, astroid.nodes.Dict.getitem, astroid.nodes.List.getitem, astroid.nodes.Tuple.getitem, astroid.nodes.ClassDef.getitem

scrapy (https://github.com/scrapy/scrapy)
- /projects/scrapy/scrapy/loader/__init__.py:36: Cannot find link target for "scrapy.item.Item", resolved from "default_item_class"
- /projects/scrapy/scrapy/loader/__init__.py:31: Cannot find link target for "scrapy.selector.Selector", resolved from "default_selector_class"
- /projects/scrapy/scrapy/utils/request.py:126: Cannot find link target for "scrapy.http.request.Request.url", resolved from "scrapy.http.Request.url"
- /projects/scrapy/scrapy/utils/request.py:127: Cannot find link target for "scrapy.http.request.Request.method", resolved from "scrapy.http.Request.method"
- /projects/scrapy/scrapy/utils/request.py:128: Cannot find link target for "scrapy.http.request.Request.body", resolved from "scrapy.http.Request.body"

sdk-python (https://github.com/temporalio/sdk-python)
+ /projects/sdk-python/temporalio/api/cluster/v1/__init__.py:1: cannot resolve re-exported name: 'temporalio.api.cluster.v1.message_pb2.ClusterMember'
+ /projects/sdk-python/temporalio/api/cluster/v1/__init__.py:1: cannot resolve re-exported name: 'temporalio.api.cluster.v1.message_pb2.ClusterMetadata'
+ /projects/sdk-python/temporalio/api/cluster/v1/__init__.py:1: cannot resolve re-exported name: 'temporalio.api.cluster.v1.message_pb2.HostInfo'
+ /projects/sdk-python/temporalio/api/cluster/v1/__init__.py:1: cannot resolve re-exported name: 'temporalio.api.cluster.v1.message_pb2.IndexSearchAttributes'
+ /projects/sdk-python/temporalio/api/cluster/v1/__init__.py:1: cannot resolve re-exported name: 'temporalio.api.cluster.v1.message_pb2.MembershipInfo'
+ /projects/sdk-python/temporalio/api/cluster/v1/__init__.py:1: cannot resolve re-exported name: 'temporalio.api.cluster.v1.message_pb2.RingInfo'

twisted (https://github.com/twisted/twisted)
+ /projects/twisted/src/twisted/trial/unittest.py:14: cannot resolve re-exported name: 'twisted.trial._synctest.SkipTest'
- /projects/twisted/src/twisted/spread/jelly.py:212: Cannot find link target for "twisted.spread.flavors.setUnjellyableForClass", resolved from "setUnjellyableForClass"

numpy (https://github.com/numpy/numpy)
+ /projects/numpy/numpy/_core/__init__.py:92: cannot resolve re-exported name: 'numpy._core.numeric.absolute'
+ /projects/numpy/numpy/_core/defchararray.py:24: cannot resolve re-exported name: 'numpy._core.multiarray.compare_chararrays'
+ /projects/numpy/numpy/_core/defchararray.py:26: cannot resolve re-exported name: 'numpy.strings.equal'
+ /projects/numpy/numpy/_core/defchararray.py:26: cannot resolve re-exported name: 'numpy.strings.not_equal'
+ /projects/numpy/numpy/_core/defchararray.py:26: cannot resolve re-exported name: 'numpy.strings.less'
+ /projects/numpy/numpy/_core/defchararray.py:26: cannot resolve re-exported name: 'numpy.strings.less_equal'
+ /projects/numpy/numpy/_core/defchararray.py:26: cannot resolve re-exported name: 'numpy.strings.greater'
+ /projects/numpy/numpy/_core/defchararray.py:26: cannot resolve re-exported name: 'numpy.strings.greater_equal'
+ /projects/numpy/numpy/_core/defchararray.py:26: cannot resolve re-exported name: 'numpy.strings.add'
+ /projects/numpy/numpy/_core/defchararray.py:26: not moving numpy._core.strings.multiply into numpy._core.defchararray, because 'multiply' is defined at line 259
+ /projects/numpy/numpy/_core/defchararray.py:26: cannot resolve re-exported name: 'numpy.strings.isalpha'
+ /projects/numpy/numpy/_core/defchararray.py:26: cannot resolve re-exported name: 'numpy.strings.isdigit'
+ /projects/numpy/numpy/_core/defchararray.py:26: cannot resolve re-exported name: 'numpy.strings.isspace'
+ /projects/numpy/numpy/_core/defchararray.py:26: cannot resolve re-exported name: 'numpy.strings.isalnum'
+ /projects/numpy/numpy/_core/defchararray.py:26: cannot resolve re-exported name: 'numpy.strings.islower'
+ /projects/numpy/numpy/_core/defchararray.py:26: cannot resolve re-exported name: 'numpy.strings.isupper'
+ /projects/numpy/numpy/_core/defchararray.py:26: cannot resolve re-exported name: 'numpy.strings.istitle'
+ /projects/numpy/numpy/_core/defchararray.py:26: cannot resolve re-exported name: 'numpy.strings.isdecimal'
+ /projects/numpy/numpy/_core/defchararray.py:26: cannot resolve re-exported name: 'numpy.strings.isnumeric'
+ /projects/numpy/numpy/_core/defchararray.py:26: cannot resolve re-exported name: 'numpy.strings.str_len'
+ /projects/numpy/numpy/_core/defchararray.py:26: not moving numpy._core.strings.partition into numpy._core.defchararray, because 'partition' is defined at line 309
+ /projects/numpy/numpy/_core/defchararray.py:26: not moving numpy._core.strings.rpartition into numpy._core.defchararray, because 'rpartition' is defined at line 349
+ /projects/numpy/numpy/_core/multiarray.py:12: cannot resolve origin module of re-exported name: '*' from origin module 'numpy._core._multiarray_umath'
+ /projects/numpy/numpy/_core/multiarray.py:16: cannot resolve origin module of re-exported name: '_flagdict' from origin module 'numpy._core._multiarray_umath'
+ /projects/numpy/numpy/_core/multiarray.py:16: cannot resolve origin module of re-exported name: 'from_dlpack' from origin module 'numpy._core._multiarray_umath'
+ /projects/numpy/numpy/_core/multiarray.py:16: cannot resolve origin module of re-exported name: '_place' from origin module 'numpy._core._multiarray_umath'
+ /projects/numpy/numpy/_core/multiarray.py:16: cannot resolve origin module of re-exported name: '_reconstruct' from origin module 'numpy._core._multiarray_umath'
+ /projects/numpy/numpy/_core/multiarray.py:16: cannot resolve origin module of re-exported name: '_vec_string' from origin module 'numpy._core._multiarray_umath'
+ /projects/numpy/numpy/_core/multiarray.py:16: cannot resolve origin module of re-exported name: '_ARRAY_API' from origin module 'numpy._core._multiarray_umath'
+ /projects/numpy/numpy/_core/multiarray.py:16: cannot resolve origin module of re-exported name: '_monotonicity' from origin module 'numpy._core._multiarray_umath'
+ /projects/numpy/numpy/_core/multiarray.py:16: cannot resolve origin module of re-exported name: '_get_promotion_state' from origin module 'numpy._core._multiarray_umath'
+ /projects/numpy/numpy/_core/multiarray.py:16: cannot resolve origin module of re-exported name: '_set_promotion_state' from origin module 'numpy._core._multiarray_umath'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.arange'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.array'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.asarray'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.asanyarray'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.ascontiguousarray'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.asfortranarray'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.broadcast'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.dtype'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.empty'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.flatiter'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.frombuffer'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.from_dlpack'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.fromfile'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.fromiter'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.fromstring'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.matmul'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.ndarray'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.nditer'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.nested_iters'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.promote_types'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray.zeros'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray._get_promotion_state'
+ /projects/numpy/numpy/_core/numeric.py:13: cannot resolve re-exported name: 'numpy._core.multiarray._set_promotion_state'
+ /projects/numpy/numpy/_core/numerictypes.py:83: cannot resolve re-exported name: 'numpy._core.multiarray.datetime_data'
+ /projects/numpy/numpy/_core/numerictypes.py:83: cannot resolve re-exported name: 'numpy._core.multiarray.busdaycalendar'
+ /projects/numpy/numpy/_core/strings.py:8: cannot resolve re-exported name: 'numpy.equal'
+ /projects/numpy/numpy/_core/strings.py:8: cannot resolve re-exported name: 'numpy.not_equal'
+ /projects/numpy/numpy/_core/strings.py:8: cannot resolve re-exported name: 'numpy.less'
+ /projects/numpy/numpy/_core/strings.py:8: cannot resolve re-exported name: 'numpy.less_equal'
+ /projects/numpy/numpy/_core/strings.py:8: cannot resolve re-exported name: 'numpy.greater'
+ /projects/numpy/numpy/_core/strings.py:8: cannot resolve re-exported name: 'numpy.greater_equal'
+ /projects/numpy/numpy/_core/strings.py:8: cannot resolve re-exported name: 'numpy.add'
+ /projects/numpy/numpy/_core/strings.py:13: cannot resolve re-exported name: 'numpy._core.umath.isalpha'
+ /projects/numpy/numpy/_core/strings.py:13: cannot resolve re-exported name: 'numpy._core.umath.isdigit'
+ /projects/numpy/numpy/_core/strings.py:13: cannot resolve re-exported name: 'numpy._core.umath.isspace'
+ /projects/numpy/numpy/_core/strings.py:13: cannot resolve re-exported name: 'numpy._core.umath.isalnum'
+ /projects/numpy/numpy/_core/strings.py:13: cannot resolve re-exported name: 'numpy._core.umath.islower'
+ /projects/numpy/numpy/_core/strings.py:13: cannot resolve re-exported name: 'numpy._core.umath.isupper'
+ /projects/numpy/numpy/_core/strings.py:13: cannot resolve re-exported name: 'numpy._core.umath.istitle'
+ /projects/numpy/numpy/_core/strings.py:13: cannot resolve re-exported name: 'numpy._core.umath.isdecimal'
+ /projects/numpy/numpy/_core/strings.py:13: cannot resolve re-exported name: 'numpy._core.umath.isnumeric'
+ /projects/numpy/numpy/_core/strings.py:13: cannot resolve re-exported name: 'numpy._core.umath.str_len'
+ /projects/numpy/numpy/_core/umath.py:11: cannot resolve origin module of re-exported name: '*' from origin module 'numpy._core._multiarray_umath'
+ /projects/numpy/numpy/ctypeslib.py:81: cannot resolve re-exported name: 'numpy.intp'
+ /projects/numpy/numpy/lib/__init__.py:42: cannot resolve origin module of re-exported name: 'add_docstring' from origin module 'numpy._core._multiarray_umath'
+ /projects/numpy/numpy/lib/__init__.py:42: cannot resolve origin module of re-exported name: 'tracemalloc_domain' from origin module 'numpy._core._multiarray_umath'
+ /projects/numpy/numpy/lib/_array_utils_impl.py:5: cannot resolve re-exported name: 'numpy._core.numeric.normalize_axis_index'
+ /projects/numpy/numpy/linalg/_linalg.py:25: cannot resolve re-exported name: 'numpy._core.matmul'
+ /projects/numpy/numpy/ma/core.py:36: cannot resolve re-exported name: 'numpy.amax'
+ /projects/numpy/numpy/ma/core.py:36: cannot resolve re-exported name: 'numpy.amin'
+ /projects/numpy/numpy/ma/core.py:36: cannot resolve re-exported name: 'numpy.bool_'
+ /projects/numpy/numpy/ma/core.py:36: cannot resolve re-exported name: 'numpy.angle'

... (truncated 124 lines) ...

@tristanlatr tristanlatr mentioned this pull request May 1, 2024
@tristanlatr
Copy link
Contributor Author

Blockers:

  • any link to CramMD5ClientAuthenticator will broke with 404, as well as other objects that will end up documented somewhere else than their old location.
  • we should consider aliases as proper Documentable before, otherwise the numpy warning diff is unacceptable.

@tristanlatr tristanlatr added the pending This ticket needs code related to another ticket not yet fixed label Aug 22, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
pending This ticket needs code related to another ticket not yet fixed
Projects
None yet
Development

Successfully merging this pull request may close these issues.

__all__ re-exports don't work for CramMD5ClientAuthenticator
1 participant