Providing Multiple Constructors in Your Python Classes

Using Optional Argument Values in .__init__()

An elegant and Pythonic way to simulate multiple constructors is to implement a .__init__() method with optional arguments. You can do this by specifying appropriate default argument values.

To this end, say you need to code a factory class called CumulativePowerFactory. This class will create callable objects that compute specific powers, using a stream of numbers as input. You also need your class to track the total sum of consecutive powers. Finally, your class should accept an argument holding an initial value for the sum of powers.

Go ahead and create a power.py file in your current directory. Then type in the following code to implement CumulativePowerFactory:

# power.py

class CumulativePowerFactory:
    def __init__(self, exponent=2, *, start=0):
        self._exponent = exponent
        self.total = start

    def __call__(self, base):
        power = base ** self._exponent
        self.total += power
        return power

The initializer of CumulativePowerFactory takes two optional arguments, exponent and start. The first argument holds the exponent that you’ll use to compute a series of powers. It defaults to 2, which is a commonly used value when it comes to computing powers.

The star or asterisk symbol (*) after exponent means that start is a keyword-only argument. To pass a value to a keyword-only argument, you need to use the argument’s name explicitly. In other words, to set arg to value, you need to explicitly type arg=value.

The start argument holds the initial value to compute the cumulative sum of powers. It defaults to 0, which is the appropriate value for those cases in which you don’t have a previously computed value to initialize the cumulative sum of powers.

The special method .__call__() turns the instances of CumulativePowerFactory into callable objects. In other words, you can call the instances of CumulativePowerFactory like you call any regular function.

Inside .__call__(), you first compute the power of base raised to exponent. Then you add the resulting value to the current value of .total. Finally, you return the computed power.

To give CumulativePowerFactory a try, open a Python interactive session in the directory containing power.py and run the following code:

>>> from power import CumulativePowerFactory

>>> square = CumulativePowerFactory()
>>> square(21)
441
>>> square(42)
1764
>>> square.total
2205

>>> cube = CumulativePowerFactory(exponent=3)
>>> cube(21)
9261
>>> cube(42)
74088
>>> cube.total
83349

>>> initialized_cube = CumulativePowerFactory(3, start=2205)
>>> initialized_cube(21)
9261
>>> initialized_cube(42)
74088
>>> initialized_cube.total
85554

These examples show how CumulativePowerFactory simulates multiple constructors. For example, the first constructor doesn’t take arguments. It allows you to create class instances that compute powers of 2, which is the default value of the exponent argument. The .total instance attribute holds the cumulative sum of computed powers as you go.

The second example shows a constructor that takes exponent as an argument and returns a callable instance that computes cubes. In this case, .total works the same as in the first example.

The third example shows how CumulativePowerFactory seems to have another constructor that allows you to create instances by providing the exponent and start arguments. Now .total starts with a value of 2205, which initializes the sum of powers.

Using optional arguments when you’re implementing .__init__() in your classes is a clean and Pythonic technique to create classes that simulate multiple constructors.

Checking Argument Types in .__init__()

Another approach to simulate multiple constructors is to write a .__init__() method that behaves differently depending on the argument type. To check the type of a variable in Python, you commonly rely on the built-in isinstance() function. This function returns True if an object is an instance of a given class and False otherwise:

>>> isinstance(42, int)
True

>>> isinstance(42, float)
False

>>> isinstance(42, (list, int))
True

>>> isinstance(42, list | int)  # Python >= 3.10
True

The first argument to isinstance() is the object that you want to type check. The second argument is the class or data type of reference. You can also pass a tuple of types to this argument. If you’re running Python 3.10 or later, then you can also use the new union syntax with the pipe symbol (|).

Now say that you want to continue working on your Person class, and you need that class to also accept the person’s birth date. Your code will represent the birth date as a date object, but for convenience your users will also have the option of providing the birth date as a string with a given format. In this case, you can do something like the following:

>>> from datetime import date

>>> class Person:
...     def __init__(self, name, birth_date):
...         self.name = name
...         if isinstance(birth_date, date):
...             self.birth_date = birth_date
...         elif isinstance(birth_date, str):
...             self.birth_date = date.fromisoformat(birth_date)
...

