Python 域¶
版本 1.0 新增。
Python 域（名称 py）为模块声明提供以下指令：
- .. py:module:: name¶
此指令标记模块（或包子模块，此时名称应完全限定，包括包名）描述的开始。模块的描述（例如 docstring）可以放在指令的正文中。
此指令还会在全局模块索引中创建一个条目。
版本 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: (无值)¶
指示类是最终类。
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: (无值)¶
指示类是最终类。
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 版新增。
- .. 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: (无值)¶
指示方法是最终方法。
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
对于没有默认值的可选参数函数（通常是 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
信息字段列表¶
版本 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 都表示为“变量”。它们之间没有任何区别。
字段名必须由这些关键字之一和参数组成（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])¶
向收件人发送消息
还可以组合参数类型和描述，如果类型是单个词，例如这样：
: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 装饰器；可以使用带点的名称。渲染的输出将以 @ 符号 (
@) 开头，例如：:py:deco:`removename`生成@removename。
- :py:data:¶
引用模块级变量。
- :py:const:¶
引用一个“定义”常量。这可能是一个不打算更改的 Python 变量。
- :py:class:¶
引用一个类；可以使用带点的名称。
- :py:meth:¶
引用对象的方法。角色文本可以包括类型名和方法名；如果它出现在类型描述中，可以省略类型名。可以使用带点的名称。
- :py:attr:¶
引用对象的数据属性。
注意
该角色也能够引用属性。
- :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()。