Python __new__ and Object Creation

Advanced

When you call a class, Python has to create an instance before that instance can be initialized. __new__() handles the creation step, while __init__() normally handles the initialization step that follows.

See the creation and initialization order

For a normal instance construction, Python first calls __new__() with the class as cls. If it returns an instance of that class, Python then calls __init__() on that instance. The completed object is then returned to the caller.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

class Report:
    def __new__(cls, name):
        print("__new__", name)
        instance = super().__new__(cls)
        return instance

    def __init__(self, name):
        print("__init__", name)
        self.name = name

report = Report("monthly")
print(report.name)

class Record:
    def __new__(cls):
        print("new")
        return super().__new__(cls)

    def __init__(self):
        print("init")

Record()
?

Define __new__ with cls

The first parameter of __new__() is the class being constructed, conventionally named cls. Python treats __new__() as a static method for lookup purposes, so you do not write @staticmethod when defining it this way.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

class User:
    def __new__(cls, name):
        instance = super().__new__(cls)
        return instance

    def __init__(self, name):
        self.name = name

user = User("Mina")
print(user.name)

Let __init__ initialize the created object

The two methods cooperate but should not be treated as interchangeable. __new__() must return the object that the constructor call should use. __init__() receives that object afterward and normally assigns or validates its mutable state. Returning a non- None value from __init__() is invalid.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

class User:
    def __new__(cls, name):
        print("create")
        return super().__new__(cls)

    def __init__(self, name):
        print("initialize")
        self.name = name.upper()

user = User("Mina")
print(user.name)

Use __new__ when an immutable value must be chosen

Immutable built-in types such as str, int, and tuple cannot have their underlying value changed after creation. For a subclass of one of these types, __new__() is the place to compute the value before the immutable object exists.

1
2
3
4
5
6
7

class CleanText(str):
    def __new__(cls, value):
        cleaned = value.strip().lower()
        return super().__new__(cls, cleaned)

text = CleanText("  Ready  ")
print(text)

class CleanText(str):
    def __new__(cls, value):
        cleaned = value.strip()
        return super().__new__(cls, cleaned)

CleanText(" ready ")
?

Return a subclass-aware instance

Use cls rather than hard-coding the base class when calling the parent implementation. That preserves the class actually being constructed and lets subclasses inherit the creation behavior correctly.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

class Code(str):
    def __new__(cls, value):
        value = value.strip()
        return super().__new__(cls, value)

class ShortCode(Code):
    pass

code = ShortCode("  A7  ")
print(code)
print(type(code).__name__)

Know what happens when __new__ returns another type

The normal sequence has an important boundary: if __new__() returns an object that is not an instance of cls, Python does not call that class’s __init__() for the result. The class call simply produces the object returned by __new__().

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

class Token:
    def __new__(cls, value):
        return str(value)

    def __init__(self, value):
        raise RuntimeError("Token.__init__ should not run")

result = Token(42)
print(result)
print(type(result).__name__)

class Token:
    def __new__(cls, value):
        return str(value)

Token(42)
?

Keep metaclass creation separate

This lesson is about __new__() for creating ordinary instances. Python also uses __new__() in custom metaclasses to customize class creation, but that is a different data-model layer and belongs with metaclasses rather than with ordinary instance construction.

class Item:
    def __new__(cls):
        print("new")
        return super().__new__(cls)

    def __init__(self):
        print("init")

Item()
?