Appearance
3.13.7 — Descriptors, Attribute Lookup & Metaclasses
An order line has a quantity and a unit price, and both must be positive. With @property from 3.13.6, that means writing a getter and a setter for each field: eight methods for two numbers, and the same eight again in every class that has a quantity. There has to be a way to write "this field must be positive" once and reuse it. There is, and it is the same mechanism that makes @property work, that turns functions into bound methods, and that lets Pydantic and SQLAlchemy read your class definitions. It is called the descriptor protocol. This page explains the exact steps Python runs for every obj.name, and then goes one level further, to the object that builds classes themselves: the metaclass.
1. What happens when you write obj.name
Every attribute access, line.quantity, cart.add, product.price, runs one method: type(obj).__getattribute__(obj, "name"). For ordinary objects, that is object.__getattribute__, written in C. Its algorithm is short, and once you know it, a whole family of Python features stops being magic.
First, two definitions. A descriptor is any object, stored as a class attribute, whose class defines __get__. When you look it up through an instance, Python does not hand you the descriptor itself. It calls the descriptor's __get__ and hands you whatever that returns.
- A data descriptor defines
__get__and__set__(or__delete__). - A non-data descriptor defines only
__get__.
Now the algorithm. For obj.name:
- Search the class and its parents, in MRO order, for
name. Call what you findclass_attr. - If
class_attris a data descriptor, callclass_attr.__get__(obj, type(obj))and return the result. - Otherwise, if
nameis in the instance's ownobj.__dict__, return that value. - Otherwise, if
class_attris a non-data descriptor, call its__get__and return the result. - Otherwise, if
class_attrwas found at all, return it as it is. - Otherwise, if the class defines
__getattr__, call it as a last resort. - Otherwise, raise
AttributeError.
Figure 1 draws the same steps as a ladder. Python stops at the first rung that answers.
Hold on to the order of rungs ①, ② and ③. A data descriptor wins over the instance's own dict. The instance's dict wins over a non-data descriptor. Every example on this page is explained by that one ordering.
Setting an attribute, obj.name = value, follows a shorter rule. If the class has a data descriptor for name, Python calls its __set__. Otherwise it writes the value into obj.__dict__.
2. Writing your own descriptor
Back to the opening problem. Here is "must be positive", written once as a descriptor, and used for two fields.
python
class PositiveNumber:
def __set_name__(self, owner, name): # (1)
print(f" __set_name__: {owner.__name__}.{name}")
self.storage_name = "_" + name
def __get__(self, instance, owner=None): # (2)
if instance is None:
return self
return getattr(instance, self.storage_name)
def __set__(self, instance, value): # (3)
if value <= 0:
raise ValueError(f"{self.storage_name[1:]} must be positive, got {value}")
setattr(instance, self.storage_name, value)
class OrderLine:
quantity = PositiveNumber() # (4)
unit_price = PositiveNumber()
def __init__(self, sku, quantity, unit_price):
self.sku = sku
self.quantity = quantity # (5)
self.unit_price = unit_price
line = OrderLine("mug", 2, 450)
print(line.quantity * line.unit_price, vars(line))
try:
line.quantity = 0
except ValueError as error:
print("ValueError:", error)text
__set_name__: OrderLine.quantity
__set_name__: OrderLine.unit_price
900 {'sku': 'mug', '_quantity': 2, '_unit_price': 450}
ValueError: quantity must be positive, got 0(1)__set_name__is called once, when the class is created, and tells the descriptor which class it lives in and which name it was given. It was added in Python 3.6. Before that, you had to repeat the name, as inquantity = PositiveNumber("quantity"). The descriptor stores the value under a private name,_quantity.(2)__get__runs on every read.instanceis the object you read through. When you read through the class itself, as inOrderLine.quantity,instanceisNone, and the convention is to return the descriptor itself.(3)__set__runs on every assignment and checks the value. Because this class defines__set__, it is a data descriptor, so it sits on rung ① and wins over the instance's dict.(4)One descriptor object per field, stored on the class. It is shared by everyOrderLine, which is why it keeps per-instance data on the instance, not on itself.(5)This assignment runsPositiveNumber.__set__, so even the constructor is validated.
The same check, written once, now guards any field in any class. This is exactly how Django model fields, SQLAlchemy columns and many validation libraries work.
3. Functions are descriptors: where bound methods come from
Here is the payoff. Ask a plain function whether it is a descriptor.
python
class Cart:
def total(self):
return 42
cart = Cart()
raw = Cart.__dict__["total"] # (1)
print(type(raw), hasattr(raw, "__get__"), hasattr(raw, "__set__")) # (2)
bound = raw.__get__(cart, Cart) # (3)
print(bound, bound())text
<class 'function'> True False
<bound method Cart.total of <__main__.Cart object at 0x00000255029E4AD0>> 42(1)Reading the class's__dict__directly skips the lookup algorithm and gives the raw stored object: a plain function.(2)Every function has__get__but no__set__. Every function is a non-data descriptor.(3)Calling its__get__with an instance returns a bound method. That is exactly whatcart.totaldoes, at rung ③.
So there is no special rule for methods in Python. A method is just a function stored on a class. Reading it through an instance triggers the function's __get__, which builds the bound method you met in 3.13.6. And because functions are non-data descriptors, an instance attribute with the same name sits on rung ② and hides the method.
python
cart.total = lambda: "instance wins"
print(cart.total())text
instance wins4. property, classmethod, staticmethod and cached_property are descriptors too
Each of the special decorators from 3.13.5 and 3.13.6 is a descriptor class. Their behaviour follows directly from which rung they sit on.
property is a data descriptor. It defines __set__ even when you give it no setter, in which case __set__ raises AttributeError. So it sits on rung ① and nothing in the instance can hide it.
python
class Product:
@property
def price(self):
return 450
product = Product()
product.__dict__["price"] = 999 # (1)
print(product.price, product.__dict__)text
450 {'price': 999}(1)We sneak a value straight into the instance dict. The property still wins, because data descriptors come before the instance dict. A read-only property is truly read-only.
cached_property is a non-data descriptor. It defines __get__ only. On the first read, the instance has no entry, so rung ③ calls __get__, which computes the value and stores it in the instance dict under the same name. On every later read, rung ② finds that stored value first, and the descriptor is never called again. Its whole caching trick is that ordering. This is why 3.13.5 said it stores the answer on the instance.
classmethod and staticmethod are non-data descriptors whose __get__ returns something different from a normal function's.
python
class Shop:
@classmethod
def create(cls):
return cls
@staticmethod
def helper():
return "h"
print(Shop.__dict__["create"]) # (1)
print(Shop.__dict__["create"].__get__(None, Shop)) # (2)
print(Shop.__dict__["helper"].__get__(None, Shop)) # (3)text
<classmethod(<function Shop.create at 0x0000025502B6F8A0>)>
<bound method Shop.create of <class '__main__.Shop'>>
<function Shop.helper at 0x0000025502B6F950>(1)The decorator wrapped the function in aclassmethodobject.(2)Its__get__binds the function to the class, whether you look it up through the class or an instance. That is whereclscomes from.(3)Astaticmethod's__get__returns the plain function, bound to nothing.
Here is the whole family at a glance.
| Object on the class | Kind | obj.name gives |
|---|---|---|
| plain function | non-data | method bound to obj |
classmethod | non-data | method bound to the class |
staticmethod | non-data | the plain function |
cached_property | non-data | computed once, then from __dict__ |
property | data | the getter's result |
__slots__ entry | data | value from the fixed slot |
The last row closes a loop from 3.13.6. Each name in __slots__ becomes a data descriptor on the class, which reads and writes a fixed position inside the object. That is how slots work without a __dict__.
5. __getattr__ and __getattribute__
Two hooks let a class take over attribute access itself. They have nearly the same name and very different power.
__getattr__is called only when normal lookup fails, at rung ⑤. It is safe and common.__getattribute__replaces the entire algorithm and runs on every access. It is powerful and easy to get wrong.
Here is a settings object that exposes dict keys as attributes, using the safe hook.
python
class Settings:
def __init__(self, values):
self._values = values # (1)
def __getattr__(self, name): # (2)
print(f" __getattr__({name!r})")
try:
return self._values[name]
except KeyError:
raise AttributeError(name) from None # (3)
settings = Settings({"db_url": "sqlite://", "debug": True})
print(settings.db_url, settings.debug)
print(settings._values is not None) # (4)text
__getattr__('db_url')
__getattr__('debug')
sqlite:// True
True(1)_valuesis a normal instance attribute.(2)db_urlis not found by rungs ① to ④, so Python calls__getattr__.(3)Missing keys must raiseAttributeError, notKeyError. Functions likehasattrandgetattr(obj, name, default)depend on that exact exception.(4)_valueswas found normally at rung ②, so__getattr__was not called for it. No print.
If you override __getattribute__ instead, every access, including self._values inside your own method, goes through your code. A careless self._values inside it calls itself forever. The correct pattern is to call object.__getattribute__(self, name) for the normal path. You will rarely need it. Proxies and debugging tools are the usual exceptions.
6. Classes are objects, and type builds them
Now the second half of the page. 3.13.6 said a class statement ends by calling type(name, bases, namespace). You can make that call yourself.
python
def describe(self):
return f"{self.sku} x{self.qty}"
OrderLine = type("OrderLine", (object,), {"currency": "INR", "describe": describe}) # (1)
line = OrderLine()
line.sku, line.qty = "mug", 2
print(line.describe(), line.currency, type(OrderLine))text
mug x2 INR <class 'type'>(1)Three arguments: the class name, a tuple of parent classes, and a dict that becomes the class namespace. This builds exactly what aclassstatement would.
So type plays two roles. Called with one argument, it tells you an object's type. Called with three, it creates a class. The thing that creates classes is called a metaclass, and type is the default metaclass of every class.
The chain ends in a loop that is worth seeing once. Every instance is an instance of its class. Every class is an instance of type. And type is an instance of itself.
python
print(type(type), isinstance(type, object), isinstance(object, type))text
<class 'type'> True Truetype is a class, so it is an object. And object is a class, so it is an instance of type. Python wires these two together by hand at startup, because neither could be created first.
7. Writing a metaclass
You can make your own metaclass by subclassing type. Its __new__ runs every time a class using it is created, so it can inspect or change each class as it is being built. Here is a payments module where every new payment method registers itself automatically.
python
class PluginRegistry(type): # (1)
plugins = {}
def __new__(mcls, name, bases, namespace): # (2)
print(f" metaclass building {name}")
cls = super().__new__(mcls, name, bases, namespace) # (3)
if bases: # (4)
mcls.plugins[namespace.get("code", name.lower())] = cls
return cls
class PaymentMethod(metaclass=PluginRegistry): # (5)
pass
class Card(PaymentMethod):
code = "card"
class Upi(PaymentMethod):
code = "upi"
print(PluginRegistry.plugins)
print(type(Card)) # (6)text
metaclass building PaymentMethod
metaclass building Card
metaclass building Upi
{'card': <class '__main__.Card'>, 'upi': <class '__main__.Upi'>}
<class '__main__.PluginRegistry'>(1)A metaclass is a class that inherits fromtype.(2)Its__new__receives the same three thingstype()does. The first argument is the metaclass itself, conventionally namedmcls.(3)We lettypebuild the class normally.(4)Then we register it, skipping the base class itself, which has no parents of its own here.(5)metaclass=chooses the metaclass. Subclasses inherit it, soCardandUpiare also built byPluginRegistry.(6)The type ofCardis now our metaclass, nottype.
Now a request handler can look up PluginRegistry.plugins["upi"] and never needs a hand-maintained list of payment methods.
The simpler tool: __init_subclass__
Most metaclasses written before 2016 only wanted to run some code whenever a subclass was created. Python 3.6 added a far simpler hook for exactly that, described in PEP 487. A method called __init_subclass__ on a parent class runs every time a subclass is defined.
python
class PaymentMethod:
registry = {}
def __init_subclass__(cls, code, **kwargs): # (1)
super().__init_subclass__(**kwargs)
print(f" registering {cls.__name__} as {code!r}")
PaymentMethod.registry[code] = cls
class Card(PaymentMethod, code="card"): # (2)
pass
class Upi(PaymentMethod, code="upi"):
pass
print(PaymentMethod.registry)text
registering Card as 'card'
registering Upi as 'upi'
{'card': <class '__main__.Card'>, 'upi': <class '__main__.Upi'>}(1)It is implicitly a class method.clsis the new subclass, and it can take its own keyword arguments.(2)Keyword arguments in theclassline are passed straight to__init_subclass__.
Same result, no metaclass, and no risk of metaclass conflicts when someone combines two libraries that each bring their own. The rule today is: reach for __init_subclass__ or a class decorator first, and a metaclass only when you must change how the class itself is built or behaves. Tim Peters, who wrote the Zen of Python, put it this way: "Metaclasses are deeper magic than 99% of users should ever worry about. If you wonder whether you need them, you don't."
8. How Pydantic and ORMs use all of this
Now put the two halves together and you can read the source of the libraries you use every day. Here is a tiny model library built from a descriptor and __init_subclass__ alone.
python
class Field:
def __init__(self, kind):
self.kind = kind
def __set_name__(self, owner, name): # (1)
self.name = name
def __get__(self, instance, owner=None):
if instance is None:
return self
return instance.__dict__[self.name]
def __set__(self, instance, value): # (2)
if not isinstance(value, self.kind):
raise TypeError(f"{self.name} must be {self.kind.__name__}, got {type(value).__name__}")
instance.__dict__[self.name] = value
class Model:
def __init_subclass__(cls, **kwargs): # (3)
super().__init_subclass__(**kwargs)
cls._fields = [name for name, value in vars(cls).items() if isinstance(value, Field)]
def __init__(self, **values): # (4)
for name in self._fields:
setattr(self, name, values[name])
def __repr__(self):
shown = ", ".join(f"{name}={getattr(self, name)!r}" for name in self._fields)
return f"{type(self).__name__}({shown})"
class Customer(Model):
name = Field(str)
age = Field(int)
print(Customer._fields, Customer(name="Asha", age=31))
try:
Customer(name="Asha", age="31")
except TypeError as error:
print("TypeError:", error)text
['name', 'age'] Customer(name='Asha', age=31)
TypeError: age must be int, got str(1)Each field learns its own name when the class is created.(2)Each field validates on assignment. It is a data descriptor, so this cannot be bypassed with a plain attribute.(3)WhenCustomeris defined, the base class collects its fields in order. Dicts keep insertion order (3.13.3), so the fields stay in the order you wrote them.(4)A generic__init__uses the collected list, so no model has to write its own constructor.
Real libraries do the same with more care.
- Pydantic uses a metaclass called
ModelMetaclass. When you writeclass Item(BaseModel): sku: str, the metaclass reads the class's type hints rather than descriptor objects, builds a validator for every field, and compiles it into fast Rust code. 3.14.2 opens that up. - SQLAlchemy uses descriptors called
InstrumentedAttributefor every mapped column. Readingorder.totalcan trigger a database load. Setting it records the change so the next commit knows what to save. And readingOrder.totalthrough the class, withinstanceset toNone, returns an object you can use in queries, such asOrder.total > 100. That is theif instance is Nonebranch from section 2, put to clever use. 3.14.6 shows it in practice. - Django models use a metaclass to collect fields and build the database table description.
python
from pydantic import BaseModel
class Item(BaseModel):
sku: str
qty: int
print(type(Item).__name__, list(Item.model_fields))text
ModelMetaclass ['sku', 'qty']9. __class_getitem__: why list[int] works
One last class-level hook explains a piece of syntax you use constantly. list[int] looks like indexing a class. Indexing an instance calls __getitem__. Indexing a class calls __class_getitem__, added in Python 3.7 for type hints.
python
class Repository:
def __class_getitem__(cls, item):
return f"Repository of {item.__name__}"
print(Repository[int]) # (1)
print(list[int], type(list[int])) # (2)text
Repository of int
list[int] <class 'types.GenericAlias'>(1)Our own class decides whatRepository[int]means.(2)Built-in types return aGenericAlias, a small object that records "a list of ints" for type checkers and for runtime tools such as Pydantic and FastAPI to read. 3.13.12 uses this everywhere.
What the interviewer will push on
"What is a descriptor?" An object stored as a class attribute that defines __get__, and optionally __set__ or __delete__, so attribute access on instances is routed through it. The tell of real understanding is the data versus non-data distinction and the lookup order: data descriptor, then instance dict, then non-data descriptor.
"How does self get passed to a method?" Functions are non-data descriptors. obj.method calls function.__get__(obj, type(obj)), which returns a bound method holding both. Almost nobody answers this way, and it is the answer that shows depth.
"How is @property implemented, and why can't an instance attribute hide it?" property is a data descriptor class whose getter, setter and deleter are stored functions. Data descriptors are checked before the instance dict. Contrast with cached_property, which is non-data and relies on the instance dict hiding it after the first read.
"What is a metaclass, and when would you use one?" The class of a class. type by default. Its __new__ and __init__ run when a class is created. A strong answer says you rarely need one: __init_subclass__ and class decorators cover registration and validation. Keep metaclasses for changing class creation itself, as ORMs and Pydantic do.
"What is the difference between __getattr__ and __getattribute__?" __getattr__ is called only when normal lookup fails. __getattribute__ runs on every access and replaces the algorithm. Mention the infinite-recursion trap and object.__getattribute__.
Something to volunteer that nobody asks for: SQLAlchemy's Order.total > 100 works because the column descriptor's __get__ returns a query expression when instance is None and the stored value otherwise. One descriptor serves both your query and your data, which shows how far this small protocol goes.
Recall
- Every
obj.nameruns__getattribute__. The order is: data descriptor on the class, thenobj.__dict__, then non-data descriptor, then plain class attribute, then__getattr__, thenAttributeError. Assignment uses a data descriptor's__set__if present, otherwiseobj.__dict__. - A descriptor defines
__get__(and maybe__set__/__delete__).__set_name__tells it its name at class creation.instance is Nonemeans it was accessed through the class. - Functions are non-data descriptors, and their
__get__makes bound methods.classmethodbinds to the class.staticmethodbinds to nothing.propertyis a data descriptor.cached_propertyis non-data and caches in the instance dict.__slots__entries are data descriptors. __getattr__is a fallback.__getattribute__replaces everything. RaiseAttributeErrorfor missing names.type(name, bases, ns)builds classes. A metaclass subclassestypeand runs at class creation. Prefer__init_subclass__or a class decorator. Pydantic uses a metaclass. ORMs use descriptors.__class_getitem__makeslist[int]work.
Self-test: Walk the lookup ladder for cart.total when total is a method. Why can an instance attribute hide a method but not a property? How does cached_property stop calling itself after the first read? What does type("A", (), {}) return? When is __init_subclass__ enough?
Quiz Bank
FoundationalWhy can an instance attribute hide a method but not a property?
Because of the order of the lookup algorithm. A method is a plain function, which is a non-data descriptor: it has __get__ but no __set__. Non-data descriptors are checked after the instance's __dict__, so a same-named instance attribute is found first. A property is a data descriptor: it defines __set__ even without a setter. Data descriptors are checked before the instance dict, so the property always wins.
AppliedYou need ten classes to each validate that certain string fields are non-empty and at most 100 characters. How would you avoid repeating property code?
Write one descriptor class, for example BoundedText(max_length=100), with __set_name__ to learn the field name, __set__ to strip and check the value and raise a clear ValueError, and __get__ to return the stored value from the instance's __dict__. Declare fields as class attributes: name = BoundedText(100). Each class gets validation on every assignment, including inside __init__, with no per-class getters and setters. If the classes are data models crossing an API boundary, Pydantic's Annotated[str, StringConstraints(min_length=1, max_length=100)] gives the same result with less code.
InterviewExplain what happens, step by step, when Python evaluates cart.add('mug') where add is a normal method.
object.__getattribute__(cart, "add") searches type(cart).__mro__ and finds the function add in the class dict. A function has __get__ but no __set__, so it is not a data descriptor. Python checks cart.__dict__ for "add" and does not find it. It then calls add.__get__(cart, type(cart)), which returns a bound method object storing the function as __func__ and the instance as __self__. Calling that bound method with "mug" calls __func__(__self__, "mug"), so self is cart. CPython has an optimisation that skips creating the bound method object for a direct call like this, but the behaviour is exactly the same.
StaffA library you maintain uses a metaclass. Users report a 'metaclass conflict' TypeError when combining your base class with another library's. How do you fix it properly?
The conflict happens because a class's metaclass must be a subclass of all its parents' metaclasses, and two unrelated metaclasses cannot both be satisfied. Look at what your metaclass actually does. If it only registers subclasses, validates class attributes or collects fields, move that logic into __init_subclass__ on your base class, and use __set_name__ on descriptors for per-field setup. Both hooks need no metaclass, so your base class becomes compatible with any other library. Keep a metaclass only if you change class creation itself, such as the namespace type, or class-level operators like __getitem__ on the class. In that case, document a combined metaclass recipe for users.
Next: you have now seen what @dataclass must be doing: reading annotations and writing methods. 3.13.8 shows exactly what it generates, every option it offers, and when to choose a dataclass, a NamedTuple, a TypedDict, an Enum or a Pydantic model.