Python Metaclasses Tutorial

The Story That Explains Metaclasses 🍪Metaclasses समझाने वाली कहानी 🍪一个讲清元类的故事 🍪

Everything Is an Object — Including Classes 🪜सब कुछ Object है — Classes भी 🪜一切皆对象 — 包括类 🪜

One central truth unlocks metaclasses: classes are objects too. You can pass them around, store them in lists and give them new attributes — and they were themselves made by another class. That maker is type.

एक मूल सच metaclasses को खोलता है: classes भी objects हैं। आप उन्हें पास कर सकते हैं, lists में रख सकते हैं, नए attributes दे सकते हैं — और उन्हें ख़ुद किसी दूसरी class ने बनाया था। वह बनाने वाला type है।

理解元类的关键只有一条：类也是对象。你可以传递它们、放进列表、给它们添加新属性 — 而且它们 本身 也是由另一个类创建的。这个创建者就是 type。

class Dog:
    pass

buddy = Dog()

# buddy is an instance of Dog
print(type(buddy))         # <class '__main__.Dog'>

# Dog is an instance of type - that's the metaclass level
print(type(Dog))           # <class 'type'>

# type is itself an instance of type - the chain stops here
print(type(type))          # <class 'type'>

# Classes have __class__ pointing to their metaclass
print(Dog.__class__)       # <class 'type'>

🪜 Simulator: The type() Ladder🪜 Simulator: type() सीढ़ी🪜 模拟器：type() 阶梯

Pick anything — an instance, a class, a built-in, a metaclass. The ladder climbs by asking type() again and again until it reaches type. All chains were read from real Python objects.

कुछ भी चुनिए — instance, class, built-in, metaclass। सीढ़ी बार-बार type() पूछकर ऊपर चढ़ती है जब तक type तक न पहुँचे। सारी chains असली Python objects से पढ़ी गई हैं।

随便选一个 — 实例、类、内置类型、元类。阶梯会一次次地调用 type() 向上爬，直到到达 type。所有链条都读取自真实的 Python 对象。

Creating a Class Dynamically With type() 🏗️type() से Class बनाना 🏗️用 type() 动态创建类 🏗️

Because type is the metaclass, calling it with three arguments creates a class — no class keyword needed. A class statement works the same way: Python runs the body to build the namespace, then calls the metaclass with the name, the bases and that namespace.

क्योंकि type metaclass है, उसे तीन arguments के साथ बुलाने पर class बन जाती है — class keyword की ज़रूरत नहीं। class statement भी ऐसे ही काम करता है: Python body चलाकर namespace बनाता है, फिर नाम, bases और उस namespace के साथ metaclass को बुलाता है।

因为 type 是元类，用三个参数调用它就能 创建一个类 — 不需要 class 关键字。class 语句也是这样工作的：Python 先运行类体来构建命名空间，然后用名字、基类和这个命名空间调用元类。

# These two forms produce equivalent classes

# Form 1 - the class keyword you already know
class Dog:
    species = "Canis familiaris"
    def bark(self):
        return f"{self.species} says woof"


# Form 2 - the same thing, built by calling type() directly
def bark(self):
    return f"{self.species} says woof"

Dog2 = type(
    "Dog2",                                       # class name
    (),                                           # base classes
    {"species": "Canis familiaris", "bark": bark} # namespace
)

# Both work the same way
print(Dog().bark())       # Canis familiaris says woof
print(Dog2().bark())      # Canis familiaris says woof
print(type(Dog) is type(Dog2))   # True - both classes have type as their metaclass

🏭 Simulator: Class Factory🏭 Simulator: Class Factory🏭 模拟器：类工厂

Choose a name, a base class and what goes in the namespace. The same class is written both ways — with class and with type(). For all 32 combinations, both forms were run and gave identical output.

नाम, base class और namespace में क्या जाए, यह चुनिए। वही class दोनों तरह लिखी जाती है — class से और type() से। सभी 32 combinations में दोनों रूप चलाए गए और एक जैसा output मिला।

