O Domínio Python¶

Adicionado na versão 1.0.

O domínio Python (nome py) fornece as seguintes diretivas para declarações de módulo:

.. py:module:: name¶

Esta diretiva marca o início da descrição de um módulo (ou submódulo de pacote, caso em que o nome deve ser totalmente qualificado, incluindo o nome do pacote). Uma descrição do módulo, como a docstring, pode ser colocada no corpo da diretiva.

Esta diretiva também adicionará uma entrada no índice global de módulos.

Alterado na versão 5.2: Diretivas de módulo possuem suporte a conteúdo do corpo.

opções

:platform: platforms (comma separated list)¶: Indica plataformas nas quais o módulo está disponível (se estiver disponível em todas as plataformas, a opção deve ser omitida). As chaves são identificadores curtos; exemplos que estão em uso incluem “IRIX”, “Mac”, “Windows” e “Unix”. É importante usar uma chave que já foi usada quando aplicável.

:synopsis: purpose (text)¶: Consiste em em uma frase descrevendo o propósito do módulo – atualmente ela é usada apenas no índice global de módulos.

:deprecated: (no argument)¶: Marca um módulo como descontinuado; ele será designado como tal em vários locais.

.. py:currentmodule:: name¶: Esta diretiva diz ao Sphinx que as classes, funções, etc. documentadas a partir daqui estão no módulo fornecido (como py:module), mas não criará entradas de índice, uma entrada no índice global de módulos ou um link de alvo para py:mod. Isso é útil em situações onde a documentação para coisas em um módulo é espalhada por vários arquivos ou seções – um local tem a diretiva py:module, os outros apenas py:currentmodule.

As seguintes diretivas são fornecidas para o conteúdo do módulo e da classe:

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

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

Descreve uma função de nível de módulo. A assinatura deve incluir os parâmetros, junto com parâmetros de tipo opcionais, como fornecidos na definição da função Python, consulte Assinaturas Python. Por exemplo:

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

Para métodos, você deve usar py:method.

A descrição normalmente inclui informações sobre os parâmetros necessários e como eles são usados (especialmente se os objetos mutáveis passados como parâmetros são modificados), efeitos colaterais e possíveis exceções.

Esta informação pode (em qualquer diretiva py) opcionalmente ser fornecida em uma forma estruturada, veja Listas de campos de informações.

opções

:async: (no value)¶: Indica que a função é uma função assíncrona.

Adicionado na versão 2.1.

:canonical: (full qualified name including module name)¶: Descreve o local onde o objeto está definido, se o objeto for importado de outros módulos

Adicionado na versão 4.0.

:single-line-parameter-list: (no value)¶: Garante que os argumentos da função serão emitidos em uma única linha lógica, substituindo python_maximum_signature_line_length e maximum_signature_line_length.

Adicionado na versão 7.1.

:single-line-type-parameter-list: (no value)¶: Garante que os parâmetros de tipo da função sejam emitidos em uma única linha lógica, substituindo python_maximum_signature_line_length e maximum_signature_line_length.

Adicionado na versão 7.1.

.. py:data:: name¶

Descreve dados globais em um módulo, incluindo variáveis e valores usados como “constantes definidas”. Considere usar py:type para apelidos de tipo e py:attribute para variáveis de classe e atributos de instância.

opções

:type: type of the variable (text)¶: Isso será analisado como uma expressão Python para referência cruzada da anotação de tipo. Como tal, o argumento para :type: deve ser uma expressão de anotação válida.

Cuidado

A sintaxe válida para a opção de diretiva :type: difere da sintaxe para o campo de informações :type:. A opção de diretiva :type: não entende a marcação reStructuredText ou as palavras-chave or ou of, o que significa que as uniões devem usar | e as sequências devem usar colchetes, e papéis como :ref:`...` não podem ser usadas.

Adicionado na versão 2.4.

:value: initial value of the variable (text)¶: Adicionado na versão 2.4.

:canonical: (full qualified name including module name)¶: Descreve o local onde o objeto está definido, se o objeto for importado de outros módulos

Adicionado na versão 4.0.

.. py:exception:: name¶

.. py:exception:: name(parameters)

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

Descreve uma classe de exceção. A assinatura pode, mas não precisa incluir parênteses com argumentos do construtor, ou podem opcionalmente incluir parâmetros de tipo (veja PEP 695).

opções

:final: (no value)¶: Indica que a classe é uma classe final.

Adicionado na versão 3.1.

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

Adicionado na versão 7.1.

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

Adicionado na versão 7.1.

.. py:class:: name¶

.. py:class:: name(parameters)

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

