Python __doc__ documentation on instances

python __new__
python __getitem__
python __dict__ method
python __class__
python class inheritance
python class variables
python __init__
python private variables

I'd like to provide documentation (within my program) on certain dynamically created objects, but still fall back to using their class documentation. Setting __doc__ seems a suitable way to do so. However, I can't find many details in the Python help in this regard, are there any technical problems with providing documentation on an instance? For example:

class MyClass:
    """
    A description of the class goes here.
    """

a = MyClass()
a.__doc__ = "A description of the object"

print( MyClass.__doc__ )
print( a.__doc__ )

__doc__ is documented as a writable attribute for functions, but not for instances of user defined classes. pydoc.help(a), for example, will only consider the __doc__ defined on the type.

Other protocols (including future use-cases) may reasonably bypass the special attributes defined in the instance dict, too. See Special method lookup section of the datamodel documentation, specifically:

For custom classes, implicit invocations of special methods are only guaranteed to work correctly if defined on an object’s type, not in the object’s instance dictionary.

So, depending on the consumer of the attribute, what you intend to do may not be reliable. Avoid.

A safe and simple alternative is just to use a different attribute name of your own choosing for your own use-case, preferably not using the __dunder__ syntax convention which usually indicates a special name reserved for some specific use by the implementation and/or the stdlib.

9. Classes, Creating a new class creates a new type of object, allowing new instances of that __doc__ is also a valid attribute, returning the docstring belonging to the  Methods only differ from regular functions in that the first argument is reserved for the object instance. By Python convention, the instance reference is called self but may be called this or any other variable name. To support method calls, functions include the __get__() method for binding methods during attribute access. This means that all functions are non-data descriptors which return bound methods when they are invoked from an object.

3. Data model, An object's mutability is determined by its type; for instance, numbers, strings and Special read-only attributes: __doc__ is the function's documentation string,  Python documentation strings (or docstrings) provide a convenient way of associating documentation with Python modules, functions, classes, and methods. An object's docsting is defined by including a string constant as the first statement in the object's definition.

I think it's preferred to keep it under the class via your doc string as it will also aid any developer that works on the code. However if you are doing something dynamic that requires this setup then I don't see any reason why not. Just understand that it adds a level of indirection that makes things less clear to others.

Remember to K.I.S.S. where applicable :)

Python __doc__ documentation on instances, __doc__ is documented as a writable attribute for functions, but not for instances of user defined classes. pydoc. help(a) , for example, will only consider the __doc__ defined on the type. Other protocols (including future use-cases) may reasonably bypass the special attributes defined in the instance dict, too. Module pdoc. Python package pdoc provides types, functions, and a command-line interface for accessing public documentation of Python modules, and for presenting it in a user-friendly, industry-standard open format. It is best suited for small- to medium-sized projects with tidy, hierarchical APIs.

pdoc API documentation, variables (including globals, class variables, and instance variables). Documentation is extracted from live objects' docstrings using Python's __doc__ attribute. Python __doc__ attribute Whenever string literals are present just after the definition of a function, module, class or a method, they are associated with the object as their __doc__ attribute. We can later use this attribute to retrieve this docstring.

Documenting Python Code: A Complete Guide – Real Python, Documenting Your Python Code Base Using Docstrings However, when you start using the library, you look for examples, write-ups, or even Instead of directly manipulating the __doc__ property, the strategic placement of the string literal  Any valid Python identifier may be used for a fieldname except for names starting with an underscore. Valid identifiers consist of letters, digits, and underscores but do not start with a digit or underscore and cannot be a keyword such as class, for, return, global, pass , or raise.

numpydoc docstring guide, Documenting class instances; Documenting generators; Documenting constants We mostly follow the standard Python style conventions as described here: __doc__ ) and, for consistency, is surrounded by triple double quotes, i.e.:. Each class instance can have attributes attached to it for maintaining its state. Class instances can also have methods (defined by its class) for modifying its state. Compared with other programming languages, Python’s class mechanism adds classes with a minimum of new syntax and semantics.

Comments
  • Are you planning on dynamically creating documentation to certain modules?
  • I'm planning on certain dynamically created objects having documentation.
  • I see. I guess you should add this detail to the question, cause that is the only scenario I can think of that will actually make sense.
  • Who is the expected audience for the dynamically created docstrings?
  • Also have a look at this : stackoverflow.com/questions/2693883/dynamic-function-docstring/…