Python ドメイン¶

バージョン 1.0 で追加されました。

Python ドメイン (名前 **py**) は、モジュール宣言のために以下のディレクティブを提供します。

.. py:module:: name¶

このディレクティブは、モジュール (またはパッケージサブモジュール。この場合、名前はパッケージ名を含む完全修飾名にする必要があります) の説明の始まりを示します。docstring などのモジュールの説明は、ディレクティブの本文に配置できます。

このディレクティブは、グローバルモジュールインデックスにエントリを作成します。

バージョン 5.2 で変更: モジュールディレクティブは本文コンテンツをサポートするようになりました。

オプション

:platform: platforms (カンマ区切りリスト)¶: モジュールが利用可能なプラットフォームを示します (すべてのプラットフォームで利用可能な場合は、このオプションを省略する必要があります)。キーは短い識別子です。使用されている例としては、「IRIX」、「Mac」、「Windows」、「Unix」などがあります。該当する場合、既に使用されているキーを使用することが重要です。

:synopsis: purpose (テキスト)¶: モジュールの目的を説明する1文で構成されます。現在、グローバルモジュールインデックスでのみ使用されています。

:deprecated: (引数なし)¶: モジュールを非推奨としてマークします。その後、さまざまな場所で非推奨として指定されます。

.. py:currentmodule:: name¶: このディレクティブは、Sphinx に対して、ここからドキュメント化されるクラス、関数などが指定されたモジュール内にあることを (py:module と同様に) 知らせますが、インデックスエントリ、グローバルモジュールインデックスのエントリ、または py:mod のリンクターゲットは作成しません。これは、モジュール内のもののドキュメントが複数のファイルまたはセクションに分散している場合に役立ちます。1つの場所に 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: (値なし)¶: 関数が async 関数であることを示します.

バージョン 2.1 で追加されました。

:canonical: (モジュール名を含む完全修飾名)¶: オブジェクトが他のモジュールからインポートされている場合、オブジェクトが定義されている場所を記述します。

バージョン 4.0 で追加されました。

:single-line-parameter-list: (値なし)¶: python_maximum_signature_line_length および maximum_signature_line_length をオーバーライドして、関数の引数が1つの論理行に出力されるようにします。

バージョン 7.1 で追加されました。

:single-line-type-parameter-list: (値なし)¶: python_maximum_signature_line_length および maximum_signature_line_length をオーバーライドして、関数の型パラメータが1つの論理行に出力されるようにします。

バージョン 7.1 で追加されました。

.. py:data:: name¶

「定義済み定数」として使用される変数と値の両方を含む、モジュール内のグローバルデータを記述します。型エイリアスの代わりに py:type を、クラス変数とインスタンス属性には py:attribute を使用することを検討してください。

オプション

:type: 変数の型 (テキスト)¶: バージョン 2.4 で追加されました。

:value: 変数の初期値 (テキスト)¶: バージョン 2.4 で追加されました。

:canonical: (モジュール名を含む完全修飾名)¶: オブジェクトが他のモジュールからインポートされている場合、オブジェクトが定義されている場所を記述します。

バージョン 4.0 で追加されました。

.. py:exception:: name¶

.. py:exception:: name(parameters)

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

