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: 变量的类型 （文本）¶: 这将解析为 Python 表达式，用于交叉引用类型注释。因此，:type: 的参数应为有效的注释表达式。

注意

:type: 指令选项的有效语法与 :type: 信息字段的语法不同。:type: 指令选项不理解 reStructuredText 标记或 or 或 of 关键字，这意味着联合必须使用 |，序列必须使用方括号，并且不能使用诸如 :ref:`...` 之类的角色。

在 2.4 版本中添加。

:value: 变量的初始值 （文本）¶: 在 2.4 版本中添加。

:canonical: （完全限定名称，包括模块名称）¶: 如果对象是从其他模块导入的，则描述对象定义的位置

在 4.0 版本中添加。

.. py:exception:: name¶

.. py:exception:: name(parameters)

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

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

选项

:final: （无值）¶: 指示该类是一个 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()

首选第一种方式。

选项

:abstract: （无值）¶

指示该类是一个抽象基类。这将产生以下输出

abstract class Cheese: 奶酪的表示。

在 8.2 版本中添加。

:canonical: （完全限定名称，包括模块名称）¶: 如果对象是从其他模块导入的，则描述对象定义的位置

在 4.0 版本中添加。

:final: （无值）¶: 指示该类是一个 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: 属性的类型 （文本）¶: 这将解析为 Python 表达式，用于交叉引用类型注释。因此，:type: 的参数应为有效的注释表达式。

注意

:type: 指令选项的有效语法与 :type: 信息字段的语法不同。:type: 指令选项不理解 reStructuredText 标记或 or 或 of 关键字，这意味着联合必须使用 |，序列必须使用方括号，并且不能使用诸如 :ref:`...` 之类的角色。

在 2.4 版本中添加。

:value: 属性的初始值 （文本）¶: 在 2.4 版本中添加。

:canonical: （完全限定名称，包括模块名称）¶: 如果对象是从其他模块导入的，则描述对象定义的位置

在 4.0 版本中添加。

.. py:property:: name¶

描述对象属性。

在 4.0 版本中添加。

选项

:abstract: （无值）¶

:abstractmethod: （无值）¶

指示该属性是抽象的。这将产生以下输出

abstract property Cheese.amount_in_stock: 国家奶酪商场的奶酪库存水平。

在版本 8.2 中更改：也支持 :abstract: 别名。

:classmethod: （无值）¶: 指示该属性是一个类方法。

在 4.2 版本中添加。

:type: 属性的类型 （文本）¶: 这将解析为 Python 表达式，用于交叉引用类型注释。因此，:type: 的参数应为有效的注释表达式。

注意

:type: 指令选项的有效语法与 :type: 信息字段的语法不同。:type: 指令选项不理解 reStructuredText 标记或 or 或 of 关键字，这意味着联合必须使用 |，序列必须使用方括号，并且不能使用诸如 :ref:`...` 之类的角色。

.. 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 签名和信息字段列表。

选项

:abstract: （无值）¶

:abstractmethod: （无值）¶

指示该方法是一个抽象方法。这将产生以下输出

abstractmethod Cheese.order_more_stock(): 订购更多奶酪（我们的新鲜奶酪用完了！）。

在 2.1 版本中添加。

在版本 8.2 中更改：也支持 :abstract: 别名。

:async: （无值）¶: 指示该方法是一个异步方法。

在 2.1 版本中添加。

:canonical: （完全限定名称，包括模块名称）¶: 如果对象是从其他模块导入的，则描述对象定义的位置

在 4.0 版本中添加。

:classmethod: （无值）¶: 指示该方法是一个类方法。

在 2.1 版本中添加。

:final: （无值）¶: 指示该方法是一个 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 角色引用装饰器函数。

: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 版本中添加。

.. py:decoratormethod:: name¶

.. py:decoratormethod:: name(signature)

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

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

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

Python 签名¶

函数、方法和类构造函数的签名可以像在 Python 中编写的那样给出。这可以包括默认值、仅限位置或仅限关键字的参数、类型注解和类型参数。例如

.. py:function:: compile(source: str, filename: Path, symbol: str = 'file') -> ast.AST

compile(source: str, filename: Path, symbol: str = 'file') → ast.AST

对于具有可选参数但没有默认值的函数（通常是在没有关键字参数支持的 C 扩展模块中实现的函数），您可以在单个指令中列出同一签名的多个版本

compile(source)
compile(source, filename)
compile(source, filename, symbol)

另一种方法是使用方括号来指定可选部分。当使用方括号时，习惯上将左方括号放在逗号之前 ([,)。

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: int 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

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

交叉引用 Python 对象¶

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

:py:mod:¶: 引用一个模块；可以使用点分隔的名称。这也应该用于包名称。

:py:func:¶: 引用一个 Python 函数；可以使用点分隔的名称。角色文本不需要包含尾随括号以增强可读性；如果 add_function_parentheses 配置值设置为 True（默认值），Sphinx 将自动添加它们。

:py:deco:¶: 引用一个 Python 装饰器；可以使用点分隔的名称。渲染的输出将在前面加上 at 符号 (@)，例如：:py:deco:`removename` 生成 @removename。

:py:data:¶: 引用模块级别的变量。

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

:py:class:¶: 引用一个类；可以使用点分隔的名称。

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

:py:attr:¶: 引用对象的数据属性。

注意

该角色也能够引用属性（property）。

:py:type:¶: 引用类型别名。

:py:exc:¶: 引用一个异常。可以使用点分隔的名称。

:py:obj:¶: 引用未指定类型的对象。例如，用作 default_role。

在 0.4 版本中添加。

目标规范¶

目标可以指定为完全限定名称（例如 :py:meth:`my_module.MyClass.my_method`）或任何缩短版本（例如 :py:meth:`MyClass.my_method` 或 :py:meth:`my_method`）。有关缩短名称解析的详细信息，请参阅目标解析。

交叉引用修饰符可以应用。简而言之

您可以提供显式标题和引用目标：:py:mod:`mathematical functions <math>` 将引用 math 模块，但链接文本将是 “mathematical functions”。
如果您在内容前加上感叹号 (!)，则不会创建引用/超链接。
如果您在内容前加上 ~，则链接文本将仅是目标的最后一个组成部分。例如，:py:meth:`~queue.Queue.get` 将引用 queue.Queue.get，但仅显示 get 作为链接文本。

目标解析¶

给定的链接目标名称使用以下策略解析为对象

这些角色中的名称首先在没有任何进一步限定的情况下搜索，然后预先添加当前模块名称，然后预先添加当前模块和类名称（如果有）。

如果您在名称前加上点 (.)，则此顺序将反转。例如，在 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()。