Using Optional Argument Values in.__init__()

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

To this end, say you need to code afactory class calledCumulativePowerFactory. 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 apower.py file in your current directory. Then type in the following code to implementCumulativePowerFactory:

classCumulativePowerFactory:def__init__(self,exponent=2,*,start=0):self._exponent=exponentself.total=startdef__call__(self,base):power=base**self._exponentself.total+=powerreturnpower

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

The star or asterisk symbol (*) afterexponent means thatstart is akeyword-only argument. To pass a value to a keyword-only argument, you need to use the argument’s name explicitly. In other words, to setarg tovalue, you need to explicitly typearg=value.

Thestart argument holds the initial value to compute the cumulative sum of powers. It defaults to0, 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 ofCumulativePowerFactory intocallable objects. In other words, you can call the instances ofCumulativePowerFactory like you call any regular function.

Inside.__call__(), you first compute the power ofbase raised toexponent. Then you add the resulting value to the current value of.total. Finally, youreturn the computed power.

To giveCumulativePowerFactory a try, open a Pythoninteractive session in the directory containingpower.py and run the following code:

>>>frompowerimportCumulativePowerFactory>>>square=CumulativePowerFactory()>>>square(21)441>>>square(42)1764>>>square.total2205>>>cube=CumulativePowerFactory(exponent=3)>>>cube(21)9261>>>cube(42)74088>>>cube.total83349>>>initialized_cube=CumulativePowerFactory(3,start=2205)>>>initialized_cube(21)9261>>>initialized_cube(42)74088>>>initialized_cube.total85554

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

The second example shows a constructor that takesexponent 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 howCumulativePowerFactory seems to have another constructor that allows you to create instances by providing theexponent andstart arguments. Now.total starts with a value of2205, 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 avariable in Python, you commonly rely on the built-inisinstance() function. This function returnsTrue if an object is an instance of a given class andFalse otherwise:

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

The first argument toisinstance() is the object that you want to type check. The second argument is the class or data type of reference. You can also pass atuple of types to this argument. If you’re runningPython 3.10 or later, then you can also use the newunion syntax with the pipe symbol (|).

Now say that you want to continue working on yourPerson class, and you need that class to also accept the person’s birth date. Your code will represent the birth date as adate 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:

>>>fromdatetimeimportdate>>>classPerson:...def__init__(self,name,birth_date):...self.name=name...ifisinstance(birth_date,date):...self.birth_date=birth_date...elifisinstance(birth_date,str):...self.birth_date=date.fromisoformat(birth_date)...>>>jane=Person("Jane Doe","2000-11-29")>>>jane.birth_datedatetime.date(2000, 11, 29)>>>john=Person("John Doe",date(1998,5,15))>>>john.birth_datedatetime.date(1998, 5, 15)

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

Theelif clause checks if thebirth_date argument is ofstr type. If so, then you set.birth_date to adate object built from the provided string. Note that thebirth_date argument should be a string with a date inISO format,YYYY-MM-DD.

That’s it! Now you have a.__init__() method that simulates a class with multiple constructors. One constructor takes arguments ofdate 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 aUnix time value forbirth_date? Check out the following code snippet:

>>>linda=Person("Linda Smith",1011222000)>>>linda.birth_dateTraceback (most recent call last):...AttributeError:'Person' object has no attribute 'birth_date'

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

To fix this issue, you can continue addingelif clauses to cover all the possible date formats that the user can pass. You can also add anelse clause to catchunsupported date formats:

>>>fromdatetimeimportdate>>>classPerson:...def__init__(self,name,birth_date):...self.name=name...ifisinstance(birth_date,date):...self.birth_date=birth_date...elifisinstance(birth_date,str):...self.birth_date=date.fromisoformat(birth_date)...else:...raiseValueError(f"unsupported date format:{birth_date}")...>>>linda=Person("Linda Smith",1011222000)Traceback (most recent call last):...ValueError:unsupported date format: 1011222000

In this example, theelse clause runs if the value ofbirth_date isn’t adate object or a string holding a valid ISO date. This way, the exceptional situation doesn’tpass 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 aCircle class. Initially, you define your class as follows:

importmathclassCircle:def__init__(self,radius):self.radius=radiusdefarea(self):returnmath.pi*self.radius**2defperimeter(self):return2*math.pi*self.radiusdef__repr__(self):returnf"{self.__class__.__name__}(radius={self.radius})"

The initializer ofCircle 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’smath module. The special method.__repr__() returns a suitablestring representation for your class.

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

>>>fromcircleimportCircle>>>circle=Circle(42)>>>circleCircle(radius=42)>>>circle.area()5541.769440932395>>>circle.perimeter()263.89378290154264

