Python 领域

版本 1.0 中新增。

Python 领域（名称为 **py**）为模块声明提供了以下指令

.. py:module:: name

此指令标志着模块（或包子模块，在这种情况下，名称应为完全限定的，包括包名称）描述的开始。模块的描述，例如文档字符串，可以放在指令的主体中。

此指令还会在全局模块索引中创建条目。

版本 5.2 中更改： 模块指令支持主体内容。

选项

:platform: platforms (逗号 分隔 列表)

指示模块可用的平台（如果它在所有平台上都可用，则应省略此选项）。键是简短的标识符；正在使用的示例包括“IRIX”、“Mac”、“Windows”和“Unix”。在适用时使用已使用的键非常重要。

:synopsis: purpose (文本)

由一句话描述模块的目的组成 - 它目前仅用于全局模块索引。

:deprecated: (无 参数)

将模块标记为已弃用；然后它将在各个位置被指定为已弃用。

.. py:currentmodule:: name

此指令告诉 Sphinx 从此处记录的类、函数等位于给定模块中（如 py:module），但它不会创建索引条目、全局模块索引中的条目或 py:mod 的链接目标。这在模块中事物的文档分散在多个文件或部分中的情况下很有用 - 一个位置具有 py:module 指令，其他位置仅具有 py:currentmodule。

以下指令用于模块和类内容

.. py:function:: name(parameters)
.. py:function:: name[type parameters](parameters)

描述模块级函数。签名应包含参数以及可选的类型参数，如 Python 函数定义中给出的，请参见 Python 签名。例如

.. py:function:: Timer.repeat(repeat=3, number=1_000_000)
.. py:function:: add[T](a: T, b: T) -> T

对于方法，您应该使用 py:method。

描述通常包括有关所需参数及其使用方法的信息（尤其是在作为参数传递的可变对象是否被修改）、副作用和可能的异常。

此信息可以在（任何 py 指令中）可选地以结构化形式给出，请参见 信息字段列表。

选项

:async: (无 值)

指示函数是异步函数。

版本 2.1 中新增。

:canonical: (包含 模块 名称的 完全限定 名称)

如果对象是从其他模块导入的，则描述对象定义的位置

版本 4.0 中新增。

:single-line-parameter-list: (无 值)

确保函数的参数将在一行逻辑线上发出，覆盖 python_maximum_signature_line_length 和 maximum_signature_line_length。

版本 7.1 中新增。

:single-line-type-parameter-list: (无 值)

确保函数的类型参数在一行逻辑线上发出，覆盖 python_maximum_signature_line_length 和 maximum_signature_line_length。

版本 7.1 中新增。

.. py:data:: name

描述模块中的全局数据，包括变量和用作“已定义常量”的值。考虑使用 py:type 来代替类型别名，并使用 py:attribute 来代替类变量和实例属性。

选项

:type: 变量的 类型 (文本)

版本 2.4 中新增。

:value: 变量的 初始 值 (文本)

版本 2.4 中新增。

:canonical: (包含 模块 名称的 完全限定 名称)

如果对象是从其他模块导入的，则描述对象定义的位置

版本 4.0 中新增。

.. py:exception:: name
.. py:exception:: name(parameters)
.. py:exception:: name[type parameters](parameters)

描述异常类。签名可以但不必包含带构造函数参数的括号，或者可以选择包含类型参数（参见 PEP 695）。

选项

:final: (无 值)

指示类是最终类。

版本 3.1 中新增。

:single-line-parameter-list: (无 值)

参见 py:class:single-line-parameter-list。

版本 7.1 中新增。

:single-line-type-parameter-list: (无 值)

参见 py:class:single-line-type-parameter-list。

版本 7.1 中新增。

.. py:class:: name
.. py:class:: name(parameters)
.. py:class:: name[type parameters](parameters)

描述一个类。签名可以包含类型参数（参见 PEP 695）或带参数的圆括号，这些参数将显示为构造函数参数。另请参见 Python 签名。

属于该类的 方法和属性 应放在此指令的主体中。如果它们放在外部，则提供的名称应包含类名，以便交叉引用仍然有效。示例

.. py:class:: Foo

   .. py:method:: quux()

-- or --

.. py:class:: Bar

.. py:method:: Bar.quux()

第一种方法是首选方法。

选项

:canonical: (包含 模块 名的 完整 限定 名称)

如果对象是从其他模块导入的，则描述对象定义的位置

版本 4.0 中新增。

:final: (无 值)

指示类是最终类。

版本 3.1 中新增。

:single-line-parameter-list: (无 值)

确保类的构造函数的参数将输出在一行上，覆盖 python_maximum_signature_line_length 和 maximum_signature_line_length。

版本 7.1 中新增。

:single-line-type-parameter-list: (无 值)

确保类的类型参数输出在一行上，覆盖 python_maximum_signature_line_length 和 maximum_signature_line_length。

.. py:attribute:: name

描述对象数据属性。描述应包含有关预期数据类型以及是否可以直接更改的信息。类型别名应使用 py:type 进行记录。

