Sphinx: autodocs does not work well with instance attributes.

[shimizukawa]

Instance attributes set in an init method can be documented with #: comments. When using the autoclass directive with :members: and no list of members, these attributes are picked up by Sphinx, but they are documented with a value of "None", even though there is no such default value.

Additionally, if using :members: with an explicit member list or if using the autoattribute directive, the attribute is not documented and Sphinx prints a traceback on the terminal (but continue with the rest of the document). For example:

Traceback (most recent call last):                                              
  File "/home/simon/.virtualenvs/tinycss/lib/python3.2/site-packages/sphinx/util/inspect.py", line 64, in safe_getattr
    return getattr(obj, name, *defargs)
AttributeError: type object 'Stylesheet' has no attribute 'rules'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/simon/.virtualenvs/tinycss/lib/python3.2/site-packages/sphinx/ext/autodoc.py", line 326, in import_object
    obj = self.get_attr(obj, part)
  File "/home/simon/.virtualenvs/tinycss/lib/python3.2/site-packages/sphinx/ext/autodoc.py", line 232, in get_attr
    return safe_getattr(obj, name, *defargs)
  File "/home/simon/.virtualenvs/tinycss/lib/python3.2/site-packages/sphinx/util/inspect.py", line 70, in safe_getattr
    raise AttributeError(name)
AttributeError: rules

/home/simon/projects/tinycss/docs/parsing.rst:25: WARNING: autodoc can't import/find attribute 'tinycss.css21.Stylesheet.rules', it reported error: "rules", please check your spelling and sys.path

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/904
• Originally reported by: Simon Sapin
• Originally created at: 2012-03-30T19:07:50.858

[shimizukawa]

_From Antonio Valentino on 2012-07-08 15:51:57+00:00_

Same problem for me.
It seems that also the autoattribute directive seems to be broken.

The following doc

{{{

!rst

Test 7

.. currentmodule:: module

.. autoclass:: Foo

Attributes

.. autoattribute:: Foo.bar

.. autoattribute:: Foo.flox

.. autoattribute:: Foo.baz

.. autoattribute:: Foo.qux

.. autoattribute:: Foo.spam

Test 8

.. currentmodule:: module

.. autoclass:: Foo

.. autoattribute:: bar

.. autoattribute:: flox

.. autoattribute:: baz

.. autoattribute:: qux

.. autoattribute:: spam

}}}

do not build correctly and gives the following error:

{{{
$ make html
sphinx-build -b html -d _build/doctrees . _build/html
Making output directory...
Running Sphinx v1.2pre/348224ae1fd5
loading pickled environment... not yet created
building [html]: targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
Traceback (most recent call last):oattr
File "/home/antonio/projects/sphinx/sphinx/ext/autodoc.py", line 326, in import_object
obj = self.get_attr(obj, part)
File "/home/antonio/projects/sphinx/sphinx/ext/autodoc.py", line 232, in get_attr
return safe_getattr(obj, name, *defargs)
File "/home/antonio/projects/sphinx/sphinx/util/inspect.py", line 70, in safe_getattr
raise AttributeError(name)
AttributeError: qux
Traceback (most recent call last):
File "/home/antonio/projects/sphinx/sphinx/ext/autodoc.py", line 326, in import_object
obj = self.get_attr(obj, part)
File "/home/antonio/projects/sphinx/sphinx/ext/autodoc.py", line 232, in get_attr
return safe_getattr(obj, name, *defargs)
File "/home/antonio/projects/sphinx/sphinx/util/inspect.py", line 70, in safe_getattr
raise AttributeError(name)
AttributeError: spam
Traceback (most recent call last):
File "/home/antonio/projects/sphinx/sphinx/ext/autodoc.py", line 326, in import_object
obj = self.get_attr(obj, part)
File "/home/antonio/projects/sphinx/sphinx/ext/autodoc.py", line 232, in get_attr
return safe_getattr(obj, name, *defargs)
File "/home/antonio/projects/sphinx/sphinx/util/inspect.py", line 70, in safe_getattr
raise AttributeError(name)
AttributeError: qux
Traceback (most recent call last):
File "/home/antonio/projects/sphinx/sphinx/ext/autodoc.py", line 326, in import_object
obj = self.get_attr(obj, part)
File "/home/antonio/projects/sphinx/sphinx/ext/autodoc.py", line 232, in get_attr
return safe_getattr(obj, name, *defargs)
File "/home/antonio/projects/sphinx/sphinx/util/inspect.py", line 70, in safe_getattr
raise AttributeError(name)
AttributeError: spam

/home/antonio/tmp/sphinx-autoattribute-issue/doc/test_autoattr.rst:86: WARNING: autodoc can't import/find attribute 'module.Foo.qux', it reported error: "qux", please check your spelling and sys.path
/home/antonio/tmp/sphinx-autoattribute-issue/doc/test_autoattr.rst:88: WARNING: autodoc can't import/find attribute 'module.Foo.spam', it reported error: "spam", please check your spelling and sys.path
/home/antonio/tmp/sphinx-autoattribute-issue/doc/test_autoattr.rst:13: WARNING: autodoc can't import/find attribute 'module.Foo.qux', it reported error: "qux", please check your spelling and sys.path
/home/antonio/tmp/sphinx-autoattribute-issue/doc/test_autoattr.rst:15: WARNING: autodoc can't import/find attribute 'module.Foo.spam', it reported error: "spam", please check your spelling and sys.path
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] test_autoattr
writing additional files... (1 module code pages) _modules/index
genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded, 4 warnings.

Build finished. The HTML pages are in _build/html.
}}}

