types — Criação de tipos dinâmicos e nomes para tipos embutidos

Código-fonte: Lib/types.py

---

Este módulo define funções utilitárias para auxiliar na criação dinâmica de novos tipos.

Também define nomes para alguns tipos de objetos usados pelo interpretador Python padrão, mas não expostos como componentes embutidos como int ou str são.

Por fim, fornece algumas classes e funções adicionais relacionadas ao tipo que não são fundamentais o suficiente para serem incorporadas.

Criação de tipos dinâmicos

types.new_class(name, bases=(), kwds=None, exec_body=None)

Cria um objeto de classe dinamicamente usando a metaclasse apropriada.

Os três primeiros argumentos são os componentes que compõem um cabeçalho de definição de classe: o nome da classe, as classes base (em ordem), os argumentos nomeados (como metaclass).

The exec_body argument is a callback that is used to populate the freshly created class namespace. It should accept the class namespace as its sole argument and update the namespace directly with the class contents. If no callback is provided, it has the same effect as passing in lambda ns: None.

Novo na versão 3.3.

types.prepare_class(name, bases=(), kwds=None)

Calcula a metaclasse apropriada e cria o espaço de nomes da classe.

Os argumentos são os componentes que compõem um cabeçalho de definição de classe: o nome da classe, as classes base (em ordem) e os argumentos nomeados (como metaclass).

O valor de retorno é uma tupla de 3: metaclass, namespace, kwds

metaclass é a metaclasse apropriada, namespace é o espaço de nomes da classe preparada e kwds é uma cópia atualizada do argumento passado no kwds com qualquer entrada 'metaclass' removida. Se nenhum argumento kwds for passado, este será um ditado vazio.

Novo na versão 3.3.

Alterado na versão 3.6: O valor padrão para o elemento namespace da tupla retornada foi alterado. Agora, um mapeamento preservando-ordem-inserção é usado quando a metaclasse não possui um método __prepare__.

Ver também

Metaclasses

Detalhes completos do processo de criação de classe suportado por essas funções

PEP 3115 - Metaclasses no Python 3000

Introduzido o gancho de espaço de nomes __prepare__

types.resolve_bases(bases)

Resolve entradas MRO dinamicamente, conforme especificado pela PEP 560.

Esta função procura por itens em bases que não sejam instâncias de type e retorna uma tupla onde cada objeto que possui um método __mro_entries__ é substituído por um resultado descompactado da chamada desse método. Se um item bases é uma instância de type, ou não possui o método __mro_entries__, ele é incluído na tupla de retorno inalterada.

Novo na versão 3.7.

Ver também

PEP 560 - Suporte básico para inserir módulo e tipos genéricos

Tipos padrão do interpretador

Este módulo fornece nomes para muitos dos tipos necessários para implementar um interpretador Python. Evita deliberadamente incluir alguns dos tipos que surgem apenas incidentalmente durante o processamento, como o tipo listiterator.

O uso típico desses nomes é para verificações isinstance() ou issubclass().

Se você instanciar algum desses tipos, observe que as assinaturas podem variar entre as versões do Python.

Os nomes padrão são definidos para os seguintes tipos:

types.FunctionType

types.LambdaType

O tipo de funções definidas pelo usuário e funções criadas por expressões lambda.

Raises an auditing event function.__new__ with argument code.

The audit event only occurs for direct instantiation of function objects, and is not raised for normal compilation.

types.GeneratorType

O tipo de objetos de iterador gerador, criados pelas funções de gerador.

types.CoroutineType

O tipo de objetos de corrotina, criado por funções de async def.

Novo na versão 3.5.

types.AsyncGeneratorType

O tipo de objetos de iterador gerador assíncrono, criados pelas funções do gerador assíncrono.

Novo na versão 3.6.

class types.CodeType(**kwargs)

O tipo de objetos código retornados por compile().

Levanta um code.__new__ de evento de auditoria com os argumentos code, filename, name, argcount, posonlyargcount, kwonlyargcount, nlocals, stacksize, flags.