选项

:type: 属性的 类型 (文本)

版本 2.4 中新增。

:value: 属性的 初始 值 (文本)

版本 2.4 中新增。

:canonical: (包含 模块 名的 完整 限定 名称)

如果对象是从其他模块导入的，则描述对象定义的位置

版本 4.0 中新增。

.. py:property:: name

描述对象属性。

版本 4.0 中新增。

选项

:abstractmethod: (无 值)

指示属性是抽象的。

:classmethod: (无 值)

指示属性是类方法。

版本 4.2 中新增。

:type: 属性的 类型 (文本)
.. py:type:: name

描述一个 类型别名。

别名表示的类型应使用 canonical 选项进行描述。此指令支持可选的描述主体。

例如

.. py:type:: UInt64

   Represent a 64-bit positive integer.

将呈现如下

type UInt64

表示 64 位正整数。

选项

:canonical: (文本)

此别名表示的规范类型，例如

.. py:type:: StrPattern
   :canonical: str | re.Pattern[str]

   Represent a regular expression or a compiled pattern.

这将呈现为

type StrPattern = str | re.Pattern[str]

表示正则表达式或编译模式。

版本 7.4 中新增。

.. py:method:: name(parameters)
.. py:method:: name[type parameters](parameters)

描述对象方法。参数不应包含 self 参数。描述应包含与 function 中描述的类似信息。另请参见 Python 签名 和 信息字段列表。

选项

:abstractmethod: (无 值)

指示方法是抽象方法。

版本 2.1 中新增。

:async: (无 值)

指示方法是异步方法。

版本 2.1 中新增。

:canonical: (包含 模块 名的 完整 限定 名称)

如果对象是从其他模块导入的，则描述对象定义的位置

版本 4.0 中新增。

:classmethod: (无 值)

指示方法是类方法。

版本 2.1 中新增。

:final: (无 值)

指示方法是最终方法。

版本 3.1 中新增。

:single-line-parameter-list: (无 值)

确保方法的参数将输出在一行上，覆盖 python_maximum_signature_line_length 和 maximum_signature_line_length。

版本 7.1 中新增。

:single-line-type-parameter-list: (无 值)

确保方法的类型参数输出在一行上，覆盖 python_maximum_signature_line_length 和 maximum_signature_line_length。

版本 7.2 中新增。

:staticmethod: (无 值)

指示方法是静态方法。

版本 2.1 中新增。

.. py:staticmethod:: name(parameters)
.. py:staticmethod:: name[type parameters](parameters)

类似于 py:method，但指示该方法是静态方法。

版本 0.4 中新增。

.. py:classmethod:: name(parameters)
.. py:classmethod:: name[type parameters](parameters)

类似于 py:method，但表示该方法是类方法。

版本 0.6 中新增。

.. py:decorator:: name
.. py:decorator:: name(parameters)
.. py:decorator:: name[type parameters](parameters)

描述一个装饰器函数。签名应表示其作为装饰器的用法。例如，给定以下函数：

def removename(func):
    func.__name__ = ''
    return func

def setnewname(name):
    def decorator(func):
        func.__name__ = name
        return func
    return decorator

描述应如下所示：

.. py:decorator:: removename

   Remove name of the decorated function.

.. py:decorator:: setnewname(name)

   Set name of the decorated function to *name*.

(而不是 .. py:decorator:: removename(func).)

没有 py:deco 角色链接到用此指令标记的装饰器；而是使用 py:func 角色。

:single-line-parameter-list: (no value)

确保装饰器的参数将在一个逻辑行上输出，覆盖 python_maximum_signature_line_length 和 maximum_signature_line_length。

版本 7.1 中新增。

:single-line-type-parameter-list: (no value)

确保装饰器的类型参数将在一个逻辑行上输出，覆盖 python_maximum_signature_line_length 和 maximum_signature_line_length。

版本 7.2 中新增。

.. py:decoratormethod:: name
.. py:decoratormethod:: name(signature)
.. py:decoratormethod:: name[type parameters](signature)

与 py:decorator 相同，但适用于作为方法的装饰器。

使用 py:meth 角色引用装饰器方法。

Python 签名

函数、方法和类构造函数的签名可以像在 Python 中编写的那样给出。

可以给出可选参数的默认值（但如果它们包含逗号，则会使签名解析器混淆）。Python 3 样式的参数注释以及返回类型注释也可以给出。

.. py:function:: compile(source : string, filename, symbol='file') -> ast object

对于没有默认值的可选参数的函数（通常是在没有关键字参数支持的 C 扩展模块中实现的函数），可以使用括号指定可选部分。

compile(source[, filename[, symbol]])

习惯上将开括号放在逗号之前。

Python 3.12 引入了 *类型参数*，它们是在类或函数定义中直接声明的类型变量。

class AnimalList[AnimalT](list[AnimalT]):
   ...

def add[T](a: T, b: T) -> T:
   return a + b

相应的 reStructuredText 文档将是：

.. py:class:: AnimalList[AnimalT]