The python code I'm trying to document is the one used in the sphinx documentation as example (http://sphinx.pocoo.org/ext/autodoc.html?highlight=autoattribute#directive-autoattribute):

{{{

!python

class Foo:
"""Docstring for class Foo."""

#: Doc comment for class attribute Foo.bar.
#: It can have multiple lines.
bar = 1

flox = 1.5   #: Doc comment for Foo.flox. One line only.

baz = 2
"""Docstring for class attribute Foo.baz."""

def __init__(self):
    #: Doc comment for instance attribute qux.
    self.qux = 3

    self.spam = 4
    """Docstring for instance attribute spam."""

}}}

[shimizukawa]

_From Alexander Stepanov on 2012-11-06 10:07:22+00:00_

I have same problem :(

[shimizukawa]

_From Jon Waltman on 2012-11-09 06:11:37+00:00_

autodoc: Handle explicit instance attributes in :members: (re #904)

→ <>

[shimizukawa]

_From Jon Waltman on 2012-11-09 06:18:12+00:00_

The case where you give an explicit :members: list
containing instance attributes should be fixed now.

they are documented with a value of "None",
even though there is no such default value.

Instance attributes are not evaluated and getattr'd like other
attributes so no value is available to document. Autodoc just
displays them as None.

if using the autoattribute directive, the attribute is
not documented and Sphinx prints a traceback

The autoattribute directive still doesn't work for instance
attributes but their is an undocumented autoinstanceattribute
directive that does work.

I'm not sure if this is the intended behavior and
autoinstanceattribute just needs to be documented or if
autoattribute should also handle instance attributes.

[shimizukawa]

_From Alexander Stepanov on 2012-11-13 12:35:15+00:00_

Jonathan Beavers Waltman

Instance attributes are not evaluated and getattr'd like other attributes so no value is available to document. Autodoc just displays them as None.

So what is a value of printing "None" near each attribute if it is only possible value? It's ugly!

[shimizukawa]

_From Johannes Dewender on 2013-01-24 13:59:07+00:00_

There is a :novalue: option proposed in pull request #109. This would keep autodoc from printing values for these attributes.

[Alexis-ROYER]

Just wanted to share a hack on that topic.

I managed to avoid displaying values for all attributes with a single piece of code in my conf.py file.

⚠️ Disables class attribute values by the way,
but I consider in the end that loosing this info is less a pain than having lots of false info for the generally more numerous instance attributes.

# Hack:
# Replace the `sphinx.ext.autodoc.object_description()` function
# in the `sphinx.ext.autodoc` module.
def no_object_description(obj):
    raise ValueError("No value for data/attributes")
import sphinx.ext.autodoc
sphinx.ext.autodoc.object_description = no_object_description

Don't know whether there is a simple and safer way to do this?
I tried to play around :annotation: (see bitbucket#109, or with the autodoc-process-signature handler, but without success.
Let me know.

[tk0miya]

About None value, it was fixed since 3.1.0 (refs: #2044 and #7515).

But the second problem that the autoattribute directive raises an AttributeError for an instance variable is still not fixed.

# index.rst
.. autoclass:: example.Foo

   .. autoattribute:: ivar

# example.py
class Foo:
    def __init__(self):
        #: ivar
        self.ivar = None



md5-cd39f374395eb4b4c261e4f712694457



WARNING: autodoc: failed to import attribute 'Foo.ivar' from module 'example'; the following exception was raised:
Traceback (most recent call last):
  File "/Users/tkomiya/work/sphinx/sphinx/util/inspect.py", line 324, in safe_getattr
    return getattr(obj, name, *defargs)
AttributeError: type object 'Foo' has no attribute 'ivar'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/Users/tkomiya/work/sphinx/sphinx/ext/autodoc/importer.py", line 71, in import_object
    obj = attrgetter(obj, attrname)
  File "/Users/tkomiya/work/sphinx/sphinx/ext/autodoc/__init__.py", line 245, in get_attr
    return autodoc_attrgetter(self.env.app, obj, name, *defargs)
  File "/Users/tkomiya/work/sphinx/sphinx/ext/autodoc/__init__.py", line 2063, in autodoc_attrgetter
    return safe_getattr(obj, name, *defargs)
  File "/Users/tkomiya/work/sphinx/sphinx/util/inspect.py", line 340, in safe_getattr
    raise AttributeError(name) from exc
AttributeError: ivar