Better property support

[tristanlatr]

The property setter and deleter informations now shows at the same place as the property getter. Meaning inside the documentation of an Attribute object.

Fixes #587. Together with #595 it will look better (without the Undocumented param tables).

As a side effect of the change, the setters and deleters Function are removed from the documentable tree, we can't look for the property setters in the search bar with *.setter, we can't link to them from docstrings (but still we can link to them with their anchor) and they won't display in intersphinx mapping.

This is a breaking change, but that might not be very important. These objects do not actually exists at runtime, so I think it's OK to remove them from the tree.

Before:

After:

[codecov]

Codecov Report

Attention: 13 lines in your changes are missing coverage. Please review.

Comparison is base (9becf85) 92.69% compared to head (1bb7bed) 92.70%.

Files	Patch %	Lines
pydoctor/astbuilder.py	93.75%	4 Missing and 3 partials ⚠️
pydoctor/model.py	91.89%	1 Missing and 5 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #640      +/-   ##
==========================================
+ Coverage   92.69%   92.70%   +0.01%     
==========================================
  Files          47       47              
  Lines        8285     8461     +176     
  Branches     1826     1872      +46     
==========================================
+ Hits         7680     7844     +164     
- Misses        347      352       +5     
- Partials      258      265       +7     

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

[tristanlatr]

More tests should be added to ensure we’re a not crashing with KeyError when objects are getting renamed because there are duplicates or moved around because they’re reparented.

[tristanlatr]

Suggested change

	"""This property has a docstring only on the setter."""
	"""This property has a docstring only on the getter."""

[tristanlatr]

Few things needs to be improved here:

• Trigger warnings when pydoctor doesn't understand a property def
• Probably the code can be factored into less lines

[tristanlatr]

This should trigger a few warnings.

[tristanlatr]

There are several refactors to do for the changes to be clean, it should take less lines and function should created to wrap the properly handing logic while visiting the function defs.

And more importantly, I’m unsure if it worth it to support inherited property overrides, like the proposed change currently does. On the one hand, it’s properly covered by tests cases and it’s used in cpython tests, but on the other hand, it’s not very common usage of te property decorators and it adds about 80 lines of code to pydoctor. But I think it’s can’t be bad to support it at the end of the day it’s safe and it doesn’t make pydoctor crash.

[tristanlatr]

I think I'll remove the support for inherited property overrides. It's jut (almost) never used in real life code. I only ever saw that in cpython test cases.

This have been done. At the same time, I've added support for property(fset, fget, fdel, doc) old school decoration.

[tristanlatr]

The numpy diff bugs me... I'm not currently sure the cause of such a diff.

[github-actions]

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

astroid (https://github.com/pylint-dev/astroid)
+ /projects/astroid/astroid/nodes/scoped_nodes/scoped_nodes.py:263: Existing docstring at line 260 is overriden
+ /projects/astroid/astroid/nodes/scoped_nodes/scoped_nodes.py:1871: Existing docstring at line 1773 is overriden
+ /projects/astroid/astroid/nodes/scoped_nodes/scoped_nodes.py:1910: Existing docstring at line 1854 is overriden
+ /projects/astroid/astroid/nodes/scoped_nodes/scoped_nodes.py:1875: Parameter name missing
+ /projects/astroid/astroid/nodes/scoped_nodes/scoped_nodes.py:2003: Parameter name missing
+     astroid.nodes.Arguments.arguments.getter
-     astroid.nodes.node_classes.Arguments.arguments

pycma (https://github.com/CMA-ES/pycma)
+ /projects/pycma/cma/sampler.py:249: Existing docstring at line 244 is overriden

twisted (https://github.com/twisted/twisted): typechecking got 1.08x slower (235.2s -> 252.9s)
(Performance measurements are based on a single noisy sample)

numpy (https://github.com/numpy/numpy)
- /projects/numpy/numpy/ma/core.py:2745: Cannot find link target for "array_like"
+ /projects/numpy/numpy/ma/core.py:3718: Cannot find link target for "numpy.ndarray"

[tristanlatr]

Blockers:

• The warning /projects/astroid/astroid/nodes/scoped_nodes/scoped_nodes.py:1875: Parameter name missing is a bug and should be fixed.
• model.Property should be removed, we should not have to handle yet another documentable type in the customizations nor in our code. What I think would be smart to do is to derive from System.Attribute at runtime in order to dynamically create the type System.Property. We could do about the same for Alias handling.