inspect — Inspeccionar objetos vivos

Código fuente: Lib/inspect.py

---

El módulo inspect proporciona varias funciones útiles para ayudar a obtener información sobre objetos vivos como módulos, clases, métodos, funciones, tracebacks, objetos de marco y objetos de código. Por ejemplo, puede ayudarte a examinar el contenido de una clase, recuperar el código fuente de un método, extraer y dar formato a la lista de argumentos de una función, u obtener toda la información que necesitas para mostrar un traceback detallado.

Hay cuatro tipos principales de servicios que ofrece este módulo: comprobación de tipos, obtención del código fuente, inspección de clases y funciones, y examinar la pila del intérprete.

Tipos y miembros

La función getmembers() recupera los miembros de un objeto como una clase o un módulo. Las funciones cuyos nombres comienzan con «is» se proveen principalmente como opciones convenientes para el segundo argumento de getmembers(). También ayudan a determinar cuándo se puede esperar encontrar los siguientes atributos especiales:

Tipo	Atributo	Descripción
módulo	__doc__	cadena de caracteres de documentación
	__file__	nombre de archivo (falta para los módulos incorporados)
clase	__doc__	cadena de caracteres de documentación
	__name__	nombre con el que se definió esta clase
	__qualname__	nombre calificado
	__module__	nombre del módulo en el que se definió esta clase
método	__doc__	cadena de caracteres de documentación
	__name__	nombre con el que se definió este método
	__qualname__	nombre calificado
	__func__	objeto función que contiene la implementación del método
	__self__	instancia a la que este método está ligado, o None
	__module__	nombre del módulo en el cual este método fue definido
función	__doc__	cadena de caracteres de documentación
	__name__	nombre con el que se definió esta función
	__qualname__	nombre calificado
	__code__	objeto de código que contiene la función compilada bytecode
	__defaults__	tupla de cualquier valor por defecto para los parámetros de posición o de palabras clave
	__kwdefaults__	mapeo de cualquier valor predeterminado para parámetros de sólo palabras clave
	__globals__	namespace global en el que se definió esta función
	__builtins__	Espacio de nombres builtins
	__annotations__	mapeo de los nombres de parámetros a las anotaciones; la tecla "return" está reservada para las anotaciones de retorno.
	__module__	nombre del módulo en el cual esta función fue definida
traceback	tb_frame	enmarcar el objeto a este nivel
	tb_lasti	índice del último intento de instrucción en código de bytes
	tb_lineno	número de línea actual en el código fuente de Python
	tb_next	el siguiente objeto de traceback interno (llamado por este nivel)
marco	f_back	el siguiente objeto exterior del marco (el que llama a este marco)
	f_builtins	construye el namespace visto por este marco
	f_code	objeto de código que se ejecuta en este marco
	f_globals	el namespace global visto por este marco
	f_lasti	índice del último intento de instrucción en código de bytes
	f_lineno	número de línea actual en el código fuente de Python
	f_locals	el namespace local visto por este marco
	f_trace	función de rastreo para este marco, o None
code	co_argcount	número de argumentos (sin incluir los argumentos de palabras clave, * o ** args)
	co_code	cadena de bytecode compilados en bruto
	co_cellvars	tupla de nombres de variables de celda (referenciados por contener alcances)
	co_consts	tupla de constantes utilizadas en el bytecode
	co_filename	nombre del archivo en el que este objeto código fue creado
	co_firstlineno	número de la primera línea del código fuente de Python
	co_flags	mapa de bits de los flags CO_*, leer más aquí
	co_lnotab	mapeo codificado de los números de línea a los índices de bytecode
	co_freevars	tupla de nombres de variables libres (referenciados a través del cierre de una función)
	co_posonlyargcount	número de argumentos solo posicionales
	co_kwonlyargcount	número de argumentos de sólo palabras clave (sin incluir el ** arg)
	co_name	nombre con el que se definió este objeto de código
	co_names	tuple of names other than arguments and function locals
	co_nlocals	número de variables locales
	co_stacksize	se requiere espacio en la pila de máquina virtual
	co_varnames	tupla de nombres de argumentos y variables locales
generador	__name__	nombre
	__qualname__	nombre calificado
	gi_frame	marco
	gi_running	¿Está el generador en ejecución?
	gi_code	code
	gi_yieldfrom	el objeto siendo iterado por yield from, o None
corutina	__name__	nombre
	__qualname__	nombre calificado
	cr_await	objeto al que se espera, o None
	cr_frame	marco
	cr_running	¿Está la corutina en ejecución?
	cr_code	code
	cr_origin	donde se creó la corutina, o None. Ver sys.set_coroutine_origin_tracking_depth()
incorporado	__doc__	cadena de caracteres de documentación
	__name__	nombre original de esta función o método
	__qualname__	nombre calificado
	__self__	instancia a la que está ligada un método, o None

Distinto en la versión 3.5: Agrega atributos __qualname__ y gi_yieldfrom a los generadores.

El atributo __name__ de los generadores se establece ahora a partir del nombre de la función, en lugar del nombre del código, y ahora puede ser modificado.

Distinto en la versión 3.7: Agrega el atributo cr_origin a las corutinas.

Distinto en la versión 3.10: Agrega el atributo __builtins__ a funciones.

inspect.getmembers(object[, predicate])

Retorna todos los miembros de un objeto en una lista de pares (name, value) ordenados por nombre. Si se proporciona el argumento predicate opcional, que se llamará con el objeto value de cada miembro, solo se incluyen los miembros para los que el predicado retorna un valor verdadero.

Nota

getmembers() sólo retornará los atributos de clase definidos en la metaclase cuando el argumento sea una clase y esos atributos hayan sido listados en la costumbre de la metaclase __dir__().