>>> jane = Person("Jane Doe", "2000-11-29")
>>> jane.birth_date
datetime.date(2000, 11, 29)

>>> john = Person("John Doe", date(1998, 5, 15))
>>> john.birth_date
datetime.date(1998, 5, 15)

Inside .__init__(), you first define the usual .name attribute. The if clause of the conditional statement checks if the provided birth date is a date object. If so, then you define .birth_date to store the date at hand.

The elif clause checks if the birth_date argument is of str type. If so, then you set .birth_date to a date object built from the provided string. Note that the birth_date argument should be a string with a date in ISO format, YYYY-MM-DD.

That’s it! Now you have a .__init__() method that simulates a class with multiple constructors. One constructor takes arguments of date type. The other constructor takes arguments of string type.

The technique in the above example has the drawback that it doesn’t scale well. If you have multiple arguments that can take values of different data types, then your implementation can soon become a nightmare. So, this technique is considered an anti-pattern in Python.

For example, what would happen if your user input a Unix time value for birth_date? Check out the following code snippet:

>>> linda = Person("Linda Smith", 1011222000)

>>> linda.birth_date
Traceback (most recent call last):
    ...
AttributeError: 'Person' object has no attribute 'birth_date'

When you access .birth_date, you get an AttributeError because your conditional statement doesn’t have a branch that considers a different date format.

To fix this issue, you can continue adding elif clauses to cover all the possible date formats that the user can pass. You can also add an else clause to catch unsupported date formats:

>>> from datetime import date

>>> class Person:
...     def __init__(self, name, birth_date):
...         self.name = name
...         if isinstance(birth_date, date):
...             self.birth_date = birth_date
...         elif isinstance(birth_date, str):
...             self.birth_date = date.fromisoformat(birth_date)
...         else:
...             raise ValueError(f"unsupported date format: {birth_date}")
...

>>> linda = Person("Linda Smith", 1011222000)
Traceback (most recent call last):
    ...
ValueError: unsupported date format: 1011222000

In this example, the else clause runs if the value of birth_date isn’t a date object or a string holding a valid ISO date. This way, the exceptional situation doesn’t pass silently.

Constructing a Circle From Its Diameter

To create your first class constructor with @classmethod, say you’re coding a geometry-related application and need a Circle class. Initially, you define your class as follows:

# circle.py

import math

class Circle:
    def __init__(self, radius):
        self.radius = radius

    def area(self):
        return math.pi * self.radius ** 2

    def perimeter(self):
        return 2 * math.pi * self.radius

    def __repr__(self):
        return f"{self.__class__.__name__}(radius={self.radius})"

The initializer of Circle takes a radius value as an argument and stores it in an instance attribute called .radius. Then the class implements methods to compute the circle’s area and perimeter using Python’s math module. The special method .__repr__() returns a suitable string representation for your class.

Go ahead and create the circle.py file in your working directory. Then open the Python interpreter and run the following code to try out Circle:

>>> from circle import Circle

>>> circle = Circle(42)
>>> circle
Circle(radius=42)

>>> circle.area()
5541.769440932395
>>> circle.perimeter()
263.89378290154264

Cool! Your class works correctly! Now say that you also want to instantiate Circle using the diameter. You can do something like Circle(diameter / 2), but that’s not quite Pythonic or intuitive. It’d be better to have an alternative constructor to create circles by using their diameter directly.

Go ahead and add the following class method to Circle right after .__init__():

# circle.py

import math

class Circle:
    def __init__(self, radius):
        self.radius = radius

    @classmethod
    def from_diameter(cls, diameter):
        return cls(radius=diameter / 2)

    # ...

Here, you define .from_diameter() as a class method. Its first argument receives a reference to the containing class, Circle.

The second argument holds the diameter of the specific circle that you want to create. Inside the method, you first calculate the radius using the input value of diameter. Then you instantiate Circle by calling cls with the radius that results from the diameter argument.

This way, you’re in full control of creating and initializing the instances of Circle using the diameter as an argument.

The call to the cls argument automatically runs the object creation and initialization steps that Python needs to instantiate a class. Finally, .from_diameter() returns the new instance to the caller.