Descreve uma classe. A assinatura pode opcionalmente incluir parâmetros de tipo (veja PEP 695) ou parênteses com parâmetros que serão mostrados como argumentos do construtor. Veja também Assinaturas Python.

Métodos e atributos pertencentes à classe devem ser colocados no corpo desta diretiva. Se forem colocados fora, o nome fornecido deve conter o nome da classe para que as referências cruzadas ainda funcionem. Exemplo:

.. py:class:: Foo

   .. py:method:: quux()

-- or --

.. py:class:: Bar

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

A primeira maneira é a preferida.

opções

:abstract: (no value)¶

Indica que a classe é uma classe base abstrata. Isso produz a seguinte saída:

abstract class Cheese: A cheesy representation.

Adicionado na versão 8.2.

:canonical: (full qualified name including module name)¶: Descreve o local onde o objeto está definido, se o objeto for importado de outros módulos

Adicionado na versão 4.0.

:final: (no value)¶: Indica que a classe é uma classe final.

Adicionado na versão 3.1.

:single-line-parameter-list: (no value)¶: Garante que os argumentos do construtor da classe serão emitidos em uma única linha lógica, substituindo python_maximum_signature_line_length e maximum_signature_line_length.

Adicionado na versão 7.1.

:single-line-type-parameter-list: (no value)¶: Garante que os parâmetros de tipo da classe sejam emitidos em uma única linha lógica, substituindo python_maximum_signature_line_length e maximum_signature_line_length.

.. py:attribute:: name¶

Descreve um atributo de dados do objeto. A descrição deve incluir informações sobre o tipo de dados esperados e se eles podem ser alterados diretamente. Apelidos de tipos devem ser documentos com py:type.

opções

:type: type of the attribute (text)¶: Isso será analisado como uma expressão Python para referência cruzada da anotação de tipo. Como tal, o argumento para :type: deve ser uma expressão de anotação válida.

Cuidado

A sintaxe válida para a opção de diretiva :type: difere da sintaxe para o campo de informações :type:. A opção de diretiva :type: não entende a marcação reStructuredText ou as palavras-chave or ou of, o que significa que as uniões devem usar | e as sequências devem usar colchetes, e papéis como :ref:`...` não podem ser usadas.

Adicionado na versão 2.4.

:value: initial value of the attribute (text)¶: Adicionado na versão 2.4.

:canonical: (full qualified name including module name)¶: Descreve o local onde o objeto está definido, se o objeto for importado de outros módulos

Adicionado na versão 4.0.

.. py:property:: name¶

Descreve uma propriedade do objeto

Adicionado na versão 4.0.

opções

:abstract: (no value)¶

:abstractmethod: (no value)¶

Indicate the property is abstract. This produces the following output:

abstract property Cheese.amount_in_stock: Cheese levels at the National Cheese Emporium.

Alterado na versão 8.2: The :abstract: alias is also supported.

:classmethod: (no value)¶: Indica que a propriedade é um método de classe.

Adicionado na versão 4.2.

:type: type of the property (text)¶: Isso será analisado como uma expressão Python para referência cruzada da anotação de tipo. Como tal, o argumento para :type: deve ser uma expressão de anotação válida.

Cuidado

A sintaxe válida para a opção de diretiva :type: difere da sintaxe para o campo de informações :type:. A opção de diretiva :type: não entende a marcação reStructuredText ou as palavras-chave or ou of, o que significa que as uniões devem usar | e as sequências devem usar colchetes, e papéis como :ref:`...` não podem ser usadas.

.. py:type:: name¶

Descreve um apelido de tipo.

O tipo que o apelido representa deve ser descrito com a opção canonical. Esta diretiva oferece suporte a um corpo de descrição opcional.

Por exemplo:

.. py:type:: UInt64

   Represent a 64-bit positive integer.

será renderizado da seguinte maneira:

type UInt64¶: Representa um número inteiro positivo de 64 bits.

opções

:canonical: (text)¶

O tipo canônico representado por este apelido, por exemplo:

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

   Represent a regular expression or a compiled pattern.

Isso é renderizado como:

type StrPattern = str | re.Pattern[str]¶: Representa uma expressão regular ou um padrão compilado.

Adicionado na versão 7.4.

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

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

Descreve um método de objeto. Os parâmetros não devem incluir o parâmetro self. A descrição deve incluir informações semelhantes às descritas para function. Veja também Assinaturas Python e Listas de campos de informações.

opções

:abstract: (no value)¶

:abstractmethod: (no value)¶

Indicate the method is an abstract method. This produces the following output:

abstractmethod Cheese.order_more_stock(): Order more cheese (we’re fresh out!).

Adicionado na versão 2.1.

Alterado na versão 8.2: The :abstract: alias is also supported.

