Geschiedenis.
Voor Python 3.6 vertrouwden descriptors die kennis nodig hadden van hun attribuutnaam op aangepaste metaclasses of handmatige class-decorators om de class-woordenlijst te scannen en namen in te voegen. Deze aanpak was omslachtig, foutgevoelig en creëerde metaclassconflicten in complexe hiëlarchieën. PEP 487 introduceerde het __set_name__-protocol in Python 3.6 om deze boilerplate te elimineren door de interpreter toe te staan descriptors automatisch te notificeren.
Probleem.
Een descriptorinstantie wordt gemaakt tijdens de uitvoering van de class-body, maar op dat moment heeft deze geen intrinsieke kennis van de variabelenaam waaraan deze is gebonden of de klasse waarin deze zich bevindt. Deze informatie is essentieel voor het genereren van zinvolle foutmeldingen, het registreren van velden in ORM-systemen of het bouwen van serialisatieschema's. Zonder externe notificatie blijft de descriptor anoniem, waardoor ontwikkelaars de attribuutnaam als een stringargument moeten herhalen, wat in strijd is met de DRY-principes.
Oplossing.
Wanneer type.__new__ een klasse construeert, iterereert het over de naamruimte-mapping die wordt geretourneerd door __prepare__. Voor elke waarde die een __set_name__-methode bezit, roept de interpreter value.__set_name__(owner_class, attribute_name) aan. Deze methode ontvangt de aan het bouwen zijnde klasse en de attribuutstring, waardoor de descriptor deze metadata kan opslaan. Echter, als een descriptor aan een klasse-attribuut wordt toegewezen nadat het creatieproces van de klasse is voltooid (monkey-patching), wordt __set_name__ niet automatisch aangeroepen omdat de type-machinerie niet meer actief is.
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
Context.
Tijdens de ontwikkeling van een configuratiebeheerlibrary hadden we descriptors nodig om omgevingsvariabelen weer te geven. Wanneer een waarde ontbrak of ongeldig was, moest de fout de exacte attribuutnaam in de klasse specificeren (bijv. Config.database_url is required), niet alleen een generieke boodschap.
Probleem.
In het begin moesten gebruikers de naam handmatig specificeren: database_url = EnvVar('database_url'). Dit leidde tot bugs tijdens het refactoren waarbij de string-literal en de variabelenaam uiteenliepen, wat leidde tot cryptische runtime-fouten.
Verschillende oplossingen overwogen:
Metaclass-injectie. We implementeerden een ConfigMeta die attrs inspecteerde en attr.set_name(name) aanriep op elke descriptor. Dit werkte, maar dwong alle gebruikersklassen om van onze metaclass te erven, waardoor de compatibiliteit met andere bibliotheken die hun eigen metaclasses gebruikten, zoals abc.ABCMeta, werd verbroken. Het voegde ook cognitieve overhead toe voor gebruikers die niet vertrouwd waren met metaclasses.
Class decorator patching. We creëerden een @config-decorator die na de class-creatie over cls.__dict__ iterereerde en namen patchte. Dit voorkwam metaclassconflicten, maar was opt-in; het vergeten van de decorator resulteerde in gebroken descriptors. Het werd ook uitgevoerd na de class-creatie, zodat descriptors hun namen niet konden gebruiken tijdens de __init_subclass__-hooks, wat de introspectiemogelijkheden beperkte.
__set_name__-protocol. We voegden __set_name__ toe aan onze EnvVar-descriptor. Dit vereiste geen wijzigingen in de gebruikerscode, werkte automatisch tijdens de class-definitie en stelde de descriptor in staat om zijn naam te kennen voordat __init_subclass__ was voltooid, waardoor vroege validatie mogelijk was.
Gekozen oplossing.
We namen __set_name__ over omdat het een kosteloze abstractie voor gebruikers bood en integreerde met Python's native datamodel. Het elimineerde het probleem met metaclassbotsingen volledig.
Resultaat.
De API werd declaratief: database_url = EnvVar(). Refactoringshulpmiddelen konden attributen veilig hernoemen, en foutmeldingen bleven nauwkeurig. De codebase kromp met 150 regels metaclass-boilerplate, en we observeerden minder bugmeldingen met betrekking tot configuratiesleutelmismatches.
Wanneer precies wordt __set_name__ aangeroepen tijdens de levenscyclus van class-creatie?
Het wordt aangeroepen door type.__new__ onmiddellijk nadat het class-body is uitgevoerd en de naamruimtewoordenlijst is gevuld, maar voordat __init_subclass__ wordt aangeroepen op ouderklassen. Deze timing is kritiek omdat het descriptors in staat stelt hun toestand te finaliseren voordat subklassen worden geïnitialiseerd. Het wordt niet geactiveerd wanneer attributen aan een reeds gemaakte klasse worden toegevoegd (bijv. setattr(MyClass, 'new_attr', descriptor())), omdat het class-creatieprotocol is voltooid. Het begrijpen van dit onderscheid is van vitaal belang voor dynamische class-manipulatie.
Waarom ontvangt __set_name__ zowel de eigenaarklasse als de naam als argumenten in plaats van deze af te leiden van self?
De descriptorinstantie bestaat onafhankelijk van de klasse; deze kan worden geïnstantieerd voordat de class-creatie plaatsvindt en theoretisch aan meerdere klassen worden toegewezen (hoewel dit zeldzaam is). Het owner-argument zorgt ervoor dat de descriptor de specifieke klasse kent waar de toewijzing plaatsvond, wat nodig is voor een correcte afhandeling van erfelijkheid. Als een descriptor in een basis klasse is gedefinieerd, wordt __set_name__ aangeroepen met de basis klasse; als het in een subklasse wordt overschreven met een nieuwe instantie, wordt het aangeroepen met de subklasse. Dit maakt per-klasse registraties mogelijk zonder kruisbesmetting tussen basis- en afgeleide klassen.
Hoe werkt __set_name__ samen met de __set__ en __get__ descriptor protocolmethoden?
__set_name__ is puur een initialisatiehook en neemt niet deel aan het attribuuttoegangprotocol (__get__/__set__). Het stelt echter die methoden in staat om correct te functioneren door de context te bieden die nodig is voor operaties. Een veelgemaakte fout is aan te nemen dat __set_name__ opnieuw zal worden aangeroepen wanneer een descriptor wordt geërfd door een subklasse die deze niet overschrijft. Aangezien dezelfde descriptorinstantie wordt hergebruikt, wordt __set_name__ niet opnieuw aangeroepen; daarom moeten descriptors die per-klasse status bijhouden gebruik maken van __init_subclass__ of owner in __get__ controleren om te zorgen voor erfelijkheid, in plaats van uitsluitend op __set_name__ te vertrouwen voor subklasse-specifieke logica.