¿A través de qué método del protocolo los descriptores de **Python** reciben automáticamente su nombre de atributo asignado y la clase contenedora durante la creación de clases, y qué limitación surge cuando los descriptores se asocian a clases después de la declaración?

Respuesta a la pregunta.

Historia.

Antes de Python 3.6, los descriptores que requerían conocimiento de su nombre de atributo dependían de metaclases personalizadas o decoradores de clases manuales para escanear el diccionario de la clase e inyectar nombres. Este enfoque era verboso, propenso a errores y creaba conflictos de metaclases en jerarquías complejas. PEP 487 introdujo el protocolo __set_name__ en Python 3.6 para eliminar este código repetitivo al permitir que el intérprete notifique automáticamente a los descriptores.

Problema.

Una instancia de descriptor se crea durante la ejecución del cuerpo de la clase, pero en ese momento no tiene conocimiento intrínseco del nombre de la variable a la que está vinculada o de la clase en la que reside. Esta información es esencial para generar mensajes de error significativos, registrar campos en sistemas ORM o construir esquemas de serialización. Sin una notificación externa, el descriptor permanece anónimo, obligando a los desarrolladores a repetir el nombre del atributo como un argumento de cadena, violando principios DRY.

Solución.

Cuando type.__new__ construye una clase, itera sobre el mapeo de espacio de nombres devuelto por __prepare__. Para cada valor que posee un método __set_name__, el intérprete invoca value.__set_name__(owner_class, attribute_name). Este método recibe la clase que se está construyendo y la cadena del atributo, permitiendo al descriptor almacenar esta metadata. Sin embargo, si un descriptor se asigna a un atributo de clase después de que se completa el proceso de creación de la clase (monkey-patching), __set_name__ no se invoca automáticamente porque la maquinaria de tipo ya no está activa.

class TrackedDescriptor:
    def __set_name__(self, owner, name):
        self.owner = owner
        self.name = name
    
    def __get__(self, instance, owner):
        if instance is None:
            return self
        return f"{self.owner.__name__}.{self.name}"

class Model:
    field = TrackedDescriptor()

# Model.field.name == 'field'
# Model.field.owner == Model

Situación de la vida real

Contexto.

Mientras desarrollábamos una biblioteca de gestión de configuración, necesitábamos descriptores para representar variables de entorno. Cuando un valor estaba ausente o era inválido, el error tenía que especificar el nombre exacto del atributo en la clase (por ejemplo, Config.database_url is required), no solo un mensaje genérico.

Problema.

Inicialmente, los usuarios tenían que especificar el nombre manualmente: database_url = EnvVar('database_url'). Esto llevó a errores durante la refactorización donde la cadena literal y el nombre de la variable divergían, causando errores crípticos en tiempo de ejecución.

Diferentes soluciones consideradas:

Inyección de metaclases. Implementamos un ConfigMeta que inspeccionaba attrs y llamaba a attr.set_name(name) en cada descriptor. Esto funcionó pero obligó a todas las clases de usuario a heredar de nuestra metaclase, rompiendo la compatibilidad con otras bibliotecas que usaban sus propias metaclases como abc.ABCMeta. También añadió carga cognitiva para los usuarios no familiarizados con metaclases.

Patching de decoradores de clase. Creamos un decorador @config que iteraba sobre cls.__dict__ después de la creación de la clase y parcheaba nombres. Esto evitó conflictos de metaclases pero era opcional; olvidar el decorador resultó en descriptores rotos. También se ejecutó después de la creación de la clase, por lo que los descriptores no podían usar sus nombres durante los hooks de __init_subclass__, limitando las capacidades de introspección.

Protocolo __set_name__. Agregamos __set_name__ a nuestro descriptor EnvVar. Esto no requería cambios en el código del usuario, funcionaba automáticamente durante la definición de la clase y permitía al descriptor conocer su nombre antes de que __init_subclass__ se completara, permitiendo la validación temprana.

Solución elegida.

Adoptamos __set_name__ porque proporcionó una abstracción sin costo para los usuarios e integró con el modelo de datos nativo de Python. Eliminó completamente el problema de la colisión de metaclases.

Resultado.

La API se volvió declarativa: database_url = EnvVar(). Las herramientas de refactorización podían cambiar el nombre de los atributos de forma segura y los mensajes de error permanecieron precisos. La base de código se redujo en 150 líneas de código repetitivo de metaclases, y observamos menos informes de errores relacionados con desajustes en las claves de configuración.

Lo que a menudo pasan por alto los candidatos

¿Cuándo se invoca exactamente __set_name__ durante el ciclo de vida de creación de la clase?

Se invoca por type.__new__ inmediatamente después de que el cuerpo de la clase termina de ejecutarse y se completa el diccionario de espacio de nombres, pero antes de que se llame a __init_subclass__ en las clases base. Este tiempo es crítico porque permite a los descriptores finalizar su estado antes de que se inicialicen las subclases. No se activa al agregar atributos a una clase ya creada (por ejemplo, setattr(MyClass, 'new_attr', descriptor())), porque el protocolo de creación de la clase ha concluido. Entender esta distinción es vital para la manipulación dinámica de clases.

¿Por qué __set_name__ recibe tanto la clase propietaria como el nombre como argumentos en lugar de inferirlos de self?

La instancia del descriptor existe independientemente de la clase; puede ser instanciada antes de la creación de la clase y teóricamente podría ser asignada a múltiples clases (aunque es raro). El argumento owner asegura que el descriptor conozca la clase específica donde ocurrió la asignación, lo cual es necesario para manejar la herencia correctamente. Si un descriptor se define en una clase base, __set_name__ se llama con la clase base; si se sobrescribe en una subclase con una nueva instancia, se llama con la subclase. Esto permite registros por clase sin contaminación cruzada entre clases base y derivadas.

¿Cómo interactúa __set_name__ con los métodos del protocolo de descriptores __set__ y __get__?

__set_name__ es puramente un gancho de inicialización y no participa en el protocolo de acceso a atributos (__get__/__set__). Sin embargo, permite que esos métodos funcionen correctamente al proporcionar el contexto necesario para las operaciones. Un error común es asumir que __set_name__ se llamará nuevamente cuando un descriptor sea heredado por una subclase que no lo sobrescriba. Dado que la misma instancia de descriptor se reutiliza, __set_name__ no se invoca nuevamente; por lo tanto, los descriptores que rastrean el estado por clase deben usar __init_subclass__ o comprobar owner en __get__ para manejar la herencia, en lugar de depender únicamente de __set_name__ para la lógica específica de subclases.