How to write a named tuple document in 2020

I learned from a PR that the namedtuple attribute is automatically set to the docstring "Alias for field number xx".

$ python
Python 3.8.1 (default, Feb 13 2020, 13:34:23)
[Clang 11.0.0 (clang-1100.0.33.17)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> from collections import namedtuple
>>>
>>> Coordinate = namedtuple('Coordinate', 'X Y')
>>> Coordinate.__doc__
'Coordinate(X, Y)'
>>> Coordinate.X.__doc__
'Alias for field number 0'
>>> Coordinate.Y.__doc__
'Alias for field number 1'

If you process this class with Sphinx (autodoc) and generate a document, the following document will be generated. スクリーンショット 2020-03-15 11.40.30.png

Although the amount of information is small, I have created a document that uses paper.

Looking back

Approach to erase docstring

The workaround for this issue is the code introduced in Removing namedtuple docstrings for Sphinx. If you find the attribute of namedtuple, delete it. You can simplify redundant documents by including this [^ 1].

[^ 1]: On the other hand, this approach has the disadvantage that the mapping between the namedtuple position and the attribute name is difficult to understand because autodoc sorts the attributes alphabetically if nothing is specified. I'm a little confused about what to do with Sphinx itself.

An approach to writing attribute documentation with docstring

Also, in How to write a docstring to create a namedtuple document with sphinx, the approach is to describe the document of each attribute with the docstring of the generated class. Introduced.

class NamedTupleWithDocstring2(namedtuple("NamedTuple", "aaa bbb ccc")):
    """
    hogehoge

    .. py:attribute:: aaa

        Description of the ``aaa``.

    .. py:attribute:: bbb

        Description of the ``bbb``.

    .. py:attribute:: ccc

        Description of the ``ccc``.
    """

I see, you can insert any description in this case.

How do you write now?

You can freely control the document in various ways of writing with docstring, but the code is verbose. If you have Python 3.6 or higher and Sphinx 2.4, it's a little simpler to write.

Using variable annotations introduced in Python 3.6, namedtuple and its documentation can be written as:

from typing import NamedTuple

class Coordinate(NamedTuple):
    """A 2-dimension coordinate."""

    X: float  #: the coordinate on X-axis
    Y: float  #: the coordinate on Y-axis

And if you use Sphinx 2.4, the #: comment attached to this variable annotation will be interpreted as a docstring, so if you process the above code with Sphinx, it will be converted as follows. スクリーンショット 2020-03-15 12.02.54.png

Let's aim for smart code and smart documents with new features.

Recommended Posts

How to write a named tuple document in 2020
How to write a docstring to create a named tuple document with sphinx
How to write a Python class
How to write soberly in pandas
How to output a document in pdf format with Sphinx
Qiita (1) How to write a code name
How to write Python document comments (Docstrings)
How to get a stacktrace in python
How to write this process in Perl?
How to write Ruby to_s in Python
How to clear tuples in a list (Python)
How to create a JSON file in Python
How to write regular expression patterns in Linux
How to implement a gradient picker in Houdini
How to write a ShellScript Bash for statement
How to notify a Discord channel in Python
How to write a string when there are multiple lines in python
[Python] How to draw a histogram in Matplotlib
How to create a Rest Api in Django
How to write async and await in Vue.js
How to count numbers in a specific range
[Go] How to write or call a function
How to read a file in a different directory
How to Mock a Public function in Pytest
How to write a ShellScript bash case statement
How to specify a schema in Django's database settings
20th Offline Real-time How to Write Problems in Python
How to convert / restore a string with [] in python
How to write a GUI using the maya command
How to write string concatenation in multiple lines in Python
I want to write in Python! (2) Let's write a test
[Python] How to expand variables in a character string
How to write a list / dictionary type of Python3
A memorandum on how to use keras.preprocessing.image in Keras
How to display DataFrame as a table in Markdown
[Python] How to write a docstring that conforms to PEP8
How to execute a command using subprocess in Python
How to reference static files in a Django project
[Linux] How to put your IP in a variable
XPath Basics (2) -How to write XPath
How to call a function
How to hack a terminal
How to slice a block multiple array from a multiple array in Python
How to import NoteBook as a module in Jupyter (IPython)
A story about how to specify a relative path in python.
It's hard to write a very simple algorithm in php
How to use the __call__ method in a Python class
How to import a file anywhere you like in Python
[Python] How to write an if statement in one sentence.
How to temporarily implement a progress bar in a scripting language
How to define multiple variables in a python for statement
A note on how to load a virtual environment in PyCharm
I tried "How to get a method decorated in Python"
How to develop in a virtual environment of Python [Memo]
How to generate a query using the IN operator in Django
How to write a test for processing that uses BigQuery
How to check if a value exists in an enum
How to get the last (last) value in a list in Python
I'll never forget how to write a shell script, don't forget! !!
How to get a list of built-in exceptions in python
To write a test in Go, first design the interface