Note that the audited arguments may not match the names or positions required by the initializer. The audit event only occurs for direct instantiation of code objects, and is not raised for normal compilation.

replace(**kwargs)

Retorna uma cópia do objeto de código com novos valores para os campos especificados.

Novo na versão 3.8.

types.CellType

O tipo para objetos de célula: tais objetos são usados como contêineres para as variáveis livres de uma função.

Novo na versão 3.8.

types.MethodType

O tipo de método de instâncias de classe definidas pelo usuário.

types.BuiltinFunctionType

types.BuiltinMethodType

O tipo de funções embutidas como len() ou sys.exit(), e métodos de classes embutidas. (Aqui, o termo “embutidas” significa “escrito em C”.)

types.WrapperDescriptorType

O tipo de método de alguns tipos de dados embutidos e classes base, como object.__init__() ou object.__lt__().

Novo na versão 3.7.

types.MethodWrapperType

O tipo de métodos vinculados de alguns tipos de dados embutidos e classes base. Por exemplo, é o tipo de object().__str__.

Novo na versão 3.7.

types.MethodDescriptorType

O tipo de método de alguns tipos de dados embutidos, como str.join().

Novo na versão 3.7.

types.ClassMethodDescriptorType

O tipo de métodos de classe não vinculados de alguns tipos de dados embutidos, como dict.__dict__['fromkeys'].

Novo na versão 3.7.

class types.ModuleType(name, doc=None)

The type of modules. The constructor takes the name of the module to be created and optionally its docstring.

Nota

Use importlib.util.module_from_spec() para criar um novo módulo se você deseja definir os vários atributos controlados por importação.

__doc__

A docstring do módulo. O padrão é None.

__loader__

O carregador que carregou o módulo. O padrão é None.

This attribute is to match importlib.machinery.ModuleSpec.loader as stored in the attr:__spec__ object.

Nota

A future version of Python may stop setting this attribute by default. To guard against this potential change, preferrably read from the __spec__ attribute instead or use getattr(module, "__loader__", None) if you explicitly need to use this attribute.

Alterado na versão 3.4: O padrão é None. Anteriormente, o atributo era opcional.

__name__

The name of the module. Expected to match importlib.machinery.ModuleSpec.name.

__package__

A qual pacote um módulo pertence. Se o módulo é de nível superior (ou seja, não faz parte de nenhum pacote específico), o atributo deve ser definido como '', senão deve ser definido como o nome do pacote (que pode ser __name__ se o módulo for o próprio pacote). O padrão é None.

This attribute is to match importlib.machinery.ModuleSpec.parent as stored in the attr:__spec__ object.

Nota

A future version of Python may stop setting this attribute by default. To guard against this potential change, preferrably read from the __spec__ attribute instead or use getattr(module, "__package__", None) if you explicitly need to use this attribute.

Alterado na versão 3.4: O padrão é None. Anteriormente, o atributo era opcional.

__spec__

A record of the the module’s import-system-related state. Expected to be an instance of importlib.machinery.ModuleSpec.

Novo na versão 3.4.

class types.TracebackType(tb_next, tb_frame, tb_lasti, tb_lineno)

O tipo de objetos traceback, como encontrados em sys.exc_info()[2].

Veja a referência de linguagem para detalhes dos atributos e operações disponíveis, e orientação sobre como criar tracebacks dinamicamente.

types.FrameType

O tipo de objetos quadro, como encontrado em tb.tb_frame se tb é um objeto traceback.

Veja a referência de linguagem para detalhes dos atributos e operações disponíveis.

types.GetSetDescriptorType

O tipo de objetos definidos em módulos de extensão com PyGetSetDef, como FrameType.f_locals ou array.array.typecode. Este tipo é usado como descritor para atributos de objeto; tem o mesmo propósito que o tipo property, mas para classes definidas em módulos de extensão.

types.MemberDescriptorType

