twisted / pydoctor

This is pydoctor, an API documentation generator that works by static analysis.
https://pydoctor.readthedocs.io
Other
179 stars 48 forks source link

Rework reparenting and allobjects attribute #725

Closed tristanlatr closed 9 months ago

tristanlatr commented 1 year ago

Rework reparenting in post-processing. 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.

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

This changes will help fixing #295 as well as improve our capacity to fix #184 and other __all__ related problems. Together with #723 it will finally fix #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.

Switch from using of a actual dict to hold values of System.allobjects attribute; instead allobject is a proxy that lazily get the documentable having the requested fullname based on system's rootobjects and modules attributes. It simplifies drastically the reparenting code since the only thing left to handle is the new name of object and it's parent.contents links. This switch also introduces diff in handling of duplicate objects since there is no need to explicitly handle allobjects mapping.

This PR should not introduce any changes in behaviour, except it fixes a bug in reparenting process when there as duplicates (see new tests).

codecov[bot] commented 1 year ago

Codecov Report

Patch coverage: 91.92% and no project coverage change.

Comparison is base (965ed95) 92.62% compared to head (d617603) 92.62%.

Additional details and impacted files ```diff @@ Coverage Diff @@ ## master #725 +/- ## ======================================= Coverage 92.62% 92.62% ======================================= Files 47 47 Lines 8132 8214 +82 Branches 1944 1968 +24 ======================================= + Hits 7532 7608 +76 Misses 343 343 - Partials 257 263 +6 ``` | [Impacted Files](https://app.codecov.io/gh/twisted/pydoctor/pull/725?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=twisted) | Coverage Δ | | |---|---|---| | [pydoctor/astbuilder.py](https://app.codecov.io/gh/twisted/pydoctor/pull/725?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=twisted#diff-cHlkb2N0b3IvYXN0YnVpbGRlci5weQ==) | `95.71% <83.33%> (-0.68%)` | :arrow_down: | | [pydoctor/model.py](https://app.codecov.io/gh/twisted/pydoctor/pull/725?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=twisted#diff-cHlkb2N0b3IvbW9kZWwucHk=) | `94.96% <97.84%> (+0.32%)` | :arrow_up: | | [pydoctor/templatewriter/\_\_init\_\_.py](https://app.codecov.io/gh/twisted/pydoctor/pull/725?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=twisted#diff-cHlkb2N0b3IvdGVtcGxhdGV3cml0ZXIvX19pbml0X18ucHk=) | `92.54% <100.00%> (ø)` | |

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Do you have feedback about the report comment? Let us know in this issue.

tristanlatr commented 10 months ago

This PR could and should be splitted in two: first the allobject refactor, then the reparenting refactor. So I'll mark it as draft for now.