How best to handle class hierarchies

[CEXT-Dan]

In my project, I have a class hierarchy Entity -> Curve -> line with overloaded constructors and I’m looking for a minimalist approach to handing doc strings.

Example docstring

class Line(PyDb.Curve):
    @overload
    def __init__(self, /) -> None: ...
    @overload
    def __init__(self, start: PyGe.Point3d, end: PyGe.Point3d, /) -> None: ...
    @overload
    def __init__(self, id: PyDb.ObjectId, /) -> None: ...
    @overload
    def __init__(self, id: PyDb.ObjectId, mode: PyDb.OpenMode, /) -> None: ...
    @overload
    def __init__(self, id: PyDb.ObjectId, mode: PyDb.OpenMode, erased: bool, /) -> None: ...
    @overload
    def __init__(self, *args) -> None:
        """
        The AcDbLine class represents the line entity in AutoCAD. A line object is a 3D object that
        is specified by its start point, endpoint, and normal vector. In addition, the line object
        supports thickness along its normal vector direction (that is, height or "extrusion").
        """
    def __reduce__(self, /) -> Any: ...

The problem is, when I hover over, or begin type in a ctor parameter, I get the docstring for Curve.

If I move the doc string just below the ‘class’ it has different behavior. I’m trying to avoid spamming the stubs with identical doc strings

Thanks for listening

[github-actions[bot]]

Hi @CEXT-Dan, I'm an AI Support assistant here to help with your issue. While the team reviews your request, I wanted to provide some possible tips and documentation that might help you in the meantime.

---

Similar Issues (FYI only, not solutions)

The following issues may or may not be related to your report. They are provided for reference only, as they may describe similar symptoms, affect the same feature, or address related concerns, but may not be the same issue.

• Incorrect showing of method/function parameters and 'docstring' information – Pylance signature help shows condensed signatures and missing docstrings for methods like DataFrame.rank and built-ins. #2711

---

The team will respond to your issue shortly. Please note this is a trial feature and may not be fully accurate. I hope these suggestions are helpful in the meantime. If this comment helped you, please give it a 👍. If the suggestion was not helpful or was incorrect, please give it a 👎. Your feedback helps us improve!

[heejaechang]

sounds like enhancement we can do.

for overload, before we look hierarchy for the same signature (overridden symbol in base type), we look other overloads to see they have doc string and prefer that over one in the base.

[erictraut]

Determining the best docstring to display for a constructor call is complex because it potentially involves an __init__ method docstring (plus one or more overloads), a __new__ method (plus one or more overloads), a class docstring, and a class hierarchy that includes all of the above.

I think it would benefit Python developers generally — and library maintainers and stub authors especially — if there was some standardization in this space. The number of Python type checkers and language servers is already large and is expanding, so consistency across tools is going to be important here.

@heejaechang, I think the Pylance team is in a good place to spearhead such a standardization effort. This would not only help developers, but it would also minimize the chance that someone else will establish a different standard in the future and force Pylance to conform to it. If you're interested in doing this, I recommend writing down a proposed algorithm and starting a thread in the Python typing forum. I'm not sure if such a standard belongs in the Python typing spec, but I could see it being accepted in the official Type System Reference.