.. py:function:: add[T](a: T, b: T) -> T

有关详细信息和完整规范，请参阅 PEP 695 和 PEP 696。

信息字段列表

版本 0.4 中新增。

版本 3.0 中已更改: 添加了元数据字段。

在 Python 对象描述指令内，识别具有以下字段的 reStructuredText 字段列表并以良好的格式进行格式化。

  • param、parameter、arg、argument、key、keyword：参数的描述。

  • type：参数的类型。如果可能，会创建一个链接。

  • raises、raise、except、exception：引发特定异常的时机和原因。

  • var、ivar、cvar：变量的描述。

  • vartype：变量的类型。如果可能，会创建一个链接。

  • returns、return：返回值的描述。

  • rtype：返回类型。如果可能，会创建一个链接。

  • meta：向 Python 对象的描述中添加元数据。元数据不会显示在输出文档中。例如，:meta private: 表示 Python 对象是私有成员。它在 sphinx.ext.autodoc 中用于过滤成员。

注意

在当前版本中，所有 var、ivar 和 cvar 都表示为“Variable”。它们之间没有任何区别。

字段名称必须由这些关键字之一和一个参数组成（returns 和 rtype 除外，它们不需要参数）。这可以通过一个示例来最好地解释。

.. py:function:: send_message(sender, recipient, message_body, [priority=1])

   Send a message to a recipient

   :param str sender: The person sending the message
   :param str recipient: The recipient of the message
   :param str message_body: The body of the message
   :param priority: The priority of the message, can be a number 1-5
   :type priority: integer or None
   :return: the message id
   :rtype: int
   :raises ValueError: if the message_body exceeds 160 characters
   :raises TypeError: if the message_body is not a basestring

这将呈现如下：

send_message(sender, recipient, message_body[, priority=1])

向收件人发送消息。

参数：

  • **sender** (str) – 发送消息的人。

  • **recipient** (str) – 消息的收件人。

  • **message_body** (str) – 消息正文。

  • **priority** (int 或 None) – 消息的优先级，可以是 1-5 之间的数字。

返回值：

消息 ID。

返回类型：

int

引发：

  • ValueError – 如果 message_body 超过 160 个字符。

  • TypeError – 如果 message_body 不是 basestring。

如果类型是单个单词，也可以将参数类型和描述组合起来，如下所示：

:param int priority: The priority of the message, can be a number 1-5

版本 1.5 中新增。

可以使用以下语法自动链接列表和字典等容器类型。

:type priorities: list(int)
:type priorities: list[int]
:type mapping: dict(str, int)
:type mapping: dict[str, int]
:type point: tuple(float, float)
:type point: tuple[float, float]

如果类型字段中的多个类型用“or”分隔，则会自动链接。

:type an_arg: int or None
:vartype a_var: str or int
:rtype: float or str

交叉引用 Python 对象

以下角色引用模块中的对象，如果找到匹配的标识符，则可能会创建超链接。

:py:mod:

引用模块；可以使用点分名称。这也应用于包名称。

:py:func:

引用 Python 函数；可以使用点分名称。角色文本不需要包含尾随括号以提高可读性；如果 add_function_parentheses 配置值设置为 True（默认值），则 Sphinx 会自动添加它们。

:py:data:

引用模块级变量。

:py:const:

引用“已定义”的常量。这可能是一个不打算更改的 Python 变量。

:py:class:

引用类；可以使用点分名称。

:py:meth:

引用对象的某个方法。角色文本可以包含类型名称和方法名称；如果它出现在类型的描述中，则可以省略类型名称。可以使用点分名称。

:py:attr:

引用对象的某个数据属性。

注意

此角色还可以引用属性。

:py:type:

引用类型别名。

:py:exc:

引用异常。可以使用点分名称。

:py:obj:

引用类型未指定的某个对象。例如，可用作default_role。

版本 0.4 中新增。

此标记中包含的名称可以包括模块名称和/或类名称。例如，:py:func:`filter`可以引用当前模块中名为filter的函数，或该名称的内置函数。相反，:py:func:`foo.filter`明确引用foo模块中的filter函数。

通常，这些角色中的名称首先在没有任何进一步限定的情况下进行搜索，然后在前面加上当前模块名称，然后在前面加上当前模块和类名称（如果有）。如果在名称前加上点，则此顺序将反转。例如，在 Python 的codecs模块的文档中，:py:func:`open`始终引用内置函数，而:py:func:`.open`引用codecs.open()。

类似的启发式方法用于确定名称是否是当前记录的类的属性。

此外，如果名称前缀为点，并且找不到完全匹配项，则目标将作为后缀，并搜索所有具有该后缀的对象名称。例如，:py:meth:`.TarFile.close`引用tarfile.TarFile.close()函数，即使当前模块不是tarfile。由于这可能会变得模棱两可，如果有多个可能的匹配项，您将收到来自 Sphinx 的警告。

请注意，您可以组合~和.前缀：:py:meth:`~.TarFile.close`将引用tarfile.TarFile.close()方法，但可见链接标题将仅为close()。