选择名字、基类以及命名空间里放什么。同一个类会用两种方式写出 — class 语句和 type() 调用。全部 32 种组合都运行了两种写法，输出完全相同。

Your First Custom Metaclass 🔧आपका पहला Custom Metaclass 🔧你的第一个自定义元类 🔧

To write a metaclass, subclass type. Override its __new__ or __init__ to run code every time a class using your metaclass is defined. Then attach it with metaclass=YourMeta in the class header.

Metaclass लिखने के लिए type की subclass बनाइए। उसका __new__ या __init__ override कीजिए ताकि आपके metaclass वाली class के define होते ही code चले। फिर class header में metaclass=YourMeta से जोड़िए।

要写一个元类，就继承 type。重写它的 __new__ 或 __init__，让每次 定义 使用该元类的类时都运行你的代码。然后在类头部用 metaclass=YourMeta 把它挂上。

class LoggingMeta(type):
    """A metaclass that announces every class defined with it."""

    def __new__(mcs, name, bases, namespace):
        print(f"[LoggingMeta] creating class {name!r} with {len(namespace)} attrs")
        # Let type do the real creation
        cls = super().__new__(mcs, name, bases, namespace)
        # Free to change the class here - add methods, add attributes...
        cls.created_at = "2026-07-12"
        return cls


class Cat(metaclass=LoggingMeta):
    def meow(self):
        return "meow"


class Dog(metaclass=LoggingMeta):
    def bark(self):
        return "woof"


# The metaclass added created_at to every class
print(Cat.created_at)    # 2026-07-12
print(Dog.created_at)    # 2026-07-12

# type() confirms the metaclass
print(type(Cat))         # <class '__main__.LoggingMeta'>
print(type(Dog))         # <class '__main__.LoggingMeta'>

class ShowMeta(type):
    def __new__(mcs, name, bases, namespace):
        print(list(namespace))          # everything the class body produced
        return super().__new__(mcs, name, bases, namespace)


class Cat(metaclass=ShowMeta):
    def meow(self):
        return "meow"

What Do Meta.__new__, __init__ and __call__ Control? ⏱️Meta.__new__, __init__ और __call__ क्या control करते हैं? ⏱️Meta.__new__、__init__ 和 __call__ 分别控制什么？⏱️

class Meta(type):
    def __new__(mcs, name, bases, namespace):
        print(f"  [Meta.__new__]  creating class {name!r}")
        return super().__new__(mcs, name, bases, namespace)

    def __init__(cls, name, bases, namespace):
        print(f"  [Meta.__init__] class {name!r} is ready")
        super().__init__(name, bases, namespace)

    def __call__(cls, *args, **kwargs):
        print(f"  [Meta.__call__] creating an instance of {cls.__name__}")
        return super().__call__(*args, **kwargs)


print("Defining Dog:")
class Dog(metaclass=Meta):
    def __init__(self, name):
        self.name = name

print("\nCreating buddy:")
buddy = Dog("Buddy")
print(buddy.name)

⏱️ Simulator: Metaclass Timeline⏱️ Simulator: Metaclass Timeline⏱️ 模拟器：元类时间线

Press the buttons in any order. Defining a class lights up the class-definition lane; creating an instance lights up the instance lane. Try creating Dog("Buddy") before defining Dog. Checked against Python on 300 random sequences.

Buttons किसी भी क्रम में दबाइए। Class define करने पर class-definition lane जलती है; instance बनाने पर instance lane। Dog define करने से पहले Dog("Buddy") बनाकर देखिए। 300 random sequences पर Python से जाँचा गया।

以任意顺序按按钮。定义类会点亮 类定义 通道；创建实例会点亮 实例 通道。试试在定义 Dog 之前先创建 Dog("Buddy")。已在 300 个随机序列上与 Python 对照。