inspect.getmodulename(path)

Retorna el nombre del módulo nombrado por el ruta de archivo, sin incluir los nombres de los paquetes adjuntos. La extensión del archivo se comprueba con todas las entradas en importlib.machinery.all_suffixes(). Si coincide, el componente final de la ruta se retorna con la extensión eliminada. En caso contrario, se retorna None.

Ten en cuenta que esta función sólo retorna un nombre significativo para los módulos reales de Python - las rutas que potencialmente se refieren a los paquetes de Python seguirán retornando None.

Distinto en la versión 3.3: La función se basa directamente en importlib.

inspect.ismodule(object)

Retorna True si el objeto es un módulo.

inspect.isclass(object)

Retorna True si el objeto es una clase, ya sea incorporada o creada en código Python.

inspect.ismethod(object)

Retorna True si el objeto es un método ligado escrito en Python.

inspect.isfunction(object)

Retorna True si el objeto es una función de Python, que incluye funciones creadas por una expresión lambda.

inspect.isgeneratorfunction(object)

Retorna True si el objeto es una función generadora de Python.

Distinto en la versión 3.8: Funciones envueltas en functools.partial() ahora retornan True si la función envuelta es una función Python generadora.

inspect.isgenerator(object)

Retorna True si el objeto es un generador.

inspect.iscoroutinefunction(object)

Retorna True si el objeto es una coroutine function (una función definida con una sintaxis async def).

Nuevo en la versión 3.5.

Distinto en la versión 3.8: Funciones envueltas en functools.partial() ahora retornan True si la función envuelta es un coroutine function.

inspect.iscoroutine(object)

Retorna verdadero si el objeto es un coroutine creado por una función async def.

Nuevo en la versión 3.5.

inspect.isawaitable(object)

Retorna True si el objeto puede ser usado en la expresión await.

También se puede utilizar para distinguir las corutinas basadas en generadores de los generadores normales:

def gen():
    yield
@types.coroutine
def gen_coro():
    yield

assert not isawaitable(gen())
assert isawaitable(gen_coro())

Nuevo en la versión 3.5.

inspect.isasyncgenfunction(object)

Retorna True si el objeto es una función asynchronous generator, por ejemplo:

>>> async def agen():
...     yield 1
...
>>> inspect.isasyncgenfunction(agen)
True

Nuevo en la versión 3.6.

Distinto en la versión 3.8: Funciones envueltas en functools.partial() ahora retornan True si la función envuelta es una función asynchronous generator.

inspect.isasyncgen(object)

Retorna verdadero si el objeto es un asynchronous generator iterator creado por una función asynchronous generator.

Nuevo en la versión 3.6.

inspect.istraceback(object)

Retorna True si el objeto es un traceback.

inspect.isframe(object)

Retorna True si el objeto es un marco.

inspect.iscode(object)

Retorna True si el objeto es un código.

inspect.isbuiltin(object)

Retorna True si el objeto es una función incorporada o un método ligado incorporado.

inspect.isroutine(object)

Retorna True si el objeto es una función o método definido por el usuario o incorporado.

inspect.isabstract(object)

Retorna True si el objeto es una clase base abstracta.

inspect.ismethoddescriptor(object)

Retorna True si el objeto es un descriptor de método, pero no si ismethod(), isclass(), isfunction() o isbuiltin() son verdaderos.

Esto, por ejemplo, es cierto para int.__add__. Un objeto que pasa esta prueba tiene un método __get__() pero no un método __set__(), pero más allá de eso el conjunto de atributos varía. Un atributo __name__ suele ser sensato, y __doc__ a menudo lo es.

Los métodos implementados a través de descriptores que también pasan una de las otras pruebas retornan False a la prueba ismethoddescriptor(), simplemente porque las otras pruebas prometen más – puede, por ejemplo, contar con tener el atributo __func__ (etc) cuando un objeto pasa ismethod().

inspect.isdatadescriptor(object)

Retorna True si el objeto es un descriptor de datos.

Los descriptores de datos tienen un método __set__ o un método __delete__. Los ejemplos son propiedades (definidas en Python), conjuntos y miembros. Los dos últimos están definidos en C y hay pruebas más específicas disponibles para esos tipos, lo cual es robusto en todas las implementaciones de Python. Típicamente, los descriptores de datos también tendrán los atributos __name__ y __doc__ (las propiedades, conjuntos y miembros tienen ambos atributos), pero esto no está garantizado.

inspect.isgetsetdescriptor(object)

Retorna True si el objeto es un descriptor de conjunto.

Detalles de implementación de CPython: conjuntos son atributos definidos en módulos de extensión a través de estructuras PyGetSetDef. Para implementaciones de Python sin tales tipos, este método siempre retornará False.

inspect.ismemberdescriptor(object)

Retorna True si el objeto es un descriptor de miembro.

Detalles de implementación de CPython: Los descriptores de miembros son atributos definidos en los módulos de extensión a través de las estructuras PyMemberDef. Para implementaciones de Python sin tales tipos, este método siempre retornará False.

Recuperar el código fuente

inspect.getdoc(object)

Get the documentation string for an object, cleaned up with cleandoc(). If the documentation string for an object is not provided and the object is a class, a method, a property or a descriptor, retrieve the documentation string from the inheritance hierarchy. Return None if the documentation string is invalid or missing.

Distinto en la versión 3.5: Las cadenas de documentación son ahora heredadas, si no anuladas.

inspect.getcomments(object)

Retorna en una sola cadena las líneas de comentarios que preceden inmediatamente al código fuente del objeto (para una clase, función o método), o en la parte superior del archivo fuente de Python (si el objeto es un módulo). Si el código fuente del objeto no está disponible, retorna None. Esto podría suceder si el objeto ha sido definido en C o en el shell interactivo.

