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 Tipo Dinâmico

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

O argumento exec_body é um retorno de chamada usado para preencher o espaço de nomes da classe recém-criado. Ele deve aceitar o espaço de nomes da classe como seu único argumento e atualizar o espaço de nomes diretamente com o conteúdo da classe. Se nenhum retorno de chamada for fornecido, ele terá o mesmo efeito que passar em lambda ns: ns.

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

The type for cell objects: such objects are used as containers for a function’s free variables.

Novo na versão 3.8.

types.MethodType

The type of methods of user-defined class instances.

types.BuiltinFunctionType
types.BuiltinMethodType

The type of built-in functions like len() or sys.exit(), and methods of built-in classes. (Here, the term “built-in” means “written in C”.)

types.WrapperDescriptorType

The type of methods of some built-in data types and base classes such as object.__init__() or object.__lt__().

Novo na versão 3.7.

types.MethodWrapperType

The type of bound methods of some built-in data types and base classes. For example it is the type of object().__str__.

Novo na versão 3.7.

types.MethodDescriptorType

The type of methods of some built-in data types such as str.join().

Novo na versão 3.7.

types.ClassMethodDescriptorType

The type of unbound class methods of some built-in data types such as dict.__dict__['fromkeys'].

Novo na versão 3.7.

class types.ModuleType(name, doc=None)

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

Nota

Use importlib.util.module_from_spec() to create a new module if you wish to set the various import-controlled attributes.

__doc__

The docstring of the module. Defaults to None.

__loader__

The loader which loaded the module. Defaults to None.

Alterado na versão 3.4: Defaults to None. Previously the attribute was optional.

__name__

The name of the module.

__package__

Which package a module belongs to. If the module is top-level (i.e. not a part of any specific package) then the attribute should be set to '', else it should be set to the name of the package (which can be __name__ if the module is a package itself). Defaults to None.

Alterado na versão 3.4: Defaults to None. Previously the attribute was optional.

class types.GenericAlias(t_origin, t_args)

The type of parameterized generics such as list[int].

t_origin should be a non-parameterized generic class, such as list, tuple or dict. t_args should be a tuple (possibly of length 1) of types which parameterize t_origin:

>>> from types import GenericAlias

>>> list[int] == GenericAlias(list, (int,))
True
>>> dict[str, int] == GenericAlias(dict, (str, int))
True

Novo na versão 3.9.

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

The type of traceback objects such as found in sys.exc_info()[2].

See the language reference for details of the available attributes and operations, and guidance on creating tracebacks dynamically.

types.FrameType

The type of frame objects such as found in tb.tb_frame if tb is a traceback object.

See the language reference for details of the available attributes and operations.

types.GetSetDescriptorType

The type of objects defined in extension modules with PyGetSetDef, such as FrameType.f_locals or array.array.typecode. This type is used as descriptor for object attributes; it has the same purpose as the property type, but for classes defined in extension modules.

types.MemberDescriptorType

The type of objects defined in extension modules with PyMemberDef, such as datetime.timedelta.days. This type is used as descriptor for simple C data members which use standard conversion functions; it has the same purpose as the property type, but for classes defined in extension modules.

CPython implementation detail: In other implementations of Python, this type may be identical to GetSetDescriptorType.

class types.MappingProxyType(mapping)

Read-only proxy of a mapping. It provides a dynamic view on the mapping’s entries, which means that when the mapping changes, the view reflects these changes.

Novo na versão 3.3.

Alterado na versão 3.9: Updated to support the new union (|) operator from PEP 584, which simply delegates to the underlying mapping.

key in proxy

Return True if the underlying mapping has a key key, else False.

proxy[key]

Return the item of the underlying mapping with key key. Raises a KeyError if key is not in the underlying mapping.

iter(proxy)

Return an iterator over the keys of the underlying mapping. This is a shortcut for iter(proxy.keys()).

len(proxy)

Return the number of items in the underlying mapping.

copy()

Return a shallow copy of the underlying mapping.

get(key[, default])

Return the value for key if key is in the underlying mapping, else default. If default is not given, it defaults to None, so that this method never raises a KeyError.

items()

Return a new view of the underlying mapping’s items ((key, value) pairs).

keys()

Return a new view of the underlying mapping’s keys.

values()

Return a new view of the underlying mapping’s values.

reversed(proxy)

Return a reverse iterator over the keys of the underlying mapping.

Novo na versão 3.9.

Additional Utility Classes and Functions

class types.SimpleNamespace

A simple object subclass that provides attribute access to its namespace, as well as a meaningful repr.

Unlike object, with SimpleNamespace you can add and remove attributes. If a SimpleNamespace object is initialized with keyword arguments, those are directly added to the underlying namespace.

The type is roughly equivalent to the following code:

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

    def __repr__(self):
        items = (f"{k}={v!r}" for k, v in self.__dict__.items())
        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 may be useful as a replacement for class NS: pass. However, for a structured record type use namedtuple() instead.

Novo na versão 3.3.

Alterado na versão 3.9: Attribute order in the repr changed from alphabetical to insertion (like dict).

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

Route attribute access on a class to __getattr__.

This is a descriptor, used to define attributes that act differently when accessed through an instance and through a class. Instance access remains normal, but access to an attribute through a class will be routed to the class’s __getattr__ method; this is done by raising AttributeError.

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

Novo na versão 3.4.

Coroutine Utility Functions

types.coroutine(gen_func)

This function transforms a generator function into a coroutine function which returns a generator-based coroutine. The generator-based coroutine is still a generator iterator, but is also considered to be a coroutine object and is awaitable. However, it may not necessarily implement the __await__() method.

If gen_func is a generator function, it will be modified in-place.

If gen_func is not a generator function, it will be wrapped. If it returns an instance of collections.abc.Generator, the instance will be wrapped in an awaitable proxy object. All other types of objects will be returned as is.

Novo na versão 3.5.