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¶

描述模块中的全局数据，包括用作“已定义常量”的变量和值。类和对象属性不在此环境中记录。

选项

:type: type of the variable (text)¶: 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()

第一种方法是首选方法。

选项

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

描述对象数据属性。描述应包括有关预期数据类型以及是否可以直接更改的信息。

选项

:type: type of the attribute (text)¶: 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.

选项

:abstractmethod: (no value)¶: 指示该属性是抽象的。

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

Added in version 4.2.

:type: type of the property (text)¶

.. py:method:: name(parameters)¶

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

描述对象方法。参数不应包括 self 参数。描述应包括与以下描述类似的信息： function .另请参见 python签名和信息字段列表 .

选项

:abstractmethod: (no value)¶: 指示该方法是抽象方法。

Added in version 2.1.

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

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

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

: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:meth 角色。

python签名¶

函数、方法和类构造函数的签名可以像用python编写一样被提供。

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

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

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

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

习惯上把方括号放在逗号之前。

推出了Python3.12 type parameters ，它们是在类或函数定义中直接声明的类型变量：

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

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

相应的reStrutiredText文档将为：

.. py:class:: AnimalList[AnimalT]

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

看见 PEP 695 和 PEP 696 获取详细信息和完整的规格。

信息字段列表¶

Added in version 0.4.

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

在python对象描述指令中，可以很好地识别和格式化具有这些字段的REST字段列表：

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

如果用单词“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 （默认值）。

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

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

:py:class:¶: 引用类；可以使用点式名称。

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

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

备注

该角色还能够引用财产。

:py:exc:¶: 引用异常。可以使用点式名称。

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

Added in version 0.4.

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

通常，首先搜索这些角色中的名称，不需要任何进一步的限定，然后预填当前模块名，然后预填当前模块名和类名（如果有）。如果在名称前面加上一个点，则顺序相反。例如，在python的文档中 codecs 模块， :py:func:`open 总是指内置函数，而 `open`() “指” codecs.open() .

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

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

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

Sphinx

On this page

Site navigation

python域¶

python签名¶

信息字段列表¶

交叉引用python对象¶