inspect.getfile(object)

Retorna el nombre del archivo (de texto o binario) en el que se definió un objeto. Esto fallará con un TypeError si el objeto es un módulo, clase o función incorporada.

inspect.getmodule(object)

Try to guess which module an object was defined in. Return None if the module cannot be determined.

inspect.getsourcefile(object)

Return the name of the Python source file in which an object was defined or None if no way can be identified to get the source. This will fail with a TypeError if the object is a built-in module, class, or function.

inspect.getsourcelines(object)

Return a list of source lines and starting line number for an object. The argument may be a module, class, method, function, traceback, frame, or code object. The source code is returned as a list of the lines corresponding to the object and the line number indicates where in the original source file the first line of code was found. An OSError is raised if the source code cannot be retrieved. A TypeError is raised if the object is a built-in module, class, or function.

Distinto en la versión 3.3: OSError se lanza en lugar de IOError, ahora un alias del primero.

inspect.getsource(object)

Return the text of the source code for an object. The argument may be a module, class, method, function, traceback, frame, or code object. The source code is returned as a single string. An OSError is raised if the source code cannot be retrieved. A TypeError is raised if the object is a built-in module, class, or function.

Distinto en la versión 3.3: OSError se lanza en lugar de IOError, ahora un alias del primero.

inspect.cleandoc(doc)

Limpiar la indentación de los docstrings que están indentados para alinearse con los bloques de código.

Todos los espacios blancos principales se eliminan de la primera línea. Cualquier espacio blanco principal que pueda ser uniformemente removido de la segunda línea en adelante es removido. Las líneas vacías al principio y al final se eliminan posteriormente. Además, todas las pestañas se expanden a los espacios.

Introspección de los invocables con el objeto Signature

Nuevo en la versión 3.3.

El objeto Signature representa la firma de llamada de un objeto invocable y su anotación de retorno. Para recuperar un objeto Signature, utilice la función signature().

inspect.signature(callable, *, follow_wrapped=True, globals=None, locals=None, eval_str=False)

Retorna un objeto Signature para el callable dado:

>>> from inspect import signature
>>> def foo(a, *, b:int, **kwargs):
...     pass

>>> sig = signature(foo)

>>> str(sig)
'(a, *, b:int, **kwargs)'

>>> str(sig.parameters['b'])
'b:int'

>>> sig.parameters['b'].annotation
<class 'int'>

Acepta un amplio rango de invocables de Python, desde funciones y clases simples hasta objetos functools.partial().

Para los objetos definidos en módulos que utilizan anotaciones convertidas a cadenas (from __future__ import annotations), signature() intentará invertir la conversión a cadenas de las anotaciones automáticamente usando inspect.get_annotations(). Los parámetros global, locals, y eval_str se pasan a inspect.get_annotations() al resolver las anotaciones; consulte la documentación de inspect.get_annotations() para obtener instrucciones sobre cómo utilizar estos parámetros.

Lanza ValueError si no se puede proporcionar ninguna signatura, y TypeError si ese tipo de objeto no es compatible. Además, si las anotaciones están convertidas a cadenas y eval_str no es falso, las llamadas eval() para invertir la conversión a cadenas de las anotaciones podrían generar cualquier tipo de excepción.

Una barra (/) en la signature de una función denota que los parámetros anteriores a ella son sólo posicionales. Para más información, ver la pregunta frecuente en parámetros solo posicionales.

Nuevo en la versión 3.5: parámetro follow_wrapped. Pasa False para obtener un signature de callable específicamente (callable.__wrapped__ no se usará para desenvolver los invocables decorados.)

Nuevo en la versión 3.10: Parámetros globals, locals, y eval_str

Nota

Algunos invocables pueden no ser introspeccionables en ciertas implementaciones de Python. Por ejemplo, en CPython, algunas funciones incorporadas definidas en C no proporcionan metadatos sobre sus argumentos.

class inspect.Signature(parameters=None, *, return_annotation=Signature.empty)

Un objeto Signature representa la firma de llamada de una función y su anotación de retorno. Por cada parámetro aceptado por la función, almacena un objeto Parameter en su colección parameters.

El argumento opcional parámetros es una secuencia de objetos Parameter, que se valida para comprobar que no hay parámetros con nombres duplicados, y que los parámetros están en el orden correcto, es decir, primero sólo de posición, luego de posición o palabra clave, y que los parámetros con valores por defecto siguen a los parámetros sin valores por defecto.

El argumento opcional return_annotation, puede ser un objeto Python arbitrario, es la anotación «return» del invocable.

Los objetos signature son inmutables. Usar Signature.replace() para hacer una copia modificada.

Distinto en la versión 3.5: Signature objects are picklable and hashable.

empty

Un marcador especial de clase para especificar la ausencia de una anotación de retorno.

parameters

Un mapeo ordenado de los nombres de los parámetros a los correspondientes objetos Parameter. Los parámetros aparecen en estricto orden de definición, incluyendo parámetros de sólo palabras clave.

Distinto en la versión 3.7: Python sólo garantizó explícitamente que conservaba el orden de declaración de los parámetros de sólo palabras clave a partir de la versión 3.7, aunque en la práctica este orden siempre se había conservado en Python 3.

return_annotation

La anotación de «retorno» para el invocable. Si el invocable no tiene ninguna anotación de «return», este atributo se establece en Signature.empty.

bind(*args, **kwargs)

Crear un mapeo de argumentos posicionales y de palabras clave a los parámetros. Retorna BoundArguments si *args y **kwargs coinciden con el signature, o lanza un TypeError.