:async: (no value)¶: Indica que o método é um método async, isto é, assíncrono.

Adicionado na versão 2.1.

:canonical: (full qualified name including module name)¶: Descreve o local onde o objeto está definido, se o objeto for importado de outros módulos

Adicionado na versão 4.0.

:classmethod: (no value)¶: Indica que o método é um método de classe.

Adicionado na versão 2.1.

:final: (no value)¶: Indica que o método é um método final.

Adicionado na versão 3.1.

:single-line-parameter-list: (no value)¶: Garante que os argumentos do método serão emitidos em uma única linha lógica, substituindo python_maximum_signature_line_length e maximum_signature_line_length.

Adicionado na versão 7.1.

:single-line-type-parameter-list: (no value)¶: Garante que os parâmetros de tipo do método sejam emitidos em uma única linha lógica, substituindo python_maximum_signature_line_length e maximum_signature_line_length.

Adicionado na versão 7.2.

:staticmethod: (no value)¶: Indica que o método é um método estático.

Adicionado na versão 2.1.

.. py:staticmethod:: name(parameters)¶
.. py:staticmethod:: name[type parameters](parameters): Como py:method, mas indica que o método é um método estático.

Adicionado na versão 0.4.

.. py:classmethod:: name(parameters)¶
.. py:classmethod:: name[type parameters](parameters): Como py:method, mas indica que o método é um método de classe.

Adicionado na versão 0.6.

.. py:decorator:: name¶

.. py:decorator:: name(parameters)

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

Descreve uma função de decorador. A assinatura deve representar o uso como decorador. Por exemplo, dadas as funções

def removename(func):
    func.__name__ = ''
    return func

def setnewname(name):
    def decorator(func):
        func.__name__ = name
        return func
    return decorator

as descrições devem se parecer com isso:

.. py:decorator:: removename

   Remove name of the decorated function.

.. py:decorator:: setnewname(name)

   Set name of the decorated function to *name*.

(em oposição a .. py:decorator:: removename(func).)

Refer to a decorator function using the py:deco role.

:single-line-parameter-list: (no value)¶: Garante que os argumentos do decorador serão emitidos em uma única linha lógica, substituindo python_maximum_signature_line_length e maximum_signature_line_length.

Adicionado na versão 7.1.

:single-line-type-parameter-list: (no value)¶: Garante que os parâmetros de tipo do decorador sejam emitidos em uma única linha lógica, substituindo python_maximum_signature_line_length e maximum_signature_line_length.

Adicionado na versão 7.2.

.. py:decoratormethod:: name¶

.. py:decoratormethod:: name(signature)

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

O mesmo que py:decorator, mas para decoradores que são métodos.

Refer to a decorator method using the py:deco role.

Assinaturas Python¶

Signatures of functions, methods and class constructors can be given like they would be written in Python. This can include default values, positional-only or keyword-only parameters, type annotations, and type parameters. For example:

.. py:function:: compile(source: str, filename: Path, symbol: str = 'file') -> ast.AST

compile(source: str, filename: Path, symbol: str = 'file') → ast.AST

For functions with optional parameters that don’t have default values (typically functions implemented in C extension modules without keyword argument support), you can list multiple versions of the same signature in a single directive:

compile(source)
compile(source, filename)
compile(source, filename, symbol)

