Python域¶

Added in version 1.0.

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

.. py:module:: name¶

This directive marks the beginning of the description of a module (or package submodule, in which case the name should be fully qualified, including the package name). A description of the module such as the docstring can be placed in the body of the directive.

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

在 5.2 版本发生变更: Module directives support body content.

选项

: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 指令，其他只有:rst:dir:py:currentmodule 。

为模块和类内容提供以下指令：

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

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

Describes a module-level function. The signature should include the parameters, together with optional type parameters, as given in the Python function definition, see Python签名. For example:

.. py:function:: Timer.repeat(repeat=3, number=1_000_000)
.. py:function:: add[T](a: T, b: T) -> T

您应该使用的方法 py:method 。

描述通常包括有关所需参数及其使用方式的信息（特别是是否修改了作为参数传递的可变对象，副作用和可能的异常。

这个信息可以(在任何 “py” 指令中)可选地以结构化形式给出，参见:ref:`信息字段列表 `。

选项

: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)¶: Ensures that the function’s arguments will be emitted on a single logical line, overriding python_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.

:single-line-type-parameter-list: (no value)¶: Ensure that the function’s type parameters are emitted on a single logical line, overriding python_maximum_signature_line_length and 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)

Describes an exception class. The signature can, but need not include parentheses with constructor arguments, or may optionally include type parameters (see PEP 695).

选项

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

Added in version 3.1.

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

Added in version 7.1.

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

Describes a class. The signature can optionally include type parameters (see PEP 695) or parentheses with parameters which will be shown as the constructor arguments. See also 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)¶: Ensures that the class constructor’s arguments will be emitted on a single logical line, overriding python_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.

:single-line-type-parameter-list: (no value)¶: Ensure that the class type parameters are emitted on a single logical line, overriding python_maximum_signature_line_length and 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)¶: Indicate the property is a classmethod.

Added in version 4.2.

:type: type of the property (text)¶

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

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

描述对象方法。参数不应包含 self 参数。描述应该包括与“function”描述的类似的信息。另见签名和:ref:信息字段列表。

选项

: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)¶: Indicate the method is a final method.

Added in version 3.1.

:single-line-parameter-list: (no value)¶: Ensures that the method’s arguments will be emitted on a single logical line, overriding python_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.

:single-line-type-parameter-list: (no value)¶: Ensure that the method’s type parameters are emitted on a single logical line, overriding python_maximum_signature_line_length and 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:装饰器:: removename(func)”。）

没有“py:deco”角色链接到用这个指令标记的装饰器；相反，使用:rst:role:py:func 角色。

:single-line-parameter-list: (no value)¶: Ensures that the decorator’s arguments will be emitted on a single logical line, overriding python_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.1.

:single-line-type-parameter-list: (no value)¶: Ensure that the decorator’s type parameters are emitted on a single logical line, overriding python_maximum_signature_line_length and maximum_signature_line_length.

Added in version 7.2.

.. py:decoratormethod:: name¶

.. py:decoratormethod:: name(signature)

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

与 :rst:dir:`py:装饰器`相同，但对于作为方法的装饰器。

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

Python签名¶

函数，方法和类构造函数的签名可以像在Python中编写一样给出。

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

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

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

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

习惯上将开口括号放在逗号之前。

Python 3.12 introduced type parameters, which are type variables declared directly within the class or function definition:

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

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

The corresponding reStructuredText documentation would be:

.. py:class:: AnimalList[AnimalT]

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

See PEP 695 and PEP 696 for details and the full specification.

信息字段列表¶

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对象是私有成员。它被用于:py:mod: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: 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 – 如果信息主体超过160个字符
TypeError – 如果信息主体不是基本字符串

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

: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

交叉引用Python对象¶

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

:py:mod:¶: 参考模块；可以使用虚线名称，这也应该用于包名称。

:py:func:¶: 引用Python函数；可以使用带虚线的名称。角色文本不需要包括尾随括号以增强可读性；如果:confval:add_function_parentheses 配置值为“ True” (默认值)，它们将由Sphinx自动添加。

: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”清楚地引用了“foo”模块中的“filter”函数。

通常，首先搜索这些角色中的名称而不进一步限定，然后将当前模块名称添加到前面，然后使用当前模块和类名（如果有）作为前缀。如果您在名称前加一个点，则此顺序相反。例如，在Python的文档“ codecs ”模块中，“open()”总是引用内置函数，而“open()”指“codecs.open()”。

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

此外，如果名称以点为前缀，并且未找到完全匹配，则将目标作为后缀，并搜索具有该后缀的所有对象名称。例如，“TarFile.close()”引用“tarfile.TarFile.close()”函数，即使当前模块不是“tarfile”。由于这可能会变得模棱两可，如果有多个可能匹配，您将收到Sphinx的警告。

请注意，您可以组合使用“~”和“.”前缀：“”~.TarFile.close()”将引用“tarfile.TarFile.close()”方法，但可见的链接标题只是“close()”。

Sphinx

On this page

Site navigation

Python域¶

Python签名¶

信息字段列表¶

交叉引用Python对象¶