Historia.
Przed Python 3.6, deskriptorzy wymagający wiedzy o swojej nazwie atrybutu polegali na niestandardowych metaklasach lub ręcznych dekoratorach klas do skanowania słownika klas i wstrzykiwania nazw. To podejście było przesadne, podatne na błędy i tworzyło konflikty metaklas w złożonych hierarchiach. PEP 487 wprowadził protokół __set_name__ w Python 3.6, aby wyeliminować ten schemat, pozwalając interpreterowi automatycznie powiadamiać deskriptorów.
Problem.
Instancja deskriptoru jest tworzona w trakcie wykonania ciała klasy, ale w tym momencie nie ma wewnętrznej wiedzy na temat nazwy zmiennej, do której jest przypisana, ani klasy, w której się znajduje. Informacja ta jest niezbędna do generowania sensownych komunikatów o błędach, rejestrowania pól w systemach ORM lub budowania schematów serializacji. Bez zewnętrznego powiadomienia, deskriptor pozostaje anonimowy, zmuszając programistów do powtarzania nazwy atrybutu jako argumentu typu string, co narusza zasady DRY.
Rozwiązanie.
Gdy type.__new__ konstruuje klasę, iteruje przez mapowanie przestrzeni nazw zwrócone przez __prepare__. Dla każdej wartości posiadającej metodę __set_name__, interpreter wywołuje value.__set_name__(owner_class, attribute_name). Ta metoda otrzymuje klasę będącą w trakcie konstrukcji i łańcuch atrybutu, co pozwala deskriptorowi przechować te metadane. Jednakże, jeśli deskriptor jest przypisany do atrybutu klasy po zakończeniu procesu tworzenia klasy (monkey-patching), __set_name__ nie jest automatycznie wywoływane, ponieważ mechanizm typu nie jest już aktywny.
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
Kontekst.
Podczas tworzenia biblioteki zarządzania konfiguracją potrzebowaliśmy deskriptorów do reprezentacji zmiennych środowiskowych. Gdy wartość była brakująca lub nieprawidłowa, komunikat o błędzie musiał precyzyjnie wskazywać na dokładną nazwę atrybutu w klasie (np. Config.database_url jest wymagane), nie tylko ogólna wiadomość.
Problem.
Początkowo użytkownicy musieli określać nazwę ręcznie: database_url = EnvVar('database_url'). To prowadziło do błędów podczas refaktoryzacji, w których literał łańcuchowy i nazwa zmiennej rozchodziły się, co powodowało niezrozumiałe błędy w czasie wykonywania.
Rozważane różne rozwiązania:
Iniekcja metaklasy. Zaimplementowaliśmy ConfigMeta, który skanował attrs i wywoływał attr.set_name(name) dla każdego deskriptoru. To zadziałało, ale zmusiło wszystkie klasy użytkowników do dziedziczenia po naszej metaklasie, łamiąc kompatybilność z innymi bibliotekami korzystającymi z własnych metaklas, takich jak abc.ABCMeta. Dodało to także umysłową przeszkodę dla użytkowników nieznających metaklas.
Patching dekoratorem klas. Stworzyliśmy dekorator @config, który iterował po cls.__dict__ po utworzeniu klasy i patchował nazwy. To unikało konfliktów metaklas, ale było dobrowolne; zapomnienie o dekoratorze skutkowało uszkodzonymi deskriptorami. Działało to również po utworzeniu klasy, więc deskriptorzy nie mogli korzystać z nazw podczas haków __init_subclass__, ograniczając możliwości introspekcji.
Protokół __set_name__. Dodaliśmy __set_name__ do naszego deskriptoru EnvVar. Nie wymagało to zmian w kodzie użytkownika, działało automatycznie podczas definicji klasy i pozwalało deskriptorowi znać swoją nazwę przed zakończeniem __init_subclass__, co umożliwiało wczesną walidację.
Wybrane rozwiązanie.
Przyjęliśmy __set_name__, ponieważ zapewniło to bezkosztową abstrakcję dla użytkowników i zintegrowało się z natywnym modelem danych Python. Całkowicie wyeliminowało problem kolizji metaklas.
Wynik.
API stało się deklaratywne: database_url = EnvVar(). Narzędzia do refaktoryzacji mogły bezpiecznie zmieniać nazwy atrybutów, a komunikaty o błędach pozostały dokładne. Kod źródłowy zmniejszył się o 150 linii szkieletu metaklas, a my zaobserwowaliśmy mniej zgłoszeń błędów związanych z niezgodnościami kluczy konfiguracyjnych.
Kiedy dokładnie __set_name__ jest wywoływane w cyklu życia tworzenia klasy?
Jest wywoływane przez type.__new__ bezpośrednio po zakończeniu wykonywania ciała klasy i wypełnieniu słownika przestrzeni nazw, ale przed wywołaniem __init_subclass__ w klasach nadrzędnych. Ten czas jest kluczowy, ponieważ pozwala deskriptorom sfinalizować swój stan przed inicjalizacją podklas. Nie jest wywoływane podczas dodawania atrybutów do już utworzonej klasy (np. setattr(MyClass, 'new_attr', descriptor())), ponieważ protokół tworzenia klasy zakończono. Zrozumienie tej różnicy jest kluczowe dla dynamicznej manipulacji klasami.
Dlaczego __set_name__ otrzymuje zarówno klasę właściciela, jak i nazwę jako argumenty, zamiast wywnioskować je z self?
Instancja deskriptoru istnieje niezależnie od klasy; może być zainstalowana przed stworzeniem klasy i teoretycznie mogłaby być przypisana do wielu klas (choć rzadko). Argument owner zapewnia, że deskriptor zna konkretną klasę, w której miało miejsce przypisanie, co jest niezbędne do prawidłowego obsługiwania dziedziczenia. Jeśli deskriptor jest zdefiniowany w klasie bazowej, __set_name__ jest wywoływane z klasą bazową; jeśli jest nadpisywane w podklasie z nową instancją, jest wywoływane z podklasy. To pozwala na rejestry na poziomie klasy bez wzajemnego zanieczyszczenia między klasą bazową a pochodnymi.
Jak __set_name__ współdziała z metodami protokołu deskriptorów __set__ i __get__?
__set_name__ jest czysto hakiem inicjalizacji i nie uczestniczy w protokole dostępu do atrybutów (__get__/__set__). Jednak umożliwia tym metodom prawidłowe działanie, dostarczając kontekst potrzebny do operacji. Powszechnym błędem jest zakładanie, że __set_name__ zostanie wywołane ponownie, gdy deskriptor jest dziedziczony przez podklasę, która go nie nadpisuje. Ponieważ ta sama instancja deskriptoru jest ponownie używana, __set_name__ nie jest wywoływane ponownie; dlatego deskriptorzy śledzący stan na poziomie klasy muszą używać __init_subclass__ lub sprawdzać owner w __get__, aby obsługiwać dziedziczenie, a nie polegać wyłącznie na __set_name__ dla logiki specyficznej dla podklasy.