Here’s how you can use your brand-new constructor to create circles by using the diameter:

>>> from circle import Circle

>>> Circle.from_diameter(84)
Circle(radius=42.0)

>>> circle.area()
5541.769440932395
>>> circle.perimeter()
263.89378290154264

The call to .from_diameter() on Circle returns a new instance of the class. To construct that instance, the method uses the diameter instead of the radius. Note that the rest of the functionality of Circle works the same as before.

Using @classmethod as you did in the example above is the most common way to provide explicit multiple constructors in your classes. With this technique, you have the option to select the right name for each alternative constructor that you provide, which can make your code more readable and maintainable.

Building a Polar Point From Cartesian Coordinates

For a more elaborate example of providing multiple constructors using class methods, say you have a class representing a polar point in a math-related application. You need a way to make your class more flexible so that you can construct new instances using Cartesian coordinates as well.

Here’s how you can write a constructor to meet this requirement:

# point.py

import math

class PolarPoint:
    def __init__(self, distance, angle):
        self.distance = distance
        self.angle = angle

    @classmethod
    def from_cartesian(cls, x, y):
        distance = math.dist((0, 0), (x, y))
        angle = math.degrees(math.atan2(y, x))
        return cls(distance, angle)

    def __repr__(self):
        return (
            f"{self.__class__.__name__}"
            f"(distance={self.distance:.1f}, angle={self.angle:.1f})"
        )

In this example, .from_cartesian() takes two arguments representing a given point’s x and y Cartesian coordinates. Then the method calculates the required distance and angle to construct the corresponding PolarPoint object. Finally, .from_cartesian() returns a new instance of the class.

Here’s how the class works, using both coordinate systems:

>>> from point import PolarPoint

>>> # With polar coordinates
>>> PolarPoint(13, 22.6)
PolarPoint(distance=13.0, angle=22.6)

>>> # With cartesian coordinates
>>> PolarPoint.from_cartesian(x=12, y=5)
PolarPoint(distance=13.0, angle=22.6)

In these examples, you use the standard instantiation process and your alternative constructor, .from_cartesian(), to create PolarPoint instances using conceptually different initialization arguments.

Constructing Dictionaries From Keys

Dictionaries are a fundamental data type in Python. They’re present in every piece of Python code, either explicitly or implicitly. They’re also a cornerstone of the language itself because important parts of the CPython implementation rely on them.

You have several ways to define dictionary instances in Python. You can use dictionary literals, which consist of key-value pairs in curly brackets ({}). You can also call dict() explicitly with keyword arguments or with a sequence of two-item tuples, for example.

This popular class also implements an alternative constructor called .fromkeys(). This class method takes an iterable of keys and an optional value. The value argument defaults to None and works as the value for all the keys in the resulting dictionary.

Now, how can .fromkeys() be useful in your code? Say you’re running an animal shelter, and you need to build a small application to track how many animals currently live in your shelter. Your app uses a dictionary to store the inventory of animals.

Because you already know which species you’re capable of housing at the shelter, you can create the initial inventory dictionary dynamically, like in the following code snippet:

>>> allowed_animals = ["dog", "cat", "python", "turtle"]

>>> animal_inventory = dict.fromkeys(allowed_animals, 0)

>>> animal_inventory
{'dog': 0, 'cat': 0, 'python': 0, 'turtle': 0}

In this example, you build an initial dictionary using .fromkeys(), which takes the keys from allowed_animals. You set the initial inventory of each animal to 0 by providing this value as the second argument to .fromkeys().

As you already learned, value defaults to None, which can be a suitable initial value for your dictionary’s keys in some situations. However, in the example above, 0 is a convenient value because you’re working with the number of individuals that you have from each species.

Other mappings in the standard library also have a constructor called .fromkeys(). This is the case with OrderedDict, defaultdict, and UserDict. For example, the source code of UserDict provides the following implementation of .fromkeys():

@classmethod
def fromkeys(cls, iterable, value=None):
    d = cls()
    for key in iterable:
        d[key] = value
    return d

Here, .fromkeys() takes an iterable and a value as arguments. The method creates a new dictionary by calling cls. Then it iterates over the keys in iterable and sets each value to value, which defaults to None, as usual. Finally, the method returns the newly created dictionary.