Another approach is to use square brackets to specify the optional parts. When using square brackets, it is customary to place the opening bracket before the comma ([,).

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 markup would be:

.. py:class:: AnimalList[AnimalT]

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

Ver também

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

Listas de campos de informações¶

Adicionado na versão 0.4.

Alterado na versão 3.0: campos meta adicionados.

Dentro das diretivas de descrição de objeto Python, as listas de campos reStructuredText com esses campos são reconhecidas e formatadas de maneira adequada:

param, parameter, arg, argument, key, keyword: Descrição de um parâmetro.
type: Tipo de um parâmetro. Cria um link, se possível.
raises, raise, except, exception: Que (e quando) uma exceção específica é levantada.
var, ivar, cvar: Descrição de uma variável.
vartype: Tipo de uma variável. Cria um link, se possível.
returns, return: Descrição do valor de retorno.
rtype: Tipo de retorno. Cria um link, se possível.
meta: Adiciona metadados à descrição do objeto python. Os metadados não serão mostrados no documento de saída. Por exemplo, :meta private: indica que o objeto python é um membro privado. É usado em sphinx.ext.autodoc para filtrar membros.

Nota

Na versão atual, todos var, ivar e cvar são representados como “Variável”. Não há diferença alguma.

Os nomes dos campos devem consistir em uma dessas palavras-chave e um argumento (exceto para returns e rtype, que não precisam de um argumento). Isso é melhor explicado por um exemplo:

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

Isso será renderizado como:

send_message(sender, recipient, message_body[, priority=1])¶

Envia uma mensagem para um destinatário

Parâmetros:

sender (str) – A pessoa enviando a mensagem
recipient (str) – O destinatário da mensagem
message_body (str) – O corpo da mensagem
priority (int or None) – A prioridade da mensagem, pode ser um número de 1-5

Retorna:

o id da mensagem

Tipo de retorno:

int

Levanta:

ValueError – se message_body exceder 160 caracteres
TypeError – se message_body não for uma basestring

Também é possível combinar o tipo e descrição do parâmetro, se o tipo for uma única palavra, como isso:

:param int priority: The priority of the message, can be a number 1-5

Adicionado na versão 1.5.

Tipos de contêineres tal como listas e dicionários podem ser vinculados automaticamente usando a seguinte sintaxe:

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

Multiple types in a type field will be linked automatically if separated by either the vertical bar (|) or the word “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

Referência cruzada de objetos Python¶

Os seguintes papéis fazem referência a objetos em módulos e são possivelmente alvos de hiperlink se um identificador correspondente for encontrado:

:py:mod:¶: Referencia um módulo; um nome pontilhado pode ser usado. Isso também deve ser usado para nomes de pacotes.

:py:func:¶: Referencia uma função Python; nomes pontilhados podem ser usados. O texto do papel não precisa incluir parênteses ao final para melhorar a legibilidade; eles serão adicionados automaticamente pelo Sphinx se o valor da configuração add_function_parentheses for True (o padrão).

:py:deco:¶: Reference a Python decorator; dotted names may be used. The rendered output will be prepended with an at-sign (@), for example: :py:deco:`removename` produces @removename.

:py:data:¶: Referencia uma variável a nível de módulo.

:py:const:¶: Referencia uma constante “definida”. Isso pode ser uma variável Python que não é destinada a ser alterada.

:py:class:¶: Referencia uma classe; um nome pontilhado pode ser usado.

:py:meth:¶: Referencia um método de um objeto. O texto do papel pode incluir o nome do tipo e o nome do método; se ocorrer dentro da descrição de um tipo, o nome do tipo pode ser omitido. Um nome pontilhado pode ser usado.

:py:attr:¶: Referencia um atributo de dados de um objeto.

Nota

O papel também é capaz de fazer referência à propriedade.

:py:type:¶: Referência um apelido de tipo

:py:exc:¶: Referencia uma exceção. Um nome pontilhado pode ser usado.

:py:obj:¶: Referencia um objeto de tipo não especificado. Útil, por exemplo, como default_role.

Adicionado na versão 0.4.

Target specification¶

The target can be specified as a fully qualified name (e.g. :py:meth:`my_module.MyClass.my_method`) or any shortened version (e.g. :py:meth:`MyClass.my_method` or :py:meth:`my_method`). See target resolution for details on the resolution of shortened names.

Cross-referencing modifiers can be applied. In short:

Você pode fornecer um título explícito e um alvo de referência: :py:mod:`mathematical functions <math>` fará referência ao módulo math, mas o texto do link será “mathematical functions”.
Se você prefixar o conteúdo com um ponto de exclamação !, nenhuma referência/hiperlink será criada.
Se você prefixar o conteúdo com ~, o texto do link será apenas o último componente do alvo. Por exemplo, :py:meth:`~queue.Queue.get` irá fazer referência a queue.Queue.get, mas somente exibirá get como o texto do link.

Target resolution¶

A given link target name is resolved to an object using the following strategy:

Names in these roles are searched first without any further qualification, then with the current module name prepended, then with the current module and class name (if any) prepended.

If you prefix the name with a dot (.), this order is reversed. For example, in the documentation of Python’s codecs module, :py:func:`open` always refers to the built-in function, while :py:func:`.open` refers to codecs.open().

Uma heurística semelhante é usada para determinar se o nome é um atributo da classe documentada atualmente.

Além disso, se o nome for prefixado com um ponto e nenhuma correspondência exata for encontrada, o alvo será considerado um sufixo e todos os nomes de objeto com esse sufixo serão pesquisados. Por exemplo, :py:meth:`.TarFile.close` faz referência à função tarfile.TarFile.close(), mesmo se o módulo atual não for tarfile. Como isso pode ficar ambíguo, se houver mais de uma correspondência possível, você receberá um aviso do Sphinx.

Note que você pode combinar os prefixos ~ e .: :py:meth:`~.TarFile.close` fará referência ao método tarfile.TarFile.close() , mas a legenda do link visível será apenas close().