Cool! Your class works correctly! Now say that you also want to instantiateCircle using the diameter. You can do something likeCircle(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 toCircle right after.__init__():

importmathclassCircle:def__init__(self,radius):self.radius=radius@classmethoddeffrom_diameter(cls,diameter):returncls(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 ofdiameter. Then you instantiateCircle by callingcls with the radius that results from thediameter argument.

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

The call to thecls 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:

>>>fromcircleimportCircle>>>circle=Circle.from_diameter(84)>>>circleCircle(radius=42.0)>>>circle.area()5541.769440932395>>>circle.perimeter()263.89378290154264

The call to.from_diameter() onCircle 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 ofCircle 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 apolar point in a math-related application. You need a way to make your class more flexible so that you can construct new instances usingCartesian coordinates as well.

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

importmathclassPolarPoint:def__init__(self,distance,angle):self.distance=distanceself.angle=angle@classmethoddeffrom_cartesian(cls,x,y):distance=math.dist((0,0),(x,y))angle=math.degrees(math.atan2(y,x))returncls(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’sx andy Cartesian coordinates. Then the method calculates the requireddistance andangle to construct the correspondingPolarPoint object. Finally,.from_cartesian() returns a new instance of the class.

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

>>>frompointimportPolarPoint>>># 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 createPolarPoint 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 theCPython implementation rely on them.

You have several ways todefine dictionary instances in Python. You can use dictionary literals, which consist of key-value pairs in curly brackets ({}). You can also calldict() 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 aniterable of keys and an optionalvalue. Thevalue argument defaults toNone 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 fromallowed_animals. You set the initial inventory of each animal to0 by providing this value as the second argument to.fromkeys().

As you already learned,value defaults toNone, 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.

Othermappings in the standard library also have a constructor called.fromkeys(). This is the case withOrderedDict,defaultdict, andUserDict. For example, thesource code ofUserDict provides the following implementation of.fromkeys():

@classmethoddeffromkeys(cls,iterable,value=None):d=cls()forkeyiniterable:d[key]=valuereturnd

Here,.fromkeys() takes aniterable and avalue as arguments. The method creates a new dictionary by callingcls. Then it iterates over the keys initerable and sets each value tovalue, which defaults toNone, as usual. Finally, the method returns the newly created dictionary.

Creatingdatetime.date Objects

Thedatetime.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 constructdatetime.date objects using conceptually different arguments.

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

>>>fromdatetimeimportdate>>>fromtimeimporttime>>># 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 adate object from the current day’s date.

The rest of the examples show howdatetime.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’spathlib 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 outPython’s pathlib Module: Taming the File System.

The handiest tool inpathlib is itsPath 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 findPath.home(), which creates a path object from your home directory:

• Windows
• Linux + macOS

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

>>>frompathlibimportPath>>>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 handlingconfiguration 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:

fromfunctoolsimportsingledispatchmethodclassDemoClass:@singledispatchmethoddefgeneric_method(self,arg):print(f"Do something with argument of type:{type(arg).__name__}")@generic_method.registerdef_(self,arg:int):print("Implementation for an int argument...")@generic_method.register(str)def_(self,arg):print("Implementation for a str argument...")

InDemoClass, you first define a base method calledgeneric_method() and decorate it with@singledispatchmethod. Then you define two alternative implementations ofgeneric_method() and decorate them with@generic_method.register.

In this example, you name the alternative implementations using a singleunderscore (_) 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 asnon-public and prevent direct calls from your end users.

You can usetype 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:

>>>fromdemoimportDemoClass>>>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 theint 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 yourPerson 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 toPerson, you can use a helper class that handles all the information related to the birth date and age.

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

 1fromdatetimeimportdate 2fromfunctoolsimportsingledispatchmethod 3 4classBirthInfo: 5@singledispatchmethod 6def__init__(self,birth_date): 7raiseValueError(f"unsupported date format:{birth_date}") 8 9@__init__.register(date)10def_from_date(self,birth_date):11self.date=birth_date1213@__init__.register(str)14def_from_isoformat(self,birth_date):15self.date=date.fromisoformat(birth_date)1617@__init__.register(int)18@__init__.register(float)19def_from_timestamp(self,birth_date):20self.date=date.fromtimestamp(birth_date)2122defage(self):23returndate.today().year-self.date.year

Here’s a breakdown of how this code works:

• Line 1 importsdate fromdatetime so that you can later convert any input date to adate object.

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

• Line 4 definesBirthInfo as a regular Python class.

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

• Lines 9 to 11 register an implementation of.__init__() that processesdate objects directly.

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

• Lines 17 to 20 register an implementation that processes dates that come as Unix time in seconds since theepoch. This time, you register two instances of the overloaded method by stacking the.register decorator with theint andfloat types.

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

Now you can usecomposition in yourPerson class to take advantage of the newBirthInfo class. Go ahead and updatePerson with the following code:

# ...classPerson:def__init__(self,name,birth_date):self.name=nameself._birth_info=BirthInfo(birth_date)@propertydefage(self):returnself._birth_info.age()@propertydefbirth_date(self):returnself._birth_info.date

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

Then you defineage() as aproperty to provide a computed attribute that returns the person’s current approximate age. The final addition toPerson is thebirth_date() property, which returns the person’s birth date as adate object.

To try out yourPerson andBirthInfo classes, open an interactive session and run the following code:

>>>frompersonimportPerson>>>john=Person("John Doe",date(1998,5,15))>>>john.age24>>>john.birth_datedatetime.date(1998, 5, 15)>>>jane=Person("Jane Doe","2000-11-29")>>>jane.age22>>>jane.birth_datedatetime.date(2000, 11, 29)>>>linda=Person("Linda Smith",1011222000)>>>linda.age20>>>linda.birth_datedatetime.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 instantiatePerson using different date formats. The internal instance ofBirthDate automatically converts the input date into a date object. If you instantiatePerson with an unsupported date format, such as a dictionary, then you get aValueError.

Note thatBirthDate.__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 afterself. If you need to use multiple arguments for dispatching appropriate implementations, then check out some existing third-party libraries, such asmultipledispatch andmultimethod.