Issue #1254 wontfix

Autodoc fails to handle descriptors with instance attribute access

Anonymous created an issue

First and foremost, here is my motivation: I would like to be able to document descriptors with "instance attribute access" with Sphinx's autodoc.

As an example, when I write something like this:

from django.db import models

class Person(models.Model):
    """Store data about humans."""
    #: Image that represents the person.
    avatar = models.ImageField()

Then I would like the "avatar" attribute and the docstring "Image that represents the person" to be shown in Sphinx documentation using autodoc.

It does not work...

Django's models use descriptors for some fields, such as django.db.models.fields.files.ImageField. Accessing Person.avatar raises AttributeError: The 'avatar' attribute can only be accessed from Person instances..

The AttributeError is raised in descriptor's __get__() method:

This behaviour seems in accordance with descriptors get() definition. I understand that raising an AttributeError is a feature.

In such a situation, Sphinx's autodoc fails to handle the avatar attribute, reports a warning and does not display the avatar attribute with docstring in documentation.

How could we get documentation for this kind of descriptors? Is it a Sphinx issue? Can developers change the descriptor implementation to make it compatible with Sphinx?

Some additional notes and references:

Comments (10)

  1. Sean Bell

    For anyone that's interested, I have a workaround for this issue. You can monkey patch the offending Django source code in your

    Add this to your Sphinx after setting up the Django environment:

    from django.db.models.fields.files import FileDescriptor
    FileDescriptor.__get__ = lambda self, *args, **kwargs: self
  2. Charl Botha

    If anyone runs into this using Brad Jasper's jsonfield, there's a different work-around, because jsonfield has a copy of Django's subclassing module.

    Add the following to your

    from jsonfield.subclassing import Creator
    Creator.__get__ = lambda self, *args, **kwargs: self
  3. Charlie Clark

    Georg Brandl I've got a similar problem with openpyxl. Unfortunately, the monkey patch doesn't quite work. Can you provide some additional information as to what Sphinx is trying to do? or what it needs so that I craft something suitable?

    Update it: fixed it for Alias descriptors (where one descriptor is merely an alias for another) but now struggle with the need for different configurations between the scan and when running doctests. Any ideas?

  4. Log in to comment