mitmproxy
Incorrect documentation when a method and its return type share the same name
Problem Description
Encountering incorrect documentation when a method and its return type share the same name. For example, consider the following code:
def Dog(self) -> Dog:
The generated documentation displays:
Dog: <property object at 0x7ffff63607c0>
Steps to reproduce the behavior:
- Python code in
dog.pyto be used withpdoc
from __future__ import annotations
class Factory:
def __init__(self) -> None:
self._dog: Dog = Dog("my_dog")
@property
def Dog(self) -> Dog:
return self._dog
class Dog:
def __init__(self, name: str) -> None:
self._name: str = name
@property
def Name(self) -> str:
return self._name
def main() -> None:
factory: Factory = Factory()
dog: Dog = factory.Dog
print(dog.Name)
main()
- Run:
pdoc ./dog.py -o doc - Examine the issue in the
pdocoutput
dog
class Factory:
Dog: <property object at 0x7ffff6367d10>
class Dog:
Dog(name: str)
Name: str
def main() -> None:
System Information
% pdoc --version
pdoc: 15.0.3
Python: 3.9.6
Platform: Linux-4.12.14-122.201-default-x86_64-with-glibc2.22
Unclear if this is a bug or if this is technically correct. At least theoretically there is a Dog member in the local namespace. Do the Python typing specs say anything about this?
I've pushed https://github.com/mhils/pdoc/commit/c0fa6e10a09fbdfa035e5169dd2769f0fd2b7fc3 with a potential fix, but I don't like it and I don't know if it should go in. Practicality may win here, not sure.
To the best of my knowledge, a function or method cannot be used as a type hint. Therefore, in this context, Dog type hint refers to the Dog class.