Practical Example 1 — Enforcing Class Design Rules 📏Practical Example 1 — Class Design के नियम लागू करना 📏实战示例 1 — 强制类设计规则 📏

A metaclass that checks every class it builds. Here every public method name must be lowercase — a small stand-in for the real coding standards a team might want to enforce.

ऐसा metaclass जो अपनी बनाई हर class को जाँचता है। यहाँ हर public method का नाम lowercase होना चाहिए — असली coding standards का एक छोटा उदाहरण जिन्हें कोई team लागू करना चाहे।

一个会检查它创建的每个类的元类。这里要求每个公有方法的名字都必须是小写 — 这是团队可能想强制执行的真实编码规范的一个小例子。

class SnakeCaseMeta(type):
    """Every public method must be snake_case (lowercase)."""

    def __new__(mcs, name, bases, namespace):
        for attr_name, attr_value in namespace.items():
            # Only check callable, public attributes
            if callable(attr_value) and not attr_name.startswith("_"):
                if not attr_name.islower():
                    raise TypeError(
                        f"In class {name!r}: method {attr_name!r} "
                        "must be lowercase (snake_case)"
                    )
        return super().__new__(mcs, name, bases, namespace)


# -- This class is fine - all methods are snake_case --
class Good(metaclass=SnakeCaseMeta):
    def do_something(self):
        return "ok"

    def save_to_disk(self):
        return "saved"

print("Good class created successfully")


# -- This class breaks the rule - refused at DEFINITION time --
try:
    class Bad(metaclass=SnakeCaseMeta):
        def DoSomething(self):        # PascalCase - not allowed
            return "nope"
except TypeError as e:
    print("Blocked:", e)

📏 Simulator: Rule Checker📏 Simulator: Rule Checker📏 模拟器：规则检查器

Switch members on and off in the class body. Watch SnakeCaseMeta.__new__ scan the namespace in order: private names and non-callables are skipped, and the first bad name stops the class from being created. All 256 combinations were run in Python.

Class body में members on/off कीजिए। देखिए SnakeCaseMeta.__new__ namespace को क्रम से कैसे जाँचता है: private नाम और non-callables छोड़े जाते हैं, और पहला ग़लत नाम class बनने से रोक देता है। सभी 256 combinations Python में चलाए गए।

在类体中打开或关闭成员。观察 SnakeCaseMeta.__new__ 按顺序扫描命名空间：私有名字和不可调用的属性会被跳过，第一个不合规的名字会阻止类被创建。全部 256 种组合都在 Python 中运行过。

Practical Example 2 — Auto-Registry of Subclasses 📇Practical Example 2 — Subclasses की Auto-Registry 📇实战示例 2 — 子类自动注册 📇

A metaclass that quietly keeps track of every subclass ever defined. Add a new plugin, and it registers itself — no manual bookkeeping. This pattern sits behind plugin systems, model discovery in ORMs, serializer registries and more.

ऐसा metaclass जो define हुई हर subclass का चुपचाप हिसाब रखता है। नया plugin जोड़िए, और वह ख़ुद register हो जाता है — हाथ से हिसाब नहीं। Plugin systems, ORMs में model discovery, serializer registries वग़ैरह के पीछे यही pattern है।

一个默默记录每个已定义子类的元类。新增一个插件，它就会自动注册 — 不用手工登记。插件系统、ORM 中的模型发现、序列化器注册表等背后都是这个模式。

class PluginRegistry(type):
    """A metaclass that auto-registers every subclass into a shared registry."""

    registry = {}    # one dict for the whole metaclass

    def __init__(cls, name, bases, namespace):
        super().__init__(name, bases, namespace)
        # Don't register the base "Plugin" itself - only its children
        if bases:
            PluginRegistry.registry[name] = cls
            print(f"[registry] Registered {name}")


# The base class - not registered because it has no bases
class Plugin(metaclass=PluginRegistry):
    def run(self, msg):
        raise NotImplementedError


