Rework reparenting #739

tristanlatr · 2023-10-01T21:58:02Z

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.

- 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 · 2023-10-01T21:59:59Z

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 · 2023-10-01T23:47:29Z

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 · 2023-10-06T02:00:16Z

Any opinion @glyph ?

pydoctor/astbuilder.py

…r follow aliases.

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

github-actions · 2024-04-03T21:30:02Z

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 · 2024-07-04T16:58:14Z

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 and others added 7 commits September 29, 2023 13:29

- Parse module imports and store them into Module.imports attribute.

190b5a7

- Call handleDuplicate when re-exporting process introduces a new duplicate object.

Move the re exporting to post processing

cd76414

Fix mypy and simplify

a3ad4eb

Fix issue #184.

8d7b748

Introduce. Module.elsewhere_contents

Do not reparent stuff listed in __all__ of a public module.

d5d176a

Give priority to public modules in the re-export sorting.

Fix space

434a460

Fix typo

0bf2334

Merge branch 'master' into 295-184-reparenting-rework

1235d9e

tristanlatr commented Oct 13, 2023

View reviewed changes

pydoctor/astbuilder.py Outdated Show resolved Hide resolved

Update pydoctor/astbuilder.py

f28c265

tristanlatr commented Oct 15, 2023

View reviewed changes

pydoctor/astbuilder.py Outdated Show resolved Hide resolved

tristanlatr and others added 4 commits October 15, 2023 13:39

Update pydoctor/astbuilder.py

a70b8b2

Merge branch 'master' into 295-184-reparenting-rework

f00cda1

It's possible to re-export stuff from a class.

1c4343b

Merge branch 'master' into 295-184-reparenting-rework

08676f8

This comment has been minimized.

Sign in to view

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

tristanlatr mentioned this pull request Dec 28, 2023

fix: Hardlink to index.html #722

Closed

tristanlatr added 2 commits April 2, 2024 21:31

Merge branch 'master' into 295-184-reparenting-rework

943092a

Fix mypy

011ebcf

This comment has been minimized.

Sign in to view

tristanlatr mentioned this pull request Apr 3, 2024

Rework reparenting + pre process docstrings #773

Closed

Try using System.find_object() in System.expandName() so it can bette…

797eb0c

…r follow aliases.

This comment has been minimized.

Sign in to view

Replace System.find_object by System.objForFullName and drop find_obj…

5df63e8

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

This comment has been minimized.

Sign in to view

Better docs

43276e0

tristanlatr mentioned this pull request May 1, 2024

Symlink to index.html #720

Closed

tristanlatr added the pending This ticket needs code related to another ticket not yet fixed label Aug 22, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rework reparenting #739

Rework reparenting #739

tristanlatr commented Oct 1, 2023 •

edited

Loading

codecov bot commented Oct 1, 2023 •

edited

Loading

tristanlatr commented Oct 1, 2023

tristanlatr commented Oct 6, 2023

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

github-actions bot commented Apr 3, 2024

tristanlatr commented Jul 4, 2024

Rework reparenting #739

Are you sure you want to change the base?

Rework reparenting #739

Conversation

tristanlatr commented Oct 1, 2023 • edited Loading

codecov bot commented Oct 1, 2023 • edited Loading

Codecov Report

tristanlatr commented Oct 1, 2023

tristanlatr commented Oct 6, 2023

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

github-actions bot commented Apr 3, 2024

tristanlatr commented Jul 4, 2024

tristanlatr commented Oct 1, 2023 •

edited

Loading

codecov bot commented Oct 1, 2023 •

edited

Loading