bind_partial(*args, **kwargs)

Funciona de la misma manera que Signature.bind(), pero permite la omisión de algunos argumentos requeridos (imita el comportamiento de functools.partial().) Retorna BoundArguments, o lanza un TypeError si los argumentos pasados no coinciden con la firma.

replace(*[, parameters][, return_annotation])

Crear una nueva instancia Signature basada en la instancia sobre la que se invocó el reemplazo. Es posible pasar diferentes parámetros y/o return_annotation para sobreescribir las propiedades correspondientes de la firma base. Para eliminar return_annotation del Signature copiado, pasar en Signature.empty.

>>> def test(a, b):
...     pass
>>> sig = signature(test)
>>> new_sig = sig.replace(return_annotation="new return anno")
>>> str(new_sig)
"(a, b) -> 'new return anno'"

classmethod from_callable(obj, *, follow_wrapped=True, globalns=None, localns=None)

Retorna un objeto Signature (o su subclase) para un determinado obj invocable. Pasa follow_wrapped=False para obtener una signatura de obj sin desenvolver su cadena __wrapped__. globalns y localns serán usados como los espacios de nombre cuando se resuelvan las anotaciones.

Este método simplifica la subclasificación de Signature:

class MySignature(Signature):
    pass
sig = MySignature.from_callable(min)
assert isinstance(sig, MySignature)

Nuevo en la versión 3.5.

Nuevo en la versión 3.10: Parámetros globalns y localns.

class inspect.Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty)

Los objetos parámetros son inmutables. En lugar de modificar un objeto Parámetro, puedes usar Parameter.replace() para crear una copia modificada.

Distinto en la versión 3.5: Parameter objects are picklable and hashable.

empty

Un marcador especial de clase para especificar la ausencia de valores predeterminados y anotaciones.

name

El nombre del parámetro como una cadena. El nombre debe ser un identificador Python válido.

Detalles de implementación de CPython: CPython genera nombres de parámetros implícitos de la forma .0 en los objetos de código utilizados para implementar expresiones de comprensiones y generadores.

Distinto en la versión 3.6: Los nombres de estos parámetros son expuestos por este módulo como nombres como implicit0.

default

El valor por defecto del parámetro. Si el parámetro no tiene un valor por defecto, este atributo se establece en Parameter.empty.

annotation

La anotación para el parámetro. Si el parámetro no tiene ninguna anotación, este atributo se establece como Parameter.empty.

kind

Describes how argument values are bound to the parameter. The possible values are accessible via Parameter (like Parameter.KEYWORD_ONLY), and support comparison and ordering, in the following order:

Nombre	Significado
POSITIONAL_ONLY	El valor debe proporcionarse como un argumento posicional. Los parámetros solo posicionales son aquellos que aparecen antes de una entrada / (si está presente) en una definición de función de Python. aceptan sólo uno o dos parámetros) los aceptan.
POSITIONAL_OR_KEYWORD	El valor puede ser suministrado como una palabra clave o como un argumento posicional (este es el comportamiento estándar de unión para las funciones implementadas en Python)
VAR_POSITIONAL	Una tupla de argumentos posicionales que no están ligados a ningún otro parámetro. Esto corresponde a un parámetro *args en una definición de función Python.
KEYWORD_ONLY	El valor debe ser suministrado como argumento de la palabra clave. Los parámetros de sólo palabras clave son los que aparecen después de una entrada * o *args en una definición de función Python.
VAR_KEYWORD	Un dictado de argumentos de palabras clave que no están ligadas a ningún otro parámetro. Esto corresponde a un parámetro **kwargs en una definición de función Python.

Ejemplo: imprimir todos los argumentos de sólo palabras clave sin valores por defecto:

>>> def foo(a, b, *, c, d=10):
...     pass

>>> sig = signature(foo)
>>> for param in sig.parameters.values():
...     if (param.kind == param.KEYWORD_ONLY and
...                        param.default is param.empty):
...         print('Parameter:', param)
Parameter: c

kind.description

Describe un valor enum como Parameter.kind.

Nuevo en la versión 3.8.

Ejemplo: imprimir todas las descripciones de los argumentos:

>>> def foo(a, b, *, c, d=10):
...     pass

>>> sig = signature(foo)
>>> for param in sig.parameters.values():
...     print(param.kind.description)
positional or keyword
positional or keyword
keyword-only
keyword-only

replace(*[, name][, kind][, default][, annotation])

Crear una nueva instancia de parámetros basada en la instancia en la que se invocó la sustitución. Para anular un atributo Parameter, pasa el argumento correspondiente. Para eliminar un valor por defecto y/o una anotación de un parámetro, pasa Parameter.empty.

>>> from inspect import Parameter
>>> param = Parameter('foo', Parameter.KEYWORD_ONLY, default=42)
>>> str(param)
'foo=42'

>>> str(param.replace()) # Will create a shallow copy of 'param'
'foo=42'

>>> str(param.replace(default=Parameter.empty, annotation='spam'))
"foo:'spam'"

Distinto en la versión 3.4: En Python 3.3 se permitía que los objetos Parámetro tuvieran el name puesto en None si su kind estaba puesto en POSITIONAL_ONLY. Esto ya no está permitido.

class inspect.BoundArguments

Resultado de una llamada Signature.bind() o Signature.bind_partial(). Mantiene el mapeo de los argumentos a los parámetros de la función.

arguments

Un mapeo mutable de los nombres de los parámetros a los valores de los argumentos. Contiene solo argumentos vinculados explícitamente. Los cambios en arguments se reflejarán en args y kwargs.

Debe ser usado en conjunto con Signature.parameters para cualquier propósito de procesamiento de argumentos.

