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 causará uma entrada no índice do módulo global.

Alterado na versão 5.2: Module directives support body content.

options

:platform: platforms (comma separated list)¶: Indicate platforms which the module is available (if it is available on all platforms, the option should be omitted). The keys are short identifiers; examples that are in use include “IRIX”, “Mac”, “Windows” and “Unix”. It is important to use a key which has already been used when applicable.

:synopsis: purpose (text)¶: Consist of one sentence describing the module’s purpose – it is currently only used in the Global Module Index.

:deprecated: (no argument)¶: Mark a module as deprecated; it will be designated as such in various locations then.

.. 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ódulo ou um link de destino 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)

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

.. 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 Lista Informação Campos.

options

:async: (no value)¶: Indicate the function is an async function.

Adicionado na versão 2.1.

:canonical: (full qualified name including module name)¶: Describe the location where the object is defined if the object is imported from other modules

Adicionado na versão 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.

Adicionado na versão 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.

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”. Atributos de classe e objeto não são documentados usando este ambiente.

options

:type: type of the variable (text)¶: 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)¶: Describe the location where the object is defined if the object is imported from other modules

Adicionado na versão 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).

options

:final: (no value)¶: Indicate the class is a final class.

Adicionado na versão 3.1.

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

Adicionado na versão 7.1.

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

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

options

:canonical: (full qualified name including module name)¶: Describe the location where the object is defined if the object is imported from other modules

Adicionado na versão 4.0.

:final: (no value)¶: Indicate the class is a final class.

Adicionado na versão 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.

Adicionado na versão 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¶

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.

options

:type: type of the attribute (text)¶: 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)¶: Describe the location where the object is defined if the object is imported from other modules

Adicionado na versão 4.0.

.. py:property:: name¶

Describes an object property.

Adicionado na versão 4.0.

options

:abstractmethod: (no value)¶: Indicate the property is abstract.

:classmethod: (no value)¶: Indicate the property is a classmethod.

Adicionado na versão 4.2.

:type: type of the property (text)¶

.. 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 Lista Informação Campos.

options

:abstractmethod: (no value)¶: Indicate the method is an abstract method.

Adicionado na versão 2.1.

:async: (no value)¶: Indicate the method is an async method.

Adicionado na versão 2.1.

:canonical: (full qualified name including module name)¶: Describe the location where the object is defined if the object is imported from other modules

Adicionado na versão 4.0.

:classmethod: (no value)¶: Indicate the method is a class method.

Adicionado na versão 2.1.

:final: (no value)¶: Indicate the method is a final method.

Adicionado na versão 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.

Adicionado na versão 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.

Adicionado na versão 7.2.

:staticmethod: (no value)¶: Indicate the method is a static method.

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

Não há papel py:deco para vincular a um decorador que está marcado com esta diretiva; em vez disso, use o papel 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.

Adicionado na versão 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.

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.

Consulte um método decorador usando o papel py:meth.

Assinaturas Python¶

As assinaturas de funções, métodos e construtores de classes podem ser fornecidas como se fossem escritas em Python.

Valores padrão para argumentos opcionais podem ser fornecidos (mas se eles contiverem vírgulas, eles irão confundir o analisador de assinatura). Anotações de argumento no estilo Python 3 também podem ser fornecidas, bem como anotações de tipo de retorno:

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

Para funções com parâmetros opcionais que não têm valores padrão (normalmente funções implementadas em módulos de extensão C sem suporte de argumento nomeado), você pode usar colchetes para especificar as partes opcionais:

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

É comum colocar o colchete de abertura antes da vírgula.

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.

Lista Informação Campos¶

Adicionado na versão 0.4.

Alterado na versão 3.0: meta fields are added.

Dentro das diretivas de descrição de objeto Python, as listas de campos reST 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: 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.

Nota

In current release, all var, ivar and cvar are represented as “Variable”. There is no difference at all.

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

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:

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]

Vários tipos em um campo de tipo será vinculado automaticamente se separados pela palavra “or”:

:type an_arg: int or None
:vartype a_var: str or int
:rtype: float or 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: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

The role is also able to refer to property.

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

O nome incluído nesta marcação pode incluir um nome de módulo e/ou um nome de classe. Por exemplo, :py:func:`filter` pode fazer referência a uma função chamada filter no módulo atual, ou a função embutida com esse nome. Em contraste, :py:func:`foo.filter` claramente se refere à função filter no módulo foo.

Normalmente, os nomes nessas funções são pesquisados primeiro sem qualquer qualificação adicional, depois com o nome do módulo atual prefixado e, em seguida, com o módulo atual e o nome da classe (se houver) prefixados. Se você prefixar o nome com um ponto, a ordem será invertida. Por exemplo, na documentação do módulo codecs do Python, :py:func:`open` sempre se refere à função embutida, enquanto :py:func:`.open` refere-se a codecs.open().

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

Also, if the name is prefixed with a dot, and no exact match is found, the target is taken as a suffix and all object names with that suffix are searched. For example, :py:meth:`.TarFile.close` references the tarfile.TarFile.close() function, even if the current module is not tarfile. Since this can get ambiguous, if there is more than one possible match, you will get a warning from 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().

Sphinx

On this page

Site navigation

O Domínio Python¶

Assinaturas Python¶

Lista Informação Campos¶

Referência cruzada de objetos Python¶