Python领域¶

Added in version 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)¶: 指定该函数是一个指定函数。

Added in version 2.1.

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

Added in version 4.0.

:single-line-parameter-list: (no value)¶: 确保函数的参数将在单个逻辑行上发出，重写 python_maximum_signature_line_length 和 maximum_signature_line_length .

Added in version 7.1.

:single-line-type-parameter-list: (no value)¶: 确保在单个逻辑行上发出函数的类型参数，重写 python_maximum_signature_line_length 和 maximum_signature_line_length .

Added in version 7.1.

.. py:data:: name¶

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

选项

:type: type of the variable (text)¶: 这将被解析为Python表达，用于交叉引用类型注释。因此，论点是 :type: 应当是有效的 annotation expression .

小心

的有效语法 :type: directive option differs from the syntax for the :type: info field .的 :type: 指令选项不理解reStructuredtext标记或 or 或 of 关键词，这意味着工会必须使用 | 和序列必须使用方括号，而角色，如 :ref:`... '不能使用。

Added in version 2.4.

:value: initial value of the variable (text)¶: Added in version 2.4.

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

Added in version 4.0.

.. py:exception:: name¶

.. py:exception:: name(parameters)

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

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

选项

:final: (no value)¶: 默认该课程是最后一堂课。

Added in version 3.1.

:single-line-parameter-list: (no value)¶: 看到 py:class:single-line-parameter-list .

Added in version 7.1.

:single-line-type-parameter-list: (no value)¶: 看到 py:class:single-line-type-parameter-list .

Added in version 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)¶

验证该类是抽象Base。这将产生以下输出：

abstract class Cheese: 俗气的代表。

Added in version 8.2.

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

Added in version 4.0.

:final: (no value)¶: 默认该课程是最后一堂课。

Added in version 3.1.

:single-line-parameter-list: (no value)¶: 确保类构造函数的参数将在单个逻辑行上发出，重写 python_maximum_signature_line_length 和 maximum_signature_line_length .

Added in version 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: directive option differs from the syntax for the :type: info field .的 :type: 指令选项不理解reStructuredtext标记或 or 或 of 关键词，这意味着工会必须使用 | 和序列必须使用方括号，而角色，如 :ref:`... '不能使用。

Added in version 2.4.

:value: initial value of the attribute (text)¶: Added in version 2.4.

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

Added in version 4.0.

.. py:property:: name¶

描述对象属性。

Added in version 4.0.

选项

:abstract: (no value)¶

:abstractmethod: (no value)¶

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

abstract property Cheese.amount_in_stock: 奶酪含量 National Cheese Emporium .

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

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

Added in version 4.2.

:type: type of the property (text)¶: 这将被解析为Python表达，用于交叉引用类型注释。因此，论点是 :type: 应当是有效的 annotation expression .

小心

的有效语法 :type: directive option differs from the syntax for the :type: info field .的 :type: 指令选项不理解reStructuredtext标记或 or 或 of 关键词，这意味着工会必须使用 | 和序列必须使用方括号，而角色，如 :ref:`... '不能使用。

.. py:type:: name¶

描述一个 type alias .

别名所代表的类型应使用 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]¶: 表示正则运算式或已编译模式。

Added in version 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(): 多点奶酪（我们刚卖完！）。

Added in version 2.1.

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

:async: (no value)¶: 卸载该方法是一种卸载方法。

Added in version 2.1.

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

Added in version 4.0.

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

Added in version 2.1.

:final: (no value)¶: 验证该方法是最终方法。

Added in version 3.1.

:single-line-parameter-list: (no value)¶: 确保方法的参数将在单个逻辑行上发出，重写 python_maximum_signature_line_length 和 maximum_signature_line_length .

Added in version 7.1.

:single-line-type-parameter-list: (no value)¶: 确保方法的类型参数在单个逻辑行上发出，重写 python_maximum_signature_line_length 和 maximum_signature_line_length .

Added in version 7.2.

:staticmethod: (no value)¶: 指定该方法是静态方法。

Added in version 2.1.

.. py:staticmethod:: name(parameters)¶
.. py:staticmethod:: name[type parameters](parameters): 像 py:method ，但表明该方法是静态方法。

Added in version 0.4.

.. py:classmethod:: name(parameters)¶
.. py:classmethod:: name[type parameters](parameters): 像 py:method ，但表明该方法是类方法。

Added in version 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*.

(as反对 .. py:decorator:: removename(func) .)

使用引用装饰器函数 py:deco 作用

:single-line-parameter-list: (no value)¶: 确保装饰者的参数将在单个逻辑行上发出，重写 python_maximum_signature_line_length 和 maximum_signature_line_length .

Added in version 7.1.

:single-line-type-parameter-list: (no value)¶: 确保装饰器的类型参数在单个逻辑行上发出，重写 python_maximum_signature_line_length 和 maximum_signature_line_length .

Added in version 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 type parameters ，它们是直接在类或函数定义中声明的类型变量：

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

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

相应的reStructured文本标记将是：

.. py:class:: AnimalList[AnimalT]

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

参见

PEP 695 和 PEP 696 ，了解详细信息和完整规范。

信息字段列表¶

Added in version 0.4.

在 3.0 版本发生变更: 添加Meta字段。

在Python对象描述指令中，包含这些字段的reStructuredtext字段列表可以很好地识别和格式化：

param , parameter , arg , argument , key , keyword ：参数的描述。
type ：参数的类型。如果可能的话创建链接。
raises , raise , except , exception ：（以及何时）提出特定的例外。
var , ivar , cvar ：变量的描述。
vartype ：变量的类型。如果可能的话创建链接。
returns , return ：返回值的描述。
rtype ：返回类型。如果可能的话创建链接。
meta ：将元数据添加到Python对象的描述中。元数据不会显示在输出文档上。例如， :meta private: 指示pPython对象是私有成员。它用于 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])¶

向收件人发送消息

参数:

sender (str) -- 发送消息的人
recipient (str) -- 消息的接收者
message_body (str) -- 消息的主体
priority (int or None) -- 消息的优先级可以是数字1-5

返回:

消息id

返回类型:

int

抛出:

ValueError -- 如果Message_body超过160个字符
TypeError -- 如果Message_body不是基字符串

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

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

Added in version 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]

类型字段中的多个类型如果用竖条分隔，将自动链接 (| ）或单词“或”：：

: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 (the默认）。

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

Added in version 0.4.

目标规格¶

目标可以指定为完全限定名称（例如 :py:meth:`my_module.MyClass.my_method ) or any shortened version (e.g. `MyClass.my_method``() or :py:meth:`my_method`). See target resolution 了解有关缩写名称的详细信息。

Cross-referencing modifiers 可以应用。简而言之：

您可以提供明确的标题和引用目标： :py:mod:`mathematical functions <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的警告。

请注意，您可以将 ~ and . 前置： :py:meth:`~.TarFile.close '将参考 tarfile.TarFile.close() 方法，但可见链接标题将仅为 close() .