autodocs does not work well with instance attributes. #904

shimizukawa · 2015-01-03T01:08:47Z

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

The text was updated successfully, but these errors were encountered:

shimizukawa · 2015-01-03T01:08:48Z

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 · 2015-01-03T01:08:49Z

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

I have same problem :(

shimizukawa · 2015-01-03T01:08:50Z

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

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

→ <<cset 6f9e541>>

shimizukawa · 2015-01-03T01:08:51Z

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 · 2015-01-03T01:08:52Z

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 · 2015-01-03T01:09:53Z

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.

alxroyer · 2020-06-10T07:26:06Z

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 · 2020-07-11T17:33:53Z

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

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

…utofunction So far, autofunction only checks the existence of the class variable. As a result, it crashes with AttributeError if an instance variable is specified. This adds an exisitence for instance attributes via ModuleAnalyzer before getattr-check.

g6ai · 2021-05-26T09:53:29Z

@tk0miya Thanks for the contribution! I still encounter AttributeError when trying to use autoattribute directive for an instance variable, with Sphinx 4.0.2

tk0miya · 2021-05-29T16:58:10Z

@g6ai Could you file a new issue, please? I'd like to know what is happened on your PC.

g6ai · 2021-05-29T23:57:52Z

@tk0miya Please see issue #9283 I just opened.

shimizukawa added type:bug extensions:autodoc labels Jan 3, 2015

alixdamman mentioned this issue Jun 12, 2017

fix #301 : added .axes in API documentation larray-project/larray#311

Merged

abchenson mentioned this issue Feb 1, 2018

autosummary not listing attributes #4534

Open

kotfu mentioned this issue Nov 30, 2019

Documenting Attributes python-cmd2/cmd2#821

Closed

po09i mentioned this issue Jan 21, 2020

Implement API and user documentation shimming-toolbox/shimming-toolbox-matlab#37

Closed

tk0miya added this to the 3.2.0 milestone Jun 10, 2020

tk0miya mentioned this issue Jul 12, 2020

Fix #904: autodoc: An instance attribute cause a crash of autofunction #7946

Merged

tk0miya closed this as completed in 8c8943f Jul 16, 2020

g6ai mentioned this issue May 29, 2021

AttributeError when trying to use autoattribute directive for an instance variable #9283

Closed

github-actions bot locked as resolved and limited conversation to collaborators Jul 10, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

autodocs does not work well with instance attributes. #904

autodocs does not work well with instance attributes. #904

shimizukawa commented Jan 3, 2015

shimizukawa commented Jan 3, 2015

shimizukawa commented Jan 3, 2015

shimizukawa commented Jan 3, 2015

shimizukawa commented Jan 3, 2015

shimizukawa commented Jan 3, 2015

shimizukawa commented Jan 3, 2015

alxroyer commented Jun 10, 2020

tk0miya commented Jul 11, 2020

g6ai commented May 26, 2021

tk0miya commented May 29, 2021

g6ai commented May 29, 2021

autodocs does not work well with instance attributes. #904

autodocs does not work well with instance attributes. #904

Comments

shimizukawa commented Jan 3, 2015

shimizukawa commented Jan 3, 2015

Test 7

Attributes

Test 8

shimizukawa commented Jan 3, 2015

shimizukawa commented Jan 3, 2015

shimizukawa commented Jan 3, 2015

shimizukawa commented Jan 3, 2015

shimizukawa commented Jan 3, 2015

alxroyer commented Jun 10, 2020

tk0miya commented Jul 11, 2020

g6ai commented May 26, 2021

tk0miya commented May 29, 2021

g6ai commented May 29, 2021