O tipo de objetos definidos em módulos de extensão com PyMemberDef, como datetime.timedelta.days. Este tipo é usado como descritor para membros de dados C simples que usam funções de conversão padrão; tem o mesmo propósito que o tipo property, mas para classes definidas em módulos de extensão.

CPython implementation detail: Em outras implementações de Python, este tipo pode ser idêntico a GetSetDescriptorType.

class types.MappingProxyType(mapping)

Proxy somente leitura de um mapeamento. Ele fornece uma visão dinâmica das entradas do mapeamento, o que significa que quando o mapeamento muda, a visão reflete essas mudanças.

Novo na versão 3.3.

key in proxy

Retorna True se o mapeamento subjacente tiver uma chave key, senão False.

proxy[key]

Retorna e o item do mapeamento subjacente com a chave key. Levanta um KeyError se key não estiver no mapeamento subjacente.

iter(proxy)

Retorna um iterador sobre as chaves do mapeamento subjacente. Este é um atalho para iter(proxy.keys()).

len(proxy)

Retorna o número de itens no mapeamento subjacente.

copy()

Retorna uma cópia rasa do mapeamento subjacente.

get(key[, default])

Retorna o valor para key se key estiver no mapeamento subjacente, caso contrário, default. Se default não for fornecido, o padrão é None, de forma que este método nunca levante uma KeyError.

items()

Retorna uma nova visão dos itens do mapeamento subjacente (pares (chave, valor)).

keys()

Retorna uma nova visão das chaves do mapeamento subjacente.

values()

Retorna uma nova visão dos valores do mapeamento subjacente.

Classes e funções de utilidades adicionais

class types.SimpleNamespace

Uma subclasse object simples que fornece acesso de atributo ao seu espaço de nomes, bem como um repr significativo.

Diferentemente de object, com SimpleNamespace você pode adicionar e remover atributos. Se um objeto SimpleNamespace é inicializado com argumentos nomeados, eles são adicionados diretamente ao espaço de nomes subjacente.

O tipo é aproximadamente equivalente ao seguinte código:

class SimpleNamespace:
    def __init__(self, /, **kwargs):
        self.__dict__.update(kwargs)

    def __repr__(self):
        keys = sorted(self.__dict__)
        items = ("{}={!r}".format(k, self.__dict__[k]) for k in keys)
        return "{}({})".format(type(self).__name__, ", ".join(items))

    def __eq__(self, other):
        if isinstance(self, SimpleNamespace) and isinstance(other, SimpleNamespace):
           return self.__dict__ == other.__dict__
        return NotImplemented

SimpleNamespace pode ser útil como um substituto para class NS: pass. No entanto, para um tipo de registro estruturado, use namedtuple().

Novo na versão 3.3.

types.DynamicClassAttribute(fget=None, fset=None, fdel=None, doc=None)

Roteia o acesso ao atributo em uma classe para __getattr__.

Este é um descritor, usado para definir atributos que atuam de forma diferente quando acessados por meio de uma instância e por meio de uma classe. O acesso à instância permanece normal, mas o acesso a um atributo por meio de uma classe será roteado para o método __getattr__ da classe; isso é feito levantando AttributeError.

This allows one to have properties active on an instance, and have virtual attributes on the class with the same name (see Enum for an example).

Novo na versão 3.4.

Funções de utilidade de corrotina

types.coroutine(gen_func)

Esta função transforma uma função geradora em uma função de corrotina que retorna uma corrotina baseada em gerador. A corrotina baseada em gerador ainda é um iterador gerador, mas também é considerada um objeto corrotina e é aguardável. No entanto, pode não necessariamente implementar o método __await__().

Se gen_func for uma função geradora, ela será modificada no local.

Se gen_func não for uma função geradora, ela será envolta. Se ele retornar uma instância de Collections.abc.Generator, a instância será envolvida em um objeto proxy aguardável. Todos os outros tipos de objetos serão retornados como estão.

Novo na versão 3.5.