Creating datetime.date Objects

The datetime.date class from the standard library is another class that takes advantage of multiple constructors. This class provides several alternative constructors, such as .today(), .fromtimestamp(), .fromordinal(), and .fromisoformat(). All of them allow you to construct datetime.date objects using conceptually different arguments.

Here are a few examples of how to use some of those constructors to create datetime.date objects:

>>> from datetime import date
>>> from time import time

>>> # Standard constructor
>>> date(2022, 1, 13)
datetime.date(2022, 1, 13)

>>> date.today()
datetime.date(2022, 1, 13)

>>> date.fromtimestamp(1642110000)
datetime.date(2022, 1, 13)
>>> date.fromtimestamp(time())
datetime.date(2022, 1, 13)

>>> date.fromordinal(738168)
datetime.date(2022, 1, 13)

>>> date.fromisoformat("2022-01-13")
datetime.date(2022, 1, 13)

The first example uses the standard class constructor as a reference. The second example shows how you can use .today() to build a date object from the current day’s date.

The rest of the examples show how datetime.date uses several class methods to provide multiple constructors. This variety of constructors makes the instantiation process pretty versatile and powerful, covering a wide range of use cases. It also improves the readability of your code with descriptive method names.

Finding Your Path to Home

Python’s pathlib module from the standard library provides convenient and modern tools for gracefully handling system paths in your code. If you’ve never used this module, then check out Python 3’s pathlib Module: Taming the File System.

The handiest tool in pathlib is its Path class. This class allows you to handle your system path in a cross-platform way. Path is another standard-library class that provides multiple constructors. For example, you’ll find Path.home(), which creates a path object from your home directory:

• Windows
• Linux + macOS

>>> from pathlib import Path

>>> Path.home()
WindowsPath('C:/Users/username')

>>> from pathlib import Path

>>> Path.home()
PosixPath('/home/username')

The .home() constructor returns a new path object representing the user’s home directory. This alternative constructor can be useful when you’re handling configuration files in your Python applications and projects.

Finally, Path also provides a constructor called .cwd(). This method creates a path object from your current working directory. Go ahead and give it a try!

A Demo Example of a Single-Dispatch Method

To apply the single-dispatch method technique to a given class, you need to define a base method implementation and decorate it with @singledispatchmethod. Then you can write alternative implementations and decorate them using the name of the base method plus .register.

Here’s an example that shows the basic syntax:

# demo.py

from functools import singledispatchmethod

class DemoClass:
    @singledispatchmethod
    def generic_method(self, arg):
        print(f"Do something with argument of type: {type(arg).__name__}")

    @generic_method.register
    def _(self, arg: int):
        print("Implementation for an int argument...")

    @generic_method.register(str)
    def _(self, arg):
        print("Implementation for a str argument...")

In DemoClass, you first define a base method called generic_method() and decorate it with @singledispatchmethod. Then you define two alternative implementations of generic_method() and decorate them with @generic_method.register.

In this example, you name the alternative implementations using a single underscore (_) as a placeholder name. In real code, you should use descriptive names, provided that they’re different from the base method name, generic_method(). When using descriptive names, consider adding a leading underscore to mark the alternative methods as non-public and prevent direct calls from your end users.

You can use type annotations to define the type of the target argument. You can also explicitly pass the type of the target argument to the .register() decorator. If you need to define a method to process several types, then you can stack multiple calls to .register(), with the required type for each.

Here’s how your class works:

>>> from demo import DemoClass

>>> demo = DemoClass()

>>> demo.generic_method(42)
Implementation for an int argument...

>>> demo.generic_method("Hello, World!")
Implementation for a str argument...

>>> demo.generic_method([1, 2, 3])
Do something with argument of type: list

If you call .generic_method() with an integer number as an argument, then Python runs the implementation corresponding to the int type. Similarly, when you call the method with a string, Python dispatches the string implementation. Finally, if you call .generic_method() with an unregistered data type, such as a list, then Python runs the base implementation of the method.

You can also use this technique to overload .__init__(), which will allow you to provide multiple implementations for this method, and therefore, your class will have multiple constructors.

