Sphinx's autodoc fails to handle FileField due to FileDescriptor implementation
|Reported by:||benoitbryon||Owned by:||nobody|
|Component:||Database layer (models, ORM)||Version:||1.5|
|Cc:||bmispelon@…, jm.barbier+djangocode@…||Triage Stage:||Ready for checkin|
|Has patch:||yes||Needs documentation:||no|
|Needs tests:||no||Patch needs improvement:||no|
I was reading code to understand why Sphinx's autodoc fails to handle some model attributes such as FileField. See https://bitbucket.org/birkenfeld/sphinx/issue/1254/autodoc-fails-to-handle-descriptors-with for details...
... then I wondered why SingleRelatedObjectDescriptor.get() returns self if instance is None whereas FileDescriptor.get() raises AttributeError().
I guess they should have the same behaviour. But I'm not sure since I do not know the reason why they differ...
As I understand http://docs.python.org/2/reference/datamodel.html#object.__get__, raising AttributeError is a feature.
But as mentioned in https://github.com/deschler/django-modeltranslation/pull/131, returning self could be a solution to get autodoc work (but isn't it a hack?).
Notes and references:
- SingleRelatedObjectDescriptor's implementation: https://github.com/django/django/blob/c7d0ff0cad24dbf444f2e4b534377c3352c7aa98/django/db/models/fields/related.py#L182
- FileDescriptor's implementation: https://github.com/django/django/blob/31e6d58d46894ca35080b4eab7967e4c6aae82d4/django/db/models/fields/files.py#L157
- Creator (and thus many custom fields, including third-party such as django-uuidfield) is also affected: https://github.com/django/django/blob/03d9566e0df45c72bffa99fe244a92f0279da56f/django/db/models/fields/subclassing.py#L33
Change History (7)
comment:1 Changed 3 years ago by benoitbryon
- Needs documentation unset
- Needs tests unset
- Patch needs improvement unset
comment:2 Changed 3 years ago by bmispelon
- Cc bmispelon@… added
- Triage Stage changed from Unreviewed to Accepted
comment:5 Changed 10 months ago by timgraham
- Has patch set
- Summary changed from Inconsistent __get__() implementation: SingleRelatedObjectDescriptor VS FileDescriptor to Sphinx's autodoc fails to handle FileField due to FileDescriptor implementation
comment:6 Changed 10 months ago by charettes
- Triage Stage changed from Accepted to Ready for checkin