Objetos tipo¶
-
type PyTypeObject¶
- Parte da API Limitada (como uma estrutura opaca).
A estrutura C dos objetos usados para descrever tipos embutidos.
-
PyTypeObject PyType_Type¶
- Parte da ABI Estável.
Este é o objeto de tipo para objetos tipo; é o mesmo objeto que
type
na camada Python.
-
int PyType_Check(PyObject *o)¶
Retorna valor diferente de zero se o objeto o for um objeto tipo, incluindo instâncias de tipos derivados do objeto tipo padrão. Retorna 0 em todos os outros casos. Esta função sempre tem sucesso.
-
int PyType_CheckExact(PyObject *o)¶
Retorna valor diferente de zero se o objeto o for um objeto tipo, mas não um subtipo do objeto tipo padrão. Retorna 0 em todos os outros casos. Esta função sempre tem sucesso.
-
unsigned int PyType_ClearCache()¶
- Parte da ABI Estável.
Limpa o cache de pesquisa interno. Retorna a marcação de versão atual.
-
unsigned long PyType_GetFlags(PyTypeObject *type)¶
- Parte da ABI Estável.
Return the
tp_flags
member of type. This function is primarily meant for use withPy_LIMITED_API
; the individual flag bits are guaranteed to be stable across Python releases, but access totp_flags
itself is not part of the limited API.Adicionado na versão 3.2.
Alterado na versão 3.4: O tipo de retorno é agora um
unsigned long
em vez de umlong
.
-
PyObject *PyType_GetDict(PyTypeObject *type)¶
Return the type object’s internal namespace, which is otherwise only exposed via a read-only proxy (
cls.__dict__
). This is a replacement for accessingtp_dict
directly. The returned dictionary must be treated as read-only.This function is meant for specific embedding and language-binding cases, where direct access to the dict is necessary and indirect access (e.g. via the proxy or
PyObject_GetAttr()
) isn’t adequate.Extension modules should continue to use
tp_dict
, directly or indirectly, when setting up their own types.Adicionado na versão 3.12.
-
void PyType_Modified(PyTypeObject *type)¶
- Parte da ABI Estável.
Invalida o cache de pesquisa interna para o tipo e todos os seus subtipos. Esta função deve ser chamada após qualquer modificação manual dos atributos ou classes bases do tipo.
-
int PyType_AddWatcher(PyType_WatchCallback callback)¶
Register callback as a type watcher. Return a non-negative integer ID which must be passed to future calls to
PyType_Watch()
. In case of error (e.g. no more watcher IDs available), return-1
and set an exception.Adicionado na versão 3.12.
-
int PyType_ClearWatcher(int watcher_id)¶
Clear watcher identified by watcher_id (previously returned from
PyType_AddWatcher()
). Return0
on success,-1
on error (e.g. if watcher_id was never registered.)An extension should never call
PyType_ClearWatcher
with a watcher_id that was not returned to it by a previous call toPyType_AddWatcher()
.Adicionado na versão 3.12.
-
int PyType_Watch(int watcher_id, PyObject *type)¶
Mark type as watched. The callback granted watcher_id by
PyType_AddWatcher()
will be called wheneverPyType_Modified()
reports a change to type. (The callback may be called only once for a series of consecutive modifications to type, if_PyType_Lookup()
is not called on type between the modifications; this is an implementation detail and subject to change.)An extension should never call
PyType_Watch
with a watcher_id that was not returned to it by a previous call toPyType_AddWatcher()
.Adicionado na versão 3.12.
-
typedef int (*PyType_WatchCallback)(PyObject *type)¶
Type of a type-watcher callback function.
The callback must not modify type or cause
PyType_Modified()
to be called on type or any type in its MRO; violating this rule could cause infinite recursion.Adicionado na versão 3.12.
-
int PyType_HasFeature(PyTypeObject *o, int feature)¶
Retorna valor diferente de zero se o objeto tipo o define o recurso feature. Os recursos de tipo são denotados por sinalizadores de bit único.
-
int PyType_IS_GC(PyTypeObject *o)¶
Return true if the type object includes support for the cycle detector; this tests the type flag
Py_TPFLAGS_HAVE_GC
.
-
int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)¶
- Parte da ABI Estável.
Retorna verdadeiro se a for um subtipo de b.
This function only checks for actual subtypes, which means that
__subclasscheck__()
is not called on b. CallPyObject_IsSubclass()
to do the same check thatissubclass()
would do.
-
PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)¶
- Retorna valor: Nova referência. Parte da ABI Estável.
Manipulador genérico para o slot
tp_alloc
de um objeto tipo. Use o mecanismo de alocação de memória padrão do Python para alocar uma nova instância e inicializar todo o seu conteúdo paraNULL
.
-
PyObject *PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)¶
- Retorna valor: Nova referência. Parte da ABI Estável.
Manipulador genérico para o slot
tp_new
de um objeto tipo. Cria uma nova instância usando o slottp_alloc
do tipo.
-
int PyType_Ready(PyTypeObject *type)¶
- Parte da ABI Estável.
Finaliza um objeto tipo. Isso deve ser chamado em todos os objetos tipo para finalizar sua inicialização. Esta função é responsável por adicionar slots herdados da classe base de um tipo. Retorna
0
em caso de sucesso, ou retorna-1
e define uma exceção em caso de erro.Nota
If some of the base classes implements the GC protocol and the provided type does not include the
Py_TPFLAGS_HAVE_GC
in its flags, then the GC protocol will be automatically implemented from its parents. On the contrary, if the type being created does includePy_TPFLAGS_HAVE_GC
in its flags then it must implement the GC protocol itself by at least implementing thetp_traverse
handle.
-
PyObject *PyType_GetName(PyTypeObject *type)¶
- Retorna valor: Nova referência. Parte da ABI Estável desde a versão 3.11.
Return the type’s name. Equivalent to getting the type’s
__name__
attribute.Adicionado na versão 3.11.
-
PyObject *PyType_GetQualName(PyTypeObject *type)¶
- Retorna valor: Nova referência. Parte da ABI Estável desde a versão 3.11.
Return the type’s qualified name. Equivalent to getting the type’s
__qualname__
attribute.Adicionado na versão 3.11.
-
PyObject *PyType_GetFullyQualifiedName(PyTypeObject *type)¶
- Parte da ABI Estável desde a versão 3.13.
Return the type’s fully qualified name. Equivalent to
f"{type.__module__}.{type.__qualname__}"
, ortype.__qualname__
iftype.__module__
is not a string or is equal to"builtins"
.Adicionado na versão 3.13.
-
PyObject *PyType_GetModuleName(PyTypeObject *type)¶
- Parte da ABI Estável desde a versão 3.13.
Return the type’s module name. Equivalent to getting the
type.__module__
attribute.Adicionado na versão 3.13.
-
void *PyType_GetSlot(PyTypeObject *type, int slot)¶
- Parte da ABI Estável desde a versão 3.4.
Retorna o ponteiro de função armazenado no slot fornecido. Se o resultado for
NULL
, isso indica que o slot éNULL
ou que a função foi chamada com parâmetros inválidos. Os chamadores normalmente lançarão o ponteiro do resultado no tipo de função apropriado.Veja
PyType_Slot.slot
por possíveis valores do argumento slot.Adicionado na versão 3.4.
Alterado na versão 3.10:
PyType_GetSlot()
can now accept all types. Previously, it was limited to heap types.
-
PyObject *PyType_GetModule(PyTypeObject *type)¶
- Parte da ABI Estável desde a versão 3.10.
Retorna o objeto de módulo associado ao tipo fornecido quando o tipo foi criado usando
PyType_FromModuleAndSpec()
.Se nenhum módulo estiver associado com o tipo fornecido, define
TypeError
e retornaNULL
.This function is usually used to get the module in which a method is defined. Note that in such a method,
PyType_GetModule(Py_TYPE(self))
may not return the intended result.Py_TYPE(self)
may be a subclass of the intended class, and subclasses are not necessarily defined in the same module as their superclass. SeePyCMethod
to get the class that defines the method. SeePyType_GetModuleByDef()
for cases whenPyCMethod
cannot be used.Adicionado na versão 3.9.
-
void *PyType_GetModuleState(PyTypeObject *type)¶
- Parte da ABI Estável desde a versão 3.10.
Return the state of the module object associated with the given type. This is a shortcut for calling
PyModule_GetState()
on the result ofPyType_GetModule()
.Se nenhum módulo estiver associado com o tipo fornecido, define
TypeError
e retornaNULL
.If the type has an associated module but its state is
NULL
, returnsNULL
without setting an exception.Adicionado na versão 3.9.
-
PyObject *PyType_GetModuleByDef(PyTypeObject *type, struct PyModuleDef *def)¶
- Parte da ABI Estável desde a versão 3.13.
Find the first superclass whose module was created from the given
PyModuleDef
def, and return that module.If no module is found, raises a
TypeError
and returnsNULL
.This function is intended to be used together with
PyModule_GetState()
to get module state from slot methods (such astp_init
ornb_add
) and other places where a method’s defining class cannot be passed using thePyCMethod
calling convention.Adicionado na versão 3.11.
-
int PyUnstable_Type_AssignVersionTag(PyTypeObject *type)¶
- Esta é uma API Instável. Isso pode se alterado sem aviso em lançamentos menores.
Attempt to assign a version tag to the given type.
Returns 1 if the type already had a valid version tag or a new one was assigned, or 0 if a new tag could not be assigned.
Adicionado na versão 3.12.
Creating Heap-Allocated Types¶
The following functions and structs are used to create heap types.
-
PyObject *PyType_FromMetaclass(PyTypeObject *metaclass, PyObject *module, PyType_Spec *spec, PyObject *bases)¶
- Parte da ABI Estável desde a versão 3.12.
Create and return a heap type from the spec (see
Py_TPFLAGS_HEAPTYPE
).The metaclass metaclass is used to construct the resulting type object. When metaclass is
NULL
, the metaclass is derived from bases (or Py_tp_base[s] slots if bases isNULL
, see below).Metaclasses that override
tp_new
are not supported, except iftp_new
isNULL
. (For backwards compatibility, otherPyType_From*
functions allow such metaclasses. They ignoretp_new
, which may result in incomplete initialization. This is deprecated and in Python 3.14+ such metaclasses will not be supported.)The bases argument can be used to specify base classes; it can either be only one class or a tuple of classes. If bases is
NULL
, the Py_tp_bases slot is used instead. If that also isNULL
, the Py_tp_base slot is used instead. If that also isNULL
, the new type derives fromobject
.The module argument can be used to record the module in which the new class is defined. It must be a module object or
NULL
. If notNULL
, the module is associated with the new type and can later be retrieved withPyType_GetModule()
. The associated module is not inherited by subclasses; it must be specified for each class individually.This function calls
PyType_Ready()
on the new type.Note that this function does not fully match the behavior of calling
type()
or using theclass
statement. With user-provided base types or metaclasses, prefer callingtype
(or the metaclass) overPyType_From*
functions. Specifically:__new__()
is not called on the new class (and it must be set totype.__new__
).__init__()
is not called on the new class.__init_subclass__()
is not called on any bases.__set_name__()
is not called on new descriptors.
Adicionado na versão 3.12.
-
PyObject *PyType_FromModuleAndSpec(PyObject *module, PyType_Spec *spec, PyObject *bases)¶
- Retorna valor: Nova referência. Parte da ABI Estável desde a versão 3.10.
Equivalent to
PyType_FromMetaclass(NULL, module, spec, bases)
.Adicionado na versão 3.9.
Alterado na versão 3.10: The function now accepts a single class as the bases argument and
NULL
as thetp_doc
slot.Alterado na versão 3.12: The function now finds and uses a metaclass corresponding to the provided base classes. Previously, only
type
instances were returned.The
tp_new
of the metaclass is ignored. which may result in incomplete initialization. Creating classes whose metaclass overridestp_new
is deprecated and in Python 3.14+ it will be no longer allowed.
-
PyObject *PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)¶
- Retorna valor: Nova referência. Parte da ABI Estável desde a versão 3.3.
Equivalent to
PyType_FromMetaclass(NULL, NULL, spec, bases)
.Adicionado na versão 3.3.
Alterado na versão 3.12: The function now finds and uses a metaclass corresponding to the provided base classes. Previously, only
type
instances were returned.The
tp_new
of the metaclass is ignored. which may result in incomplete initialization. Creating classes whose metaclass overridestp_new
is deprecated and in Python 3.14+ it will be no longer allowed.
-
PyObject *PyType_FromSpec(PyType_Spec *spec)¶
- Retorna valor: Nova referência. Parte da ABI Estável.
Equivalent to
PyType_FromMetaclass(NULL, NULL, spec, NULL)
.Alterado na versão 3.12: The function now finds and uses a metaclass corresponding to the base classes provided in Py_tp_base[s] slots. Previously, only
type
instances were returned.The
tp_new
of the metaclass is ignored. which may result in incomplete initialization. Creating classes whose metaclass overridestp_new
is deprecated and in Python 3.14+ it will be no longer allowed.
-
type PyType_Spec¶
- Parte da ABI Estável (incluindo todos os membros).
Structure defining a type’s behavior.
-
const char *name¶
Name of the type, used to set
PyTypeObject.tp_name
.
-
int basicsize¶
If positive, specifies the size of the instance in bytes. It is used to set
PyTypeObject.tp_basicsize
.If zero, specifies that
tp_basicsize
should be inherited.If negative, the absolute value specifies how much space instances of the class need in addition to the superclass. Use
PyObject_GetTypeData()
to get a pointer to subclass-specific memory reserved this way.Alterado na versão 3.12: Previously, this field could not be negative.
-
int itemsize¶
Size of one element of a variable-size type, in bytes. Used to set
PyTypeObject.tp_itemsize
. Seetp_itemsize
documentation for caveats.If zero,
tp_itemsize
is inherited. Extending arbitrary variable-sized classes is dangerous, since some types use a fixed offset for variable-sized memory, which can then overlap fixed-sized memory used by a subclass. To help prevent mistakes, inheritingitemsize
is only possible in the following situations:The base is not variable-sized (its
tp_itemsize
).The requested
PyType_Spec.basicsize
is positive, suggesting that the memory layout of the base class is known.The requested
PyType_Spec.basicsize
is zero, suggesting that the subclass does not access the instance’s memory directly.With the
Py_TPFLAGS_ITEMS_AT_END
flag.
-
unsigned int flags¶
Type flags, used to set
PyTypeObject.tp_flags
.If the
Py_TPFLAGS_HEAPTYPE
flag is not set,PyType_FromSpecWithBases()
sets it automatically.
-
PyType_Slot *slots¶
Array of
PyType_Slot
structures. Terminated by the special slot value{0, NULL}
.Each slot ID should be specified at most once.
-
const char *name¶
-
type PyType_Slot¶
- Parte da ABI Estável (incluindo todos os membros).
Structure defining optional functionality of a type, containing a slot ID and a value pointer.
-
int slot¶
A slot ID.
Slot IDs are named like the field names of the structures
PyTypeObject
,PyNumberMethods
,PySequenceMethods
,PyMappingMethods
andPyAsyncMethods
with an addedPy_
prefix. For example, use:Py_tp_dealloc
to setPyTypeObject.tp_dealloc
Py_nb_add
to setPyNumberMethods.nb_add
Py_sq_length
to setPySequenceMethods.sq_length
The following “offset” fields cannot be set using
PyType_Slot
:tp_weaklistoffset
(usePy_TPFLAGS_MANAGED_WEAKREF
instead if possible)tp_dictoffset
(usePy_TPFLAGS_MANAGED_DICT
instead if possible)tp_vectorcall_offset
(use"__vectorcalloffset__"
in PyMemberDef)
If it is not possible to switch to a
MANAGED
flag (for example, for vectorcall or to support Python older than 3.12), specify the offset inPy_tp_members
. See PyMemberDef documentation for details.The following fields cannot be set at all when creating a heap type:
tp_vectorcall
(usetp_new
and/ortp_init
)Internal fields:
tp_dict
,tp_mro
,tp_cache
,tp_subclasses
, andtp_weaklist
.
Setting
Py_tp_bases
orPy_tp_base
may be problematic on some platforms. To avoid issues, use the bases argument ofPyType_FromSpecWithBases()
instead.Alterado na versão 3.9: Slots in
PyBufferProcs
may be set in the unlimited API.Alterado na versão 3.11:
bf_getbuffer
andbf_releasebuffer
are now available under the limited API.
-
void *pfunc¶
The desired value of the slot. In most cases, this is a pointer to a function.
Slots other than
Py_tp_doc
may not beNULL
.
-
int slot¶