例外クラスを記述します。シグネチャには、コンストラクタ引数を含む括弧を含めることも、含めないこともできます。または、オプションで型パラメータを含めることもできます ( 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:: name¶

.. py:class:: name(パラメータ)

.. py:class:: name[型パラメータ](パラメータ)

クラスを記述します。シグネチャには、オプションで型パラメータ（PEP 695を参照）またはコンストラクタの引数として表示されるパラメータを含む括弧を含めることができます。Python シグネチャも参照してください。

クラスに属するメソッドと属性はこのディレクティブの本文に配置する必要があります。外部に配置する場合は、クロスリファレンスが機能するように、指定された名前にクラス名を含める必要があります。例

.. py:class:: Foo

   .. py:method:: quux()

-- or --

.. py:class:: Bar

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

最初の方法が推奨されます。

オプション

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

オブジェクトデータ属性を記述します。説明には、予期されるデータの型と、直接変更できるかどうかに関する情報を含める必要があります。型エイリアスは py:type を使用してドキュメント化する必要があります。

オプション

:type: 属性の型 (テキスト)¶: バージョン 2.4 で追加されました。

:value: 属性の初期値 (テキスト)¶: バージョン 2.4 で追加されました。

:canonical: (モジュール名を含む完全修飾名)¶: オブジェクトが他のモジュールからインポートされている場合、オブジェクトが定義されている場所を記述します。

バージョン 4.0 で追加されました。

.. py:property:: name¶

オブジェクトプロパティを記述します。

バージョン 4.0 で追加されました。

オプション

:abstractmethod: (値なし)¶: プロパティが抽象的であることを示します。

:classmethod: (値なし)¶: プロパティがクラスメソッドであることを示します。

バージョン 4.2 で追加されました。

:type: プロパティの型 (テキスト)¶

.. py:type:: name¶

型エイリアスを記述します。

エイリアスが表す型は、canonical オプションで記述する必要があります。このディレクティブは、オプションの説明本文をサポートしています。

例えば

.. py:type:: UInt64

   Represent a 64-bit positive integer.

は次のようにレンダリングされます

型 UInt64¶: 64 ビットの正の整数を表します。

オプション

:canonical: (テキスト)¶

このエイリアスによって表される標準的な型、例えば

.. py:type:: StrPattern
   :canonical: str | re.Pattern[str]

   Represent a regular expression or a compiled pattern.

これは次のようにレンダリングされます

型 StrPattern = str | re.Pattern[str]¶: 正規表現またはコンパイルされたパターンを表します。

バージョン 7.4 で追加されました。

.. py:method:: name(パラメータ)¶

.. py:method:: name[型パラメータ](パラメータ)

オブジェクトメソッドを記述します。パラメータには、self パラメータを含めるべきではありません。説明には、function について説明したものと同様の情報を含める必要があります。Python シグネチャと情報フィールドリストも参照してください。

オプション

:abstractmethod: (値なし)¶: メソッドが抽象メソッドであることを示します。

バージョン 2.1 で追加されました。

: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:: name(パラメータ)¶
.. py:staticmethod:: name[型パラメータ](パラメータ): py:methodと同様ですが、メソッドが静的メソッドであることを示します。

バージョン 0.4 で追加されました。

.. py:classmethod:: name(parameters)¶
.. py:classmethod:: name[type parameters](parameters): py:method と同様ですが、メソッドがクラスメソッドであることを示します。

バージョン 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: (値なし)¶: デコレータの引数が単一の論理行に出力されるようにし、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:: 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 を参照してください。

情報フィールドリスト¶

バージョン 0.4 で追加されました。

バージョン 3.0 で変更: メタフィールドが追加されました。

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 は「変数」として表されます。違いはまったくありません。

フィールド名は、これらのキーワードのいずれかと引数で構成する必要があります (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

バージョン 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（デフォルト）の場合、Sphinx によって自動的に追加されます。

:py:data:¶: モジュールレベルの変数を参照します。

:py:const:¶: 「定義済み」定数を参照します。これは、変更されないことを意図した Python 変数である可能性があります。

:py:class:¶: クラスを参照します。ドット区切りの名前を使用できます。

:py:meth:¶: オブジェクトのメソッドを参照します。ロールテキストには、型名とメソッド名を含めることができます。型の説明内で使用される場合、型名は省略できます。ドット区切りの名前を使用できます。

:py:attr:¶: オブジェクトのデータ属性を参照します。

注記

このロールは、プロパティも参照できます。

:py:type:¶: 型エイリアスを参照します。

:py:exc:¶: 例外を参照します。ドット区切りの名前を使用できます。

:py:obj:¶: 型が指定されていないオブジェクトを参照します。default_role として役立ちます。

バージョン 0.4 で追加されました。

このマークアップで囲まれた名前には、モジュール名やクラス名を含めることができます。たとえば、:py:func:`filter` は、現在のモジュールにある filter という名前の関数、またはその名前の組み込み関数を参照できます。対照的に、:py:func:`foo.filter` は、明らかに foo モジュールの filter 関数を参照します。

通常、これらのロール内の名前は、最初に修飾なしで検索され、次に現在のモジュール名を先頭に付けて検索され、次に現在のモジュールとクラス名（存在する場合）を先頭に付けて検索されます。名前にドットを付けると、この順序は逆になります。たとえば、Python の codecs モジュールのドキュメントでは、:py:func:`open` は常に組み込み関数を参照しますが、:py:func:`.open` は codecs.open() を参照します。

名前が現在ドキュメント化されているクラスの属性であるかどうかを判断するために、同様のヒューリスティックが使用されます。

また、名前にドットが prefixesされ、完全一致が見つからない場合、ターゲットは接尾辞として扱われ、その接尾辞を持つすべてのオブジェクト名が検索されます。たとえば、:py:meth:`.TarFile.close` は、現在のモジュールが tarfile でなくても、tarfile.TarFile.close() 関数を参照します。これはあいまいになる可能性があるため、一致する可能性が複数ある場合は、Sphinx から警告が表示されます。

~ と . のプレフィックスを組み合わせることができることに注意してください。:py:meth:`~.TarFile.close` は tarfile.TarFile.close() メソッドを参照しますが、表示されるリンクキャプションは close() のみになります。