Nota

Los argumentos para los cuales Signature.bind() o Signature.bind_partial() se basaban en un valor por defecto se saltan. Sin embargo, si es necesario, use BoundArguments.apply_defaults() para añadirlos.

Distinto en la versión 3.9: arguments ahora es de tipo dict. Anteriormente, era de tipo collections.OrderedDict.

args

Una tupla de valores de argumentos posicionales. Calculados dinámicamente a partir del atributo arguments.

kwargs

Un diccionario de valores de argumentos de palabras clave. Calculados dinámicamente a partir del atributo arguments.

signature

Una referencia al objeto padre Signature.

apply_defaults()

Establece valores por defecto para los argumentos que faltan.

Para los argumentos de posición variable (*args) el valor por defecto es una tupla vacía.

Para los argumentos de palabras clave variables (**kwargs) el valor por defecto es un diccionario vacío.

>>> def foo(a, b='ham', *args): pass
>>> ba = inspect.signature(foo).bind('spam')
>>> ba.apply_defaults()
>>> ba.arguments
{'a': 'spam', 'b': 'ham', 'args': ()}

Nuevo en la versión 3.5.

Las propiedades args y kwargs pueden ser usadas para invocar funciones:

def test(a, *, b):
    ...

sig = signature(test)
ba = sig.bind(10, b=20)
test(*ba.args, **ba.kwargs)

Ver también

PEP 362 - Función Objeto Signature.

La especificación detallada, los detalles de implementación y los ejemplos.

Clases y funciones

inspect.getclasstree(classes, unique=False)

Organizar la lista de clases dada en una jerarquía de listas anidadas. Cuando aparece una lista anidada, contiene clases derivadas de la clase cuya entrada precede inmediatamente a la lista. Cada entrada es una tupla de 2 valores que contienen una clase y una tupla de sus clases base. Si el argumento unique es cierto, aparece exactamente una entrada en la estructura retornada para cada clase de la lista dada. De lo contrario, las clases que utilizan la herencia múltiple y sus descendientes aparecerán varias veces.

inspect.getargspec(func)

Obtener los nombres y valores por defecto de los parámetros de una función de Python. A named tuple ArgSpec(args, varargs, keywords, defaults) es retornado. args es una lista de los nombres de los parámetros. varargs y keywords son los nombres de los parámetros * y ** o None. defaults es una tupla de valores de los argumentos por defecto o None si no hay argumentos por defecto; si esta tupla tiene n elementos, corresponden a los últimos n elementos listados en args.

Obsoleto desde la versión 3.0: Use getfullargspec() para una API actualizada que suele ser un sustituto de la que no se necesita, pero que también maneja correctamente las anotaciones de la función y los parámetros de sólo palabras clave.

Alternativamente, use signature() y Objeto Signature, que proporcionan una API de introspección más estructurada para los invocables.

inspect.getfullargspec(func)

Obtener los nombres y valores por defecto de los parámetros de una función de Python. Se retorna un named tuple:

FullArgSpec(args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations)

args es una lista de los nombres de los parámetros posicionales. varargs es el nombre del parámetro * o None si no se aceptan argumentos posicionales arbitrarios. varkw es el nombre del parámetro ** o None si no se aceptan argumentos de palabras clave arbitrarias. defaults es una n-tupla de valores de argumentos por defecto que corresponden a los últimos parámetros de posición n, o None si no hay tales valores por defecto definidos. kwonlyargs es una lista de nombres de parámetros de sólo palabras clave en orden de declaración. kwonlydefaults es un diccionario que asigna los nombres de los parámetros de kwonlyargs a los valores por defecto utilizados si no se suministra ningún argumento. annotations es un diccionario que asigna los nombres de los parámetros a las anotaciones. La tecla especial "return" se utiliza para informar de la anotación del valor de retorno de la función (si existe).

Observe que signature() y Objeto Signature proporcionan la API recomendada para la introspección invocable, y soportan comportamientos adicionales (como los argumentos de sólo posición) que a veces se encuentran en las API de los módulos de extensión. Esta función se conserva principalmente para su uso en el código que necesita mantener la compatibilidad con la API de módulos de inspect de Python 2.

Distinto en la versión 3.4: Esta función se basa ahora en signature(), pero sigue ignorando los atributos __wrapped__ e incluye el primer parámetro ya ligado en la salida del signature para los métodos ligados.

Distinto en la versión 3.6: Este método fue documentado anteriormente como obsoleto en favor de signature() en Python 3.5, pero esa decisión ha sido revocada para restaurar una interfaz estándar claramente soportada para el código de una sola fuente en Python 2/3 que se aleja de la API heredada getargspec().

Distinto en la versión 3.7: Python sólo garantizó explícitamente que conservaba el orden de declaración de los parámetros de sólo palabras clave a partir de la versión 3.7, aunque en la práctica este orden siempre se había conservado en Python 3.

inspect.getargvalues(frame)

