Python域¶

在 1.0 版本加入.

Python域(名为 py)为模块声明提供了以下指令:

.. py:module:: name¶

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

该指令还将导致全局模块索引中的条目。

在 5.2 版本发生变更: 模块指令支持正文内容。

选项

:platform: platforms (comma separated list)¶: 指出模块可用的平台（如果它在所有平台上都可用，该选项应被省略）。键是短的标识符;使用中的例子包括"IRIX"、"Mac"、"Windows"和"Unix"。在适当的时候使用已经使用过的密钥是重要的。

:synopsis: purpose (text)¶: 由描述模块用途的一句话组成——它目前只在全局模块索引中使用。

:deprecated: (no argument)¶: 将模块标记为已弃用；届时，它将在不同的地点被指定为这样的场所。

.. 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: (no value)¶: 指出该函数是一个异步函数。

在 2.1 版本加入.

:canonical: (full qualified name including module name)¶: 如果对象是从其他模块导入的，请描述定义对象的位置。

在 4.0 版本加入.

: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.1 版本加入.

.. py:data:: name¶

描述模块中的全局数据，包括用作“定义常量”的变量和值。考虑改用 py:type 用于类型别名，以及 py:attribute 用于类变量和实例属性。

选项

:type: type of the variable (text)¶: 被解析为用于交叉引用类型注释的Python表达式。因此:type:的参数应为有效的annotation expression。

小心

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

在 2.4 版本加入.

:value: initial value of the variable (text)¶: 在 2.4 版本加入.

:canonical: (full qualified name including module name)¶: 如果对象是从其他模块导入的，请描述定义对象的位置。

在 4.0 版本加入.

.. py:exception:: name¶

.. py:exception:: name(parameters)

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

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

选项

:final: (no value)¶: 指明这个类是最后一个类。

在 3.1 版本加入.

:single-line-parameter-list: (no value)¶: 参见 py:class:single-line-parameter-list 。

在 7.1 版本加入.

:single-line-type-parameter-list: (no value)¶: 参见 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: (no value)¶

指明该类是一个抽象基类。这会产生以下输出：

abstract class Cheese: 一个奶酪的表现。

在 8.2 版本加入.

:canonical: (full qualified name including module name)¶: 如果对象是从其他模块导入的，请描述定义对象的位置。

在 4.0 版本加入.

:final: (no value)¶: 指明这个类是最后一个类。

在 3.1 版本加入.

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

.. py:attribute:: name¶

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

选项

:type: type of the attribute (text)¶: 被解析为用于交叉引用类型注释的Python表达式。因此:type:的参数应为有效的annotation expression。

小心

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

在 2.4 版本加入.

:value: initial value of the attribute (text)¶: 在 2.4 版本加入.

:canonical: (full qualified name including module name)¶: 如果对象是从其他模块导入的，请描述定义对象的位置。

在 4.0 版本加入.

.. py:property:: name¶

描述一个对象的属性。

在 4.0 版本加入.

选项

:abstract: (no value)¶

:abstractmethod: (no value)¶

指明该属性是抽象的。这会产生以下输出：

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

在 8.2 版本发生变更: 也支持 :abstract: 别名。

:classmethod: (no value)¶: 指明该属性是一个类方法。

在 4.2 版本加入.

:type: type of the property (text)¶: 被解析为用于交叉引用类型注释的Python表达式。因此:type:的参数应为有效的annotation expression。

小心

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

.. py:type:: name¶

描述一个类型别名。

应使用 canonical 选项描述别名所表示的类型。该指令支持可选的描述正文。

例如：

.. py:type:: UInt64

   Represent a 64-bit positive integer.

将呈现如下：

type UInt64¶: 表示一个64位的正整数。

选项

:canonical: (text)¶

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

.. 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: (no value)¶

:abstractmethod: (no value)¶

指明该方法是一个抽象方法。这会产生以下输出：

abstractmethod Cheese.order_more_stock(): 订购更多奶酪（我们已经卖完了！）。

在 2.1 版本加入.

在 8.2 版本发生变更: 也支持 :abstract: 别名。

:async: (no value)¶: 指明该方法是一个异步方法。

在 2.1 版本加入.

:canonical: (full qualified name including module name)¶: 如果对象是从其他模块导入的，请描述定义对象的位置。

在 4.0 版本加入.

:classmethod: (no value)¶: 指明该方法是一个类方法。

在 2.1 版本加入.

:final: (no value)¶: 指明该方法是最后一个方法。

在 3.1 版本加入.

: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 版本加入.

:staticmethod: (no value)¶: 指明该方法是抽象方法。

在 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: (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: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 or None) -- 消息的优先级可以是1-5

返回:

消息ID

返回类型:

int

抛出:

ValueError -- 如果信息主体超过160个字符
TypeError -- 如果信息主体不是基本字符串

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

: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:¶: 引用对象的数据属性。

备注

也可以指向属性。

: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`)。有关缩短名称解析，详见target resolution。

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

您可以提供一个显式的标题和参考目标： :py:mod:`数学函数 <math>` 将引用 math 模块，但链接文本将是"数学函数"。
如果您在内容前加上感叹号(!)，则不会创建引用/超链接。
如果您在内容前加上 ~，链接文本将仅是目标的最后一个组件。例如， :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() 。