A Real-World Example of a Single-Dispatch Method

As a more realistic example of using @singledispatchmethod, say you need to continue adding features to your Person class. This time, you need to provide a way to compute the approximate age of a person based on their birth date. To add this feature to Person, you can use a helper class that handles all the information related to the birth date and age.

Go ahead and create a file called person.py in your working directory. Then add the following code to it:

 1# person.py
 2
 3from datetime import date
 4from functools import singledispatchmethod
 5
 6class BirthInfo:
 7    @singledispatchmethod
 8    def __init__(self, birth_date):
 9        raise ValueError(f"unsupported date format: {birth_date}")
10
11    @__init__.register(date)
12    def _from_date(self, birth_date):
13        self.date = birth_date
14
15    @__init__.register(str)
16    def _from_isoformat(self, birth_date):
17        self.date = date.fromisoformat(birth_date)
18
19    @__init__.register(int)
20    @__init__.register(float)
21    def _from_timestamp(self, birth_date):
22        self.date = date.fromtimestamp(birth_date)
23
24    def age(self):
25        return date.today().year - self.date.year

Here’s a breakdown of how this code works:

• Line 3 imports date from datetime so that you can later convert any input date to a date object.

• Line 4 imports @singledispatchmethod to define the overloaded method.

• Line 6 defines BirthInfo as a regular Python class.

• Lines 7 to 9 define the class initializer as a single-dispatch generic method using @singledispatchmethod. This is the method’s base implementation, and it raises a ValueError for unsupported date formats.

• Lines 11 to 13 register an implementation of .__init__() that processes date objects directly.

• Lines 15 to 17 define the implementation of .__init__() that processes dates that come as strings with an ISO format.

• Lines 19 to 22 register an implementation that processes dates that come as Unix time in seconds since the epoch. This time, you register two instances of the overloaded method by stacking the .register decorator with the int and float types.

• Lines 24 to 25 provide a regular method to compute the age of a given person. Note that the implementation of age() isn’t totally accurate because it doesn’t consider the month and day of the year when calculating the age. The age() method is just a bonus feature to enrich the example.

Now you can use composition in your Person class to take advantage of the new BirthInfo class. Go ahead and update Person with the following code:

# person.py
# ...

class Person:
    def __init__(self, name, birth_date):
        self.name = name
        self._birth_info = BirthInfo(birth_date)

    @property
    def age(self):
        return self._birth_info.age()

    @property
    def birth_date(self):
        return self._birth_info.date

In this update, Person has a new non-public attribute called ._birth_info, which is an instance of BirthInfo. This instance is initialized with the input argument birth_date. The overloaded initializer of BirthInfo will initialize ._birth_info according to the user’s birth date.

Then you define age() as a property to provide a computed attribute that returns the person’s current approximate age. The final addition to Person is the birth_date() property, which returns the person’s birth date as a date object.

To try out your Person and BirthInfo classes, open an interactive session and run the following code:

>>> from person import Person

>>> john = Person("John Doe", date(1998, 5, 15))
>>> john.age
24
>>> john.birth_date
datetime.date(1998, 5, 15)

>>> jane = Person("Jane Doe", "2000-11-29")
>>> jane.age
22
>>> jane.birth_date
datetime.date(2000, 11, 29)

>>> linda = Person("Linda Smith", 1011222000)
>>> linda.age
20
>>> linda.birth_date
datetime.date(2002, 1, 17)

>>> david = Person("David Smith", {"year": 2000, "month": 7, "day": 25})
Traceback (most recent call last):
    ...
ValueError: unsupported date format: {'year': 2000, 'month': 7, 'day': 25}

You can instantiate Person using different date formats. The internal instance of BirthDate automatically converts the input date into a date object. If you instantiate Person with an unsupported date format, such as a dictionary, then you get a ValueError.

Note that BirthDate.__init__() takes care of processing the input birth date for you. There’s no need to use explicit alternative constructors to process different types of input. You can just instantiate the class using the standard constructor.

The main limitation of the single-dispatch method technique is that it relies on a single argument, the first argument after self. If you need to use multiple arguments for dispatching appropriate implementations, then check out some existing third-party libraries, such as multipledispatch and multimethod.