Obtener información sobre los argumentos pasados en un marco particular. Un named tuple ArgInfo(args, varargs, keywords, locals) es retornado. args es una lista de los nombres de los argumentos. varargs y keywords son los nombres de los argumentos *` y ``** o None. locals es el diccionario local del marco dado.

Nota

Esta función fue inadvertidamente marcada como obsoleta en Python 3.5.

inspect.formatargspec(args[, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations[, formatarg, formatvarargs, formatvarkw, formatvalue, formatreturns, formatannotations]])

Formatea un bonito argumento de los valores retornados por getfullargspec().

Los primeros siete argumentos son (args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations).

Los otros seis argumentos son funciones que se llaman para convertir los nombres de los argumentos, el nombre del argumento *, el nombre del argumento **, los valores por defecto, la anotación de retorno y las anotaciones individuales en cadenas, respectivamente.

Por ejemplo:

>>> from inspect import formatargspec, getfullargspec
>>> def f(a: int, b: float):
...     pass
...
>>> formatargspec(*getfullargspec(f))
'(a: int, b: float)'

Obsoleto desde la versión 3.5: Usar signature() y Objeto Signature, que proporcionan un mejor API de introspección para los invocables.

inspect.formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue])

Formatea una bonita especificación de argumentos de los cuatro valores retornados por getargvalues(). Los argumentos de formato* son las correspondientes funciones de formato opcionales que se llaman para convertir nombres y valores en cadenas.

Nota

Esta función fue inadvertidamente marcada como obsoleta en Python 3.5.

inspect.getmro(cls)

Retorna una tupla de clases base de cls, incluyendo cls, en orden de resolución de métodos. Ninguna clase aparece más de una vez en esta tupla. Obsérvese que el orden de resolución de los métodos depende del tipo de cls. A menos que se utilice un meta tipo muy peculiar definido por el usuario, cls será el primer elemento de la tupla.

inspect.getcallargs(func, /, *args, **kwds)

Ata los args y kwds a los nombres de los argumentos de la función o método func de Python, como si se llamara con ellos. Para los métodos ligados, liga también el primer argumento (típicamente llamado self) a la instancia asociada. Se retorna un diccionario, mapeando los nombres de los argumentos (incluyendo los nombres de los argumentos * y **, si los hay) a sus valores de args y kwds. En caso de invocar func incorrectamente, es decir, siempre que func(*args, **kwds) plantee una excepción por firma incompatible, se plantea una excepción del mismo tipo y del mismo o similar mensaje. Por ejemplo:

>>> from inspect import getcallargs
>>> def f(a, b=1, *pos, **named):
...     pass
>>> getcallargs(f, 1, 2, 3) == {'a': 1, 'named': {}, 'b': 2, 'pos': (3,)}
True
>>> getcallargs(f, a=2, x=4) == {'a': 2, 'named': {'x': 4}, 'b': 1, 'pos': ()}
True
>>> getcallargs(f)
Traceback (most recent call last):
...
TypeError: f() missing 1 required positional argument: 'a'

Nuevo en la versión 3.2.

Obsoleto desde la versión 3.5: Usa Signature.bind() y Signature.bind_partial() en su lugar.

inspect.getclosurevars(func)

Obtener el mapeo de referencias de nombres externos en una función o método func de Python a sus valores actuales. Un named tuple ClosureVars(nonlocals, globals, builtins, unbound) es retornado. nonlocals asigna los nombres referidos a las variables de cierre léxicas, globals a los globals de los módulos de la función y builtins a los builtins visibles desde el cuerpo de la función. unbound es el conjunto de nombres referenciados en la función que no pudieron ser resueltos en absoluto dados los actuales globals y builtins del módulo.

TypeError es lanzado si func no es una función o método de Python.

Nuevo en la versión 3.3.

inspect.unwrap(func, *, stop=None)

Obtiene el objeto envuelto por func. Sigue la cadena de atributos __wrapped__ retornando el último objeto de la cadena.

stop es una retrollamada opcional que acepta un objeto de la cadena envuelta como único argumento que permite terminar el desenvolvimiento antes de tiempo si la retrollamada retorna un valor real. Si la retrollamada nunca retorna un valor verdadero, el último objeto de la cadena se retorna como de costumbre. Por ejemplo, signature() utiliza esto para detener el desenvolvimiento si algún objeto de la cadena tiene definido el atributo __signature__.

ValueError es lanzado si se encuentra un ciclo.

Nuevo en la versión 3.4.

inspect.get_annotations(obj, *, globals=None, locals=None, eval_str=False)

Calcular el diccionario de anotaciones de un objeto.

obj puede ser un invocable, clase o módulo. Al pasar un objeto de cualquier otro tipo, se genera TypeError.

Retorna un diccionario. get_annotations() retorna un nuevo diccionario cada vez que se invoca; llamarlo dos veces en el mismo objeto retornara dos diccionarios diferentes pero equivalentes.

Esta función maneja varios detalles por usted:

• Si eval_str es verdadero, los valores del tipo str dejarán de ser cadenas usando eval(). La intención de este diseño es su uso con anotaciones convertidas a cadenas (from __future__ import annotations).

• Si obj no tiene un diccionario de anotaciones, retorna un diccionario vacío. (Las funciones y los métodos siempre tienen un diccionario de anotaciones; las clases, los módulos y otros tipos de intocables pueden no tenerlo).

• Ignora las anotaciones heredadas en las clases. Si una clase no tiene su propio diccionario de anotaciones, retorna un diccionario vacío.

• Todos los accesos a los miembros del objeto y a los valores del diccionario se realizan mediante getattr() y dict.get() para mayor seguridad.

• Always, always, always returns a freshly created dict.

eval_str controla si los valores del tipo str se sustituyen o no por el resultado de llamar a eval() sobre esos valores:

• Si eval_str es verdadero, eval() se llama a valores de tipo str. (Tenga en cuenta que get_annotations no detecta excepciones; si eval() genera una excepción, desenrollará la pila más allá de la llamada get_annotations).

• Si eval_str es false (el valor predeterminado), los valores del tipo str no cambian.

globals and locals se pasan a eval(); consulte la documentación de eval() para obtener más información. Si globals` o ``locals es None, esta función puede reemplazar ese valor con un valor predeterminado específico del contexto, supeditado a type(obj):

• Si obj es un módulo, globals por defecto es obj.__dict__.

