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函数定义中所示,参见 :ref :signatures .例如:

.. 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)¶: 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:单行参数列表 .

Added in version 7.1.

:single-line-type-parameter-list: (no value)¶: 请参见 py:class:单行类型参数列表 .

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¶

描述一个对象数据属性.描述应包括关于期望数据类型的信息,以及它是否可以直接更改.类型别名应使用 py:type 文档化.

选项

: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: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]¶: 表示一个正则表达式或一个编译后的模式.

Added in version 7.4.

.. 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 角色可以链接到标记为此指令的装饰器;而是使用:rst:role: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]])¶

在逗号之前放置开括号是惯例.

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 .

信息字段列表¶

Added in version 0.4.

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

在 Python 对象描述指令中,识别并美化带有这些字段的 reStructuredText 字段列表:

param, parameter, arg, argument, key, keyword: Description of a parameter.
type: Type of a parameter. Creates a link if possible.
raises, raise, except, exception: That (and when) a specific exception is raised.
var, ivar, cvar: Description of a variable.
vartype: Type of a variable. Creates a link if possible.
returns, return: Description of the return value.
rtype: Return type. Creates a link if possible.
meta: Add metadata to description of the python object. The metadata will not be shown on output document. For example, :meta private: indicates the python object is private member. It is used in sphinx.ext.autodoc for filtering members.

备注

在当前版本中,所有 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 – 如果 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

交叉引用 Python 对象¶

以下角色指的是模块中的对象,可能会在找到匹配标识符时提供超链接:

:py:mod:¶: 引用一个模块;可以使用带点的名称. 这也应该用于包名称.

:py:func:¶: 引用一个Python函数;可以使用点名.为了增强可读性,角色文本不需要包含末尾的括号;如果配置值:confval:add_function_parentheses 为 True （默认为此值）,Sphinx将自动添加括号.

: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:func:filter```可能指当前模块中名为 ``filter` 的函数,或该名称的内置函数.相反,``:py:func:foo.filter```明确指 ``foo` 模块中的 filter 函数.

通常,这些角色中的名称会首先不加任何其他限定地进行搜索,然后是前面加上当前模块名的搜索,接着是前面加上当前模块和类名（如果有）的搜索.如果你用句点前缀名称,则顺序会反转.例如,在 Python 的 codecs 模块的文档中,``:py:func:open```始终指的是内置函数,而`open```指的是 :func:`codecs.open() .

使用类似的启发式方法来判断名称是否是当前文档类的一个属性.

此外,如果名称以点为前缀,并且没有找到精确匹配,则将目标视为后缀,并搜索所有带有该后缀的对象名称.例如,``:py:meth:.TarFile.close ``引用了` tarfile.TarFile.close() 函数,即使当前模块不是 tarfile`` .由于这可能会产生歧义,如果有多个可能的匹配,您将收到Sphinx的警告.

注意,您可以组合使用 ~ 和 . 前缀::py:meth:`~.TarFile.close```将引用 ``tarfile.TarFile.close() 方法,但可见链接标题将仅为 close() .