Understanding the Python Class Creation Process

The Python Class Creation Process in Two Phases

When you write a class definition in Python, the interpreter does more than store a blueprint. It executes the class body and then invokes a metaclass to build the class object itself. Later, each instance goes through its own creation sequence involving __new__ and __init__. Understanding this process lets you control behavior at both the class level and the instance level.

What Happens When You Define a Class

A class statement triggers the following steps:

1. The class body is executed in a new namespace.
2. The metaclass is determined (either explicitly via metaclass= or by inheriting from a parent class).
3. The metaclass is called with the class name, bases, and namespace to produce the class object.
4. The class object is bound to the name in the enclosing scope.

The default metaclass is type. When you write class MyClass:, Python effectively calls type('MyClass', (), namespace). The namespace contains the attributes defined in the body.

class MyClass:
    x = 10

    def method(self):
        return self.x

Under the hood, this is roughly equivalent to:

namespace = {'x': 10, 'method': lambda self: self.x}
MyClass = type('MyClass', (), namespace)

The type call returns a new class object. That object is what you use to create instances later.

Customizing Class Creation with Metaclasses

A metaclass is a class whose instances are classes. By subclassing type and overriding its __new__ or __init__, you can intercept class creation. This is useful for validation, registration, or adding methods automatically.

class ValidatedMeta(type):
    def __new__(mcls, name, bases, namespace):
        if 'required_attr' not in namespace:
            raise TypeError(f"{name} must define 'required_attr'")
        return super().__new__(mcls, name, bases, namespace)

class Base(metaclass=ValidatedMeta):
    required_attr = "present"

# This raises TypeError:
# class Broken(Base):
#     pass

Here, ValidatedMeta.__new__ runs before the class object exists. It checks the namespace and raises an error if a required attribute is missing. The metaclass must return a class object, usually by calling super().__new__.

Metaclasses are powerful but can make code harder to follow. Use them when you need to enforce invariants across many classes or when you want to modify class behavior uniformly.

Instance Creation: __new__ and __init__

When you call a class to create an instance, Python performs two steps:

1. __new__ is called to allocate and return a new instance.
2. __init__ is called to initialize that instance, if __new__ returns an instance of the class.

__new__ is a static method (though it's passed the class as the first argument). It's responsible for creating the object. __init__ receives the instance and sets up its state.

class Point:
    def __new__(cls, x, y):
        print("Creating instance")
        instance = super().__new__(cls)
        return instance

    def __init__(self, x, y):
        print("Initializing instance")
        self.x = x
        self.y = y

p = Point(1, 2)

The output shows that __new__ runs first, then __init__. If __new__ returns an object that is not an instance of cls, __init__ is not called. This is useful for returning cached instances or singletons.

class Singleton:
    _instance = None

    def __new__(cls):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance

s1 = Singleton()
s2 = Singleton()
assert s1 is s2

Here, __new__ controls instance creation, ensuring only one instance exists.

The Role of __init_subclass__ and Class Decorators

For many customization needs, you don't need a full metaclass. Python provides __init_subclass__, a hook called when a subclass is created. It's defined on a base class and receives the new subclass.

class Base:
    def __init_subclass__(cls, **kwargs):
        super().__init_subclass__(**kwargs)
        cls.registered = True

class Child(Base):
    pass

print(Child.registered)  # True

Class decorators are another lighter alternative. They run after the class is created and can modify or wrap it.

def add_greeting(cls):
    cls.greet = lambda self: "Hello"
    return cls

@add_greeting
class Greeter:
    pass

g = Greeter()
print(g.greet())

Both approaches are easier to reason about than metaclasses when you only need to adjust subclasses or a single class.

Common Mistakes and Pitfalls

A frequent error is forgetting to call super().__init__ in a subclass, which breaks parent initialization. Similarly, when overriding __new__, you must return an instance, or __init__ will be skipped silently.

Another pitfall is using metaclasses for tasks that __init_subclass__ can handle. Metaclasses introduce an extra layer of complexity and can conflict with other metaclasses if multiple inheritance is involved. Python requires a class to have a single metaclass, so combining two classes with different metaclasses raises a TypeError.

Also, be careful with __new__ when subclassing immutable types like tuple or int. Because those types are immutable, you must set attributes in __new__, not __init__.

class NamedTuple(tuple):
    def __new__(cls, name, *values):
        instance = super().__new__(cls, values)
        instance.name = name  # This fails because tuple is immutable
        return instance

To handle immutability, you need to use __new__ to set attributes via object.__setattr__ or use a different pattern.

Performance and Maintainability Considerations

Metaclasses and custom __new__ add overhead to class and instance creation. In most applications, this overhead is negligible, but in hot paths where millions of instances are created, it can matter. Profile before optimizing.

From a maintainability perspective, metaclasses are often overused. They make the codebase harder to navigate because the creation logic is hidden. Prefer __init_subclass__ or class decorators when they suffice. Reserve metaclasses for cases where you need to intercept class creation itself, such as registering classes in a plugin system or enforcing interface contracts.

The class creation process is a core part of Python's object model. Knowing how it works helps you write more predictable code and debug issues when classes behave unexpectedly.