• Si obj es una clase, globals tiene como valor predeterminado sys.modules[obj.__module__].__dict__ y locals es de forma predeterminada el espacio de nombres de clase obj .

• Si obj es un callable, globals por defecto es obj.__globals__, aunque si obj es una función envuelta (usando functools.update_wrapper()) primero se desenvuelve.

Llamar a get_annotations es una práctica recomendada para acceder al diccionario de anotaciones de cualquier objeto. Consulte Prácticas recomendadas para las anotaciones para obtener más información sobre las prácticas recomendadas de anotaciones.

Nuevo en la versión 3.10.

La pila del interprete

Cuando las siguientes funciones retornan «registros de cuadro», cada registro es un named tuple FrameInfo(frame, filename, lineno, function, code_context, index). La tupla contiene el objeto marco, el nombre de archivo, el número de línea de la línea actual, el nombre de la función, una lista de líneas de contexto del código fuente, y el índice de la línea actual dentro de esa lista.

Distinto en la versión 3.5: Retorna una tupla con nombre en lugar de una tupla.

Nota

Mantener referencias a los objetos marco, como se encuentra en el primer elemento de los registros marco que estas funciones retornan, puede hacer que su programa cree ciclos de referencia. Una vez creado un ciclo de referencia, la vida útil de todos los objetos a los que se puede acceder desde los objetos que forman el ciclo puede ser mucho mayor, incluso si el detector de ciclos opcional de Python está activado. Si es necesario crear tales ciclos, es importante asegurarse de que se rompen explícitamente para evitar la destrucción retardada de los objetos y el aumento del consumo de memoria que se produce.

Aunque el detector de ciclos los captará, la destrucción de los marcos (y las variables locales) puede hacerse determinísticamente eliminando el ciclo en una cláusula de finally. Esto también es importante si el detector de ciclos fue desactivado cuando se compiló Python o usando gc.disable(). Por ejemplo:

def handle_stackframe_without_leak():
    frame = inspect.currentframe()
    try:
        # do something with the frame
    finally:
        del frame

Si quieres mantener el marco alrededor (por ejemplo para imprimir una traceback más tarde), también puedes romper los ciclos de referencia utilizando el método frame.clear().

El argumento opcional de context, apoyado por la mayoría de estas funciones, especifica el número de líneas de contexto a retornar, que se centran en la línea actual.

inspect.getframeinfo(frame, context=1)

Obtener información sobre un marco o un objeto de traceback. Un named tuple Traceback(filename, lineno, function, code_context, index) es retornado.

inspect.getouterframes(frame, context=1)

Obtener una lista de registros marco para un marco y de todos los marcos exteriores. Estos marcos representan las llamadas que conducen a la creación de frame. La primera entrada de la lista retornada representa frame; la última entrada representa la llamada más exterior en la pila de frame.

Distinto en la versión 3.5: Una lista de named tuples FrameInfo(frame, filename, lineno, function, code_context, index) es retornada.

inspect.getinnerframes(traceback, context=1)

Consigue una lista de registros de marcos para un marco de traceback y todos los marcos internos. Estos marcos representan llamadas hechas como consecuencia de frame. La primera entrada de la lista representa traceback; la última entrada representa donde se lanzó la excepción.

Distinto en la versión 3.5: Una lista de named tuples FrameInfo(frame, filename, lineno, function, code_context, index) es retornada.

inspect.currentframe()

Retorna el objeto marco para el marco de la pila del que llama.

Detalles de implementación de CPython: Esta función se basa en el soporte del marco de la pila de Python en el intérprete, que no está garantizado que exista en todas las implementaciones de Python. Si se ejecuta en una implementación sin soporte de marcos de pila de Python, esta función retorna None.

inspect.stack(context=1)

Retorna una lista de registros de marco para la pila del que llama. La primera entrada de la lista retornada representa al que llama; la última entrada representa la llamada más exterior de la pila.

Distinto en la versión 3.5: Una lista de named tuples FrameInfo(frame, filename, lineno, function, code_context, index) es retornada.

inspect.trace(context=1)

Retorna una lista de registros de marco para la pila entre el marco actual y el marco en la que se lanzó una excepción que se está manejando actualmente. La primera entrada de la lista representa al que llama; la última entrada representa el lugar donde se lanzó la excepción.

Distinto en la versión 3.5: Una lista de named tuples FrameInfo(frame, filename, lineno, function, code_context, index) es retornada.

Obteniendo atributos estáticamente

Tanto getattr() como hasattr() pueden desencadenar la ejecución del código al buscar o comprobar la existencia de atributos. Los descriptores, como las propiedades, serán invocados y se podrá llamar a __getattr__() y __getattribute__().

Para los casos en los que se quiera una introspección pasiva, como las herramientas de documentación, esto puede ser un inconveniente. getattr_static() tiene la misma firma que getattr() pero evita la ejecución de código cuando obtiene atributos.

inspect.getattr_static(obj, attr, default=None)

Recuperar los atributos sin activar la búsqueda dinámica a través del protocolo descriptor, __getattr__() o __getattribute__().

Nota: es posible que esta función no pueda recuperar todos los atributos que getattr puede recuperar (como los atributos creados dinámicamente) y puede encontrar atributos que getattr no puede (como los descriptores que lanzan AttributeError). También puede retornar objetos descriptores en lugar de miembros de la instancia.

Si la instancia __dict__ es ensombrecida por otro miembro (por ejemplo una propiedad) entonces esta función no podrá encontrar miembros de la instancia.

Nuevo en la versión 3.2.

getattr_static() no resuelve los descriptores, por ejemplo los descriptores de ranura o los descriptores de getset en los objetos implementados en C. El objeto descriptor se retorna en lugar del atributo subyacente.

