Python 領域¶

在版本 1.0 中新增。

Python 領域（名稱為 py）為模組宣告提供以下指令

.. py:module:: 名稱¶

此指令標記模組（或套件子模組，在這種情況下，名稱應為完整限定名稱，包括套件名稱）描述的開始。模組的描述（例如 docstring）可以放置在指令的主體中。

此指令也會在全域模組索引中建立一個條目。

在版本 5.2 中變更：模組指令支援主體內容。

選項

:platform: 平台 （逗號分隔列表）¶: 指出模組可用的平台（如果它在所有平台上都可用，則應省略此選項）。鍵是簡短的識別碼；正在使用的範例包括 “IRIX”、“Mac”、“Windows” 和 “Unix”。重要的是在適用的情況下使用已使用的鍵。

:synopsis: 目的 （文字）¶: 包含一句描述模組用途的句子 – 目前僅在全域模組索引中使用。

:deprecated: （無引數）¶: 將模組標記為已棄用；它將在各種位置被指定為已棄用。

.. py:currentmodule:: 名稱¶: 此指令告訴 Sphinx，從此處開始記錄的文件中的類別、函式等都在給定的模組中（類似於 py:module），但它不會建立索引條目、全域模組索引中的條目，或 py:mod 的連結目標。這在模組中事物的文件分散在多個檔案或章節的情況下很有用 – 一個位置有 py:module 指令，其他位置只有 py:currentmodule。

以下指令適用於模組和類別內容

.. py:function:: 名稱(參數)¶

.. py:function:: 名稱[類型參數](參數)

描述模組層級的函式。簽名應包括參數以及選用的類型參數，如 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: （無值）¶: 指示函式為非同步函式。

在版本 2.1 中新增。

:canonical: （完整限定名稱，包括模組名稱）¶: 描述物件定義的位置，如果物件是從其他模組匯入的

在版本 4.0 中新增。

:single-line-parameter-list: （無值）¶: 確保函式的引數將在單個邏輯行上發出，覆蓋 python_maximum_signature_line_length 和 maximum_signature_line_length。

在版本 7.1 中新增。

:single-line-type-parameter-list: （無值）¶: 確保函式的類型參數將在單個邏輯行上發出，覆蓋 python_maximum_signature_line_length 和 maximum_signature_line_length。

在版本 7.1 中新增。

.. py:data:: 名稱¶

描述模組中的全域資料，包括變數和用作「已定義常數」的值。考慮對類型別名使用 py:type，對類別變數和實例屬性使用 py:attribute。

選項

:type: 變數的類型 （文字）¶: 這將被解析為 Python 表達式，用於交叉參照類型註解。因此，:type: 的引數應為有效的註解表達式。

注意

:type: 指令選項的有效語法與 :type: 資訊欄位的語法不同。:type: 指令選項不理解 reStructuredText 標記或 or 或 of 關鍵字，這表示聯集必須使用 |，序列必須使用方括號，並且不能使用諸如 :ref:`...` 之類的角色。

在版本 2.4 中新增。

:value: 變數的初始值 （文字）¶: 在版本 2.4 中新增。

:canonical: （完整限定名稱，包括模組名稱）¶: 描述物件定義的位置，如果物件是從其他模組匯入的

在版本 4.0 中新增。

.. py:exception:: 名稱¶

.. py:exception:: 名稱(參數)

.. py:exception:: 名稱[類型參數](參數)

描述例外類別。簽名可以但不需要包含帶有建構子引數的括號，或者可以選擇性地包含類型參數（請參閱 PEP 695）。

選項

:final: （無值）¶: 指示類別為最終類別。

在版本 3.1 中新增。

:single-line-parameter-list: （無值）¶: 請參閱 py:class:single-line-parameter-list。

在版本 7.1 中新增。

:single-line-type-parameter-list: （無值）¶: 請參閱 py:class:single-line-type-parameter-list。

在版本 7.1 中新增。

.. py:class:: 名稱¶

.. py:class:: 名稱(參數)

.. py:class:: 名稱[類型參數](參數)

描述類別。簽名可以選擇性地包含類型參數（請參閱 PEP 695）或帶有將顯示為建構子引數的參數的括號。另請參閱 Python 簽名。

屬於類別的方法和屬性應放置在此指令的主體中。如果它們放置在外部，則提供的名稱應包含類別名稱，以便交叉參照仍然有效。範例

.. py:class:: Foo

   .. py:method:: quux()

-- or --

.. py:class:: Bar

.. py:method:: Bar.quux()

第一種方式是首選方式。

選項

:abstract: （無值）¶

指示類別為抽象基底類別。這會產生以下輸出

abstract class Cheese: 起司的表示法。

在版本 8.2 中新增。

:canonical: （完整限定名稱，包括模組名稱）¶: 描述物件定義的位置，如果物件是從其他模組匯入的

在版本 4.0 中新增。

:final: （無值）¶: 指示類別為最終類別。

在版本 3.1 中新增。

:single-line-parameter-list: （無值）¶: 確保類別建構子的引數將在單個邏輯行上發出，覆蓋 python_maximum_signature_line_length 和 maximum_signature_line_length。

在版本 7.1 中新增。

:single-line-type-parameter-list: （無值）¶: 確保類別類型參數將在單個邏輯行上發出，覆蓋 python_maximum_signature_line_length 和 maximum_signature_line_length。

.. py:attribute:: 名稱¶

描述物件資料屬性。描述應包括有關預期資料類型的資訊，以及是否可以直接變更它。類型別名應使用 py:type 記錄。

選項