# Every subclass is added to the registry automatically
class EmailPlugin(Plugin):
    def run(self, msg):
        return f"EMAIL: {msg}"

class SMSPlugin(Plugin):
    def run(self, msg):
        return f"SMS: {msg}"

class PushPlugin(Plugin):
    def run(self, msg):
        return f"PUSH: {msg}"


# The registry now holds every plugin - dispatch by name
print()
print("All registered plugins:", list(PluginRegistry.registry))

for plugin_name, plugin_cls in PluginRegistry.registry.items():
    plugin = plugin_cls()
    print(f"  {plugin_name} → {plugin.run('hello')}")

The Modern Alternative — __init_subclass__ ✨आधुनिक विकल्प — __init_subclass__ ✨现代替代方案 — __init_subclass__ ✨

Python 3.6 added __init_subclass__, which covers most real uses of metaclasses with much less ceremony. If all you need is "run some code every time a subclass is defined", it is almost always the better choice.

Python 3.6 ने __init_subclass__ जोड़ा, जो बहुत कम झंझट के साथ metaclasses के ज़्यादातर असली इस्तेमाल सँभाल लेता है। अगर आपको बस "हर subclass define होने पर कुछ code चलाना" है, तो यह लगभग हमेशा बेहतर है।

Python 3.6 引入了 __init_subclass__，它用少得多的样板代码覆盖了 元类的大多数实际用途。如果你只需要"每定义一个子类就运行一些代码"，它几乎总是更好的选择。

# -- The SAME auto-registry pattern - no metaclass needed --
class Plugin:
    registry = {}

    def __init_subclass__(cls, **kwargs):
        super().__init_subclass__(**kwargs)
        Plugin.registry[cls.__name__] = cls
        print(f"[registry] Registered {cls.__name__}")


class EmailPlugin(Plugin):
    def run(self, msg): return f"EMAIL: {msg}"

class SMSPlugin(Plugin):
    def run(self, msg): return f"SMS: {msg}"

print(list(Plugin.registry))    # ['EmailPlugin', 'SMSPlugin']

📇 Simulator: Registry Builder📇 Simulator: Registry Builder📇 模拟器：注册表构建器

Build the plugin family one class at a time with three versions: the metaclass from Section 07, the same metaclass without its if bases: check, and __init_subclass__. Then press Run all. All 105 orderings were run in Python.

Plugin परिवार को एक-एक class करके तीन versions में बनाइए: Section 07 का metaclass, वही metaclass if bases: जाँच के बिना, और __init_subclass__। फिर Run all दबाइए। सभी 105 क्रम Python में चलाए गए।

用三个版本一次一个地构建插件家族：第 07 节的元类、去掉 if bases: 检查的同一个元类，以及 __init_subclass__。然后按 Run all。全部 105 种顺序都在 Python 中运行过。

When to Use a Metaclass (and When Not To) 🧭Metaclass कब लें (और कब नहीं) 🧭何时使用元类（以及何时不用）🧭

Common Mistakes (and Fixes) 🩹आम ग़लतियाँ (और उनके हल) 🩹常见错误（及修正）🩹

🩺 Simulator: Bug Doctor🩺 Simulator: Bug Doctor🩺 模拟器：Bug 医生

Five of these mistakes, run for real. Buggy code on the left, fixed code on the right, changed lines marked.

इनमें से पाँच ग़लतियाँ, असली run में। बाईं ओर buggy code, दाईं ओर ठीक किया हुआ, बदली lines चिह्नित।

其中五个错误的真实运行。左边是有 bug 的代码，右边是修正后的代码，改动的行已标出。

Quick Reference 📋Quick Reference 📋速查表 📋

Golden Rules and Quiz 🏆सुनहरे नियम और Quiz 🏆黄金法则与小测验 🏆

Quick Quiz — 8 Questionsछोटा Quiz — 8 सवाल小测验 — 8 道题