Puedes manejar esto con un código como el siguiente. Tenga en cuenta que la invocación de los descriptores de getset arbitrarios pueden desencadenar la ejecución del código:

# example code for resolving the builtin descriptor types
class _foo:
    __slots__ = ['foo']

slot_descriptor = type(_foo.foo)
getset_descriptor = type(type(open(__file__)).name)
wrapper_descriptor = type(str.__dict__['__add__'])
descriptor_types = (slot_descriptor, getset_descriptor, wrapper_descriptor)

result = getattr_static(some_object, 'foo')
if type(result) in descriptor_types:
    try:
        result = result.__get__()
    except AttributeError:
        # descriptors can raise AttributeError to
        # indicate there is no underlying value
        # in which case the descriptor itself will
        # have to do
        pass

Estado actual de los Generadores y las Corutinas

Al implementar los programadores de corutinas y para otros usos avanzados de los generadores, es útil determinar si un generador se está ejecutando actualmente, si está esperando para iniciarse o reanudarse o si ya ha terminado. getgeneratorstate() permite determinar fácilmente el estado actual de un generador.

inspect.getgeneratorstate(generator)

Obtener el estado actual de un generador-iterador.

Los posibles estados son:

• GEN_CREATED: Esperando para iniciar la ejecución.

• GEN_RUNNING: Actualmente está siendo ejecutado por el intérprete.

• GEN_SUSPENDED: Actualmente suspendido en una expresión yield.

• GEN_CLOSED: La ejecución se ha completado.

Nuevo en la versión 3.2.

inspect.getcoroutinestate(coroutine)

Obtener el estado actual de un objeto de corutina. La función está pensada para ser usada con objetos de corutina creados por las funciones async def, pero aceptará cualquier objeto de corutina que tenga los atributos cr_running y cr_frame.

Los posibles estados son:

• CORO_CREATED: Esperando para iniciar la ejecución.

• CORO_RUNNING: Actualmente está siendo ejecutado por el intérprete.

• CORO_SUSPENDED: Actualmente suspendido en una expresión de espera.

• CORO_CLOSED: La ejecución se ha completado.

Nuevo en la versión 3.5.

También se puede consultar el estado interno actual del generador. Esto es mayormente útil para fines de prueba, para asegurar que el estado interno se actualiza como se espera:

inspect.getgeneratorlocals(generator)

Consigue el mapeo de las variables vivas locales en generator a sus valores actuales. Se retorna un diccionario que mapea de los nombres de las variables a los valores. Esto es el equivalente a llamar locals() en el cuerpo del generador, y se aplican todas las mismas advertencias.

Si generator es un generator sin marco asociado actualmente, entonces se retorna un diccionario vacío. TypeError es lanzado si generator no es un objeto generador de Python.

Detalles de implementación de CPython: Esta función se basa en que el generador exponga un marco de pila de Python para la introspección, lo cual no está garantizado en todas las implementaciones de Python. En tales casos, esta función siempre retornará un diccionario vacío.

Nuevo en la versión 3.3.

inspect.getcoroutinelocals(coroutine)

Esta función es análoga a getgeneratorlocals(), pero funciona para los objetos de corutina creados por funciones async def.

Nuevo en la versión 3.5.

Objetos de código Bit Flags

Los objetos de código Python tienen un atributo co_flags, que es un mapa de bits de los siguientes flags:

inspect.CO_OPTIMIZED

El objeto del código está optimizado, usando locales rápidas (fast locals).

inspect.CO_NEWLOCALS

Si se establece, se creará un nuevo diccionario para el marco f_locals cuando se ejecute el objeto código.

inspect.CO_VARARGS

El objeto del código tiene un parámetro posicional variable (similar a *args).

inspect.CO_VARKEYWORDS

El objeto del código tiene un parámetro de palabra clave variable (similar a **kwargs).

inspect.CO_NESTED

El flag se fija cuando el objeto del código es una función anidada.

inspect.CO_GENERATOR

El flag se fija cuando el objeto del código es una función generadora, es decir, un objeto generador es retornado cuando el objeto del código se ejecuta.

inspect.CO_NOFREE

El flag se configura si no hay variables libres o de celda.

inspect.CO_COROUTINE

El flag se configura cuando el objeto del código es una función de corutina. Cuando el objeto código se ejecuta, retorna un objeto de corutina. Ver PEP 492 para más detalles.

Nuevo en la versión 3.5.

inspect.CO_ITERABLE_COROUTINE

El flag se utiliza para transformar generadores en corutinas basadas en generadores. Los objetos generadores con este flag pueden ser usados en la expresión await, y objetos de corutina yield from. Ver PEP 492 para más detalles.

Nuevo en la versión 3.5.

inspect.CO_ASYNC_GENERATOR

El flag se configura cuando el objeto del código es una función generadora asíncrona. Cuando el objeto código se ejecuta, retorna un objeto generador asíncrono. Ver PEP 525 para más detalles.

Nuevo en la versión 3.6.

Nota

Los flags son específicos de CPython, y no pueden ser definidas en otras implementaciones de Python. Además, los flags son un detalle de la implementación, y pueden ser eliminados o desaprobados en futuras versiones de Python. Se recomienda utilizar las APIs públicas del módulo inspect para cualquier necesidad de introspección.

Interfaz de la línea de comando

El módulo inspect también proporciona una capacidad básica de introspección desde la línea de comandos.

Por defecto, acepta el nombre de un módulo e imprime la fuente de ese módulo. Una clase o función dentro del módulo puede imprimirse en su lugar añadiendo dos puntos y el nombre calificado del objeto objetivo.

--details

Imprimir información sobre el objeto especificado en lugar del código fuente