:type: 屬性的類型 （文字）¶: 這將被解析為 Python 表達式，用於交叉參照類型註解。因此，:type: 的引數應為有效的註解表達式。

注意

:type: 指令選項的有效語法與 :type: 資訊欄位的語法不同。:type: 指令選項不理解 reStructuredText 標記或 or 或 of 關鍵字，這表示聯集必須使用 |，序列必須使用方括號，並且不能使用諸如 :ref:`...` 之類的角色。

在版本 2.4 中新增。

:value: 屬性的初始值 （文字）¶: 在版本 2.4 中新增。

:canonical: （完整限定名稱，包括模組名稱）¶: 描述物件定義的位置，如果物件是從其他模組匯入的

在版本 4.0 中新增。

.. py:property:: 名稱¶

描述物件屬性。

在版本 4.0 中新增。

選項

:abstract: （無值）¶

:abstractmethod: （無值）¶

指示屬性為抽象屬性。這會產生以下輸出

abstract property Cheese.amount_in_stock: 國家起司商場 的起司存量。

在版本 8.2 中變更：也支援 :abstract: 別名。

:classmethod: （無值）¶: 指示屬性為類別方法。

在版本 4.2 中新增。

:type: 屬性的類型 （文字）¶: 這將被解析為 Python 表達式，用於交叉參照類型註解。因此，:type: 的引數應為有效的註解表達式。

注意

:type: 指令選項的有效語法與 :type: 資訊欄位的語法不同。:type: 指令選項不理解 reStructuredText 標記或 or 或 of 關鍵字，這表示聯集必須使用 |，序列必須使用方括號，並且不能使用諸如 :ref:`...` 之類的角色。

.. py:type:: 名稱¶

描述類型別名。

別名表示的類型應使用 canonical 選項描述。此指令支援選用的描述主體。

例如

.. py:type:: UInt64

   Represent a 64-bit positive integer.

將呈現如下

type UInt64¶: 表示 64 位元正整數。

選項

:canonical: （文字）¶

此別名表示的規範類型，例如

.. 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:: 名稱(參數)¶

.. py:method:: 名稱[類型參數](參數)

描述物件方法。參數不應包含 self 參數。描述應包括與為 function 描述的資訊類似的資訊。另請參閱 Python 簽名和資訊欄位列表。

選項

:abstract: （無值）¶

:abstractmethod: （無值）¶

指示方法為抽象方法。這會產生以下輸出

abstractmethod Cheese.order_more_stock(): 訂購更多起司（我們的起司賣完了！）。

在版本 2.1 中新增。

在版本 8.2 中變更：也支援 :abstract: 別名。

:async: （無值）¶: 指示方法為非同步方法。

在版本 2.1 中新增。

:canonical: （完整限定名稱，包括模組名稱）¶: 描述物件定義的位置，如果物件是從其他模組匯入的

在版本 4.0 中新增。

:classmethod: （無值）¶: 指示方法為類別方法。

在版本 2.1 中新增。

:final: （無值）¶: 指示方法為最終方法。

在版本 3.1 中新增。

:single-line-parameter-list: （無值）¶: 確保方法的引數將在單個邏輯行上發出，覆蓋 python_maximum_signature_line_length 和 maximum_signature_line_length。

在版本 7.1 中新增。

:single-line-type-parameter-list: （無值）¶: 確保方法的類型參數將在單個邏輯行上發出，覆蓋 python_maximum_signature_line_length 和 maximum_signature_line_length。

在版本 7.2 中新增。

:staticmethod: （無值）¶: 指示方法為靜態方法。

在版本 2.1 中新增。

.. py:staticmethod:: 名稱(參數)¶
.. py:staticmethod:: 名稱[類型參數](參數): 類似於 py:method，但指示方法為靜態方法。

在版本 0.4 中新增。

.. py:classmethod:: 名稱(參數)¶
.. py:classmethod:: 名稱[類型參數](參數): 類似於 py:method，但指示方法為類別方法。

在版本 0.6 中新增。

.. py:decorator:: 名稱¶

.. py:decorator:: 名稱(參數)

.. py:decorator:: 名稱[類型參數](參數)

描述裝飾器函式。簽名應表示作為裝飾器的用法。例如，給定以下函式

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: （無值）¶: 確保裝飾器的引數將在單個邏輯行上發出，覆蓋 python_maximum_signature_line_length 和 maximum_signature_line_length。

在版本 7.1 中新增。

:single-line-type-parameter-list: （無值）¶: 確保裝飾器的類型參數將在單個邏輯行上發出，覆蓋 python_maximum_signature_line_length 和 maximum_signature_line_length。

在版本 7.2 中新增。

.. py:decoratormethod:: 名稱¶

.. py:decoratormethod:: 名稱(簽名)

.. py:decoratormethod:: 名稱[類型參數](簽名)

與 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 中變更：新增了 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: 表示此 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 或 None) – 訊息的優先順序，可以是數字 1-5

回傳:

訊息 ID

回傳類型:

int

引發:

ValueError – 如果 message_body 超過 160 個字元
TypeError – 如果 message_body 不是 basestring

如果類型是單字，也可以將參數類型和描述結合，如下所示

: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 config 值為 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`）。有關縮短名稱解析的詳細資訊，請參閱目標解析。

交叉參照修飾符可以套用。簡而言之

您可以提供明確的標題和參照目標：:py:mod:`mathematical functions <math>` 將參照 math 模組，但連結文字將為「mathematical functions」。
如果您在內容前加上驚嘆號 (!)，則不會建立參照/超連結。
如果您在內容前加上 ~，則連結文字將僅為目標的最後一個元件。例如，: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()。