The Problems With Complex Conditional Code

The example above exhibits all the problems you’ll find in complex logical code. Complex logical code usesif/elif/else structures to change the behavior of an application. Usingif/elif/else conditional structures makes the code harder to read, harder to understand, and harder to maintain.

The code above might not seem hard to read or understand, but wait till you see the final code in this section!

Nevertheless, the code above is hard to maintain because it is doing too much. Thesingle responsibility principle states that amodule, a class, or even a method should have a single, well-defined responsibility. It should do just one thing and have only one reason to change.

The.serialize() method inSongSerializer will require changes for many different reasons. This increases the risk of introducing new defects or breaking existing functionality when changes are made. Let’s take a look at all the situations that will require modifications to the implementation:

• When a new format is introduced: The method will have to change to implement the serialization to that format.

• When theSong object changes: Adding or removing properties to theSong class will require the implementation to change in order to accommodate the new structure.

• When the string representation for a format changes (plainJSON vsJSON API): The.serialize() method will have to change if the desired string representation for a format changes because the representation is hard-coded in the.serialize() method implementation.

The ideal situation would be if any of those changes in requirements could be implemented without changing the.serialize() method. Let’s see how you can do that in the following sections.

Looking for a Common Interface

The first step when you see complex conditional code in an application is to identify the common goal of each of the execution paths (or logical paths).

Code that usesif/elif/else usually has a common goal that is implemented in different ways in each logical path. The code above converts asong object to itsstring representation using a different format in each logical path.

Based on the goal, you look for a common interface that can be used to replace each of the paths. The example above requires an interface that takes asong object and returns astring.

Once you have a common interface, you provide separate implementations for each logical path. In the example above, you will provide an implementation to serialize to JSON and another for XML.

Then, you provide a separate component that decides the concrete implementation to use based on the specifiedformat. This component evaluates the value offormat and returns the concrete implementation identified by its value.

In the following sections, you will learn how to make changes to existing code without changing the behavior. This is referred to asrefactoring the code.

Martin Fowler in his bookRefactoring: Improving the Design of Existing Code defines refactoring as “the process of changing a software system in such a way that does not alter the external behavior of the code yet improves its internal structure.” If you’d like to see refactoring in action, check out the Real Python Code ConversationRefactoring: Prepare Your Code to Get Help.

Let’s begin refactoring the code to achieve the desired structure that uses the Factory Method design pattern.

Refactoring Code Into the Desired Interface

The desired interface is an object or a function that takes aSong object and returns astring representation.

The first step is to refactor one of the logical paths into this interface. You do this by adding a new method._serialize_to_json() and moving the JSON serialization code to it. Then, you change the client to call it instead of having the implementation in the body of theif statement:

classSongSerializer:defserialize(self,song,format):ifformat=='JSON':returnself._serialize_to_json(song)# The rest of the code remains the samedef_serialize_to_json(self,song):payload={'id':song.song_id,'title':song.title,'artist':song.artist}returnjson.dumps(payload)

Once you make this change, you can verify that the behavior has not changed. Then, you do the same for the XML option by introducing a new method._serialize_to_xml(), moving the implementation to it, and modifying theelif path to call it.

The following example shows the refactored code:

classSongSerializer:defserialize(self,song,format):ifformat=='JSON':returnself._serialize_to_json(song)elifformat=='XML':returnself._serialize_to_xml(song)else:raiseValueError(format)def_serialize_to_json(self,song):payload={'id':song.song_id,'title':song.title,'artist':song.artist}returnjson.dumps(payload)def_serialize_to_xml(self,song):song_element=et.Element('song',attrib={'id':song.song_id})title=et.SubElement(song_element,'title')title.text=song.titleartist=et.SubElement(song_element,'artist')artist.text=song.artistreturnet.tostring(song_element,encoding='unicode')

The new version of the code is easier to read and understand, but it can still be improved with a basic implementation of Factory Method.

Basic Implementation of Factory Method

The central idea in Factory Method is to provide a separate component with the responsibility to decide which concrete implementation should be used based on some specified parameter. That parameter in our example is theformat.

To complete the implementation of Factory Method, you add a new method._get_serializer() that takes the desiredformat. This method evaluates the value offormat and returns the matching serialization function:

classSongSerializer:def_get_serializer(self,format):ifformat=='JSON':returnself._serialize_to_jsonelifformat=='XML':returnself._serialize_to_xmlelse:raiseValueError(format)

Now, you can change the.serialize() method ofSongSerializer to use._get_serializer() to complete the Factory Method implementation. The next example shows the complete code:

classSongSerializer:defserialize(self,song,format):serializer=self._get_serializer(format)returnserializer(song)def_get_serializer(self,format):ifformat=='JSON':returnself._serialize_to_jsonelifformat=='XML':returnself._serialize_to_xmlelse:raiseValueError(format)def_serialize_to_json(self,song):payload={'id':song.song_id,'title':song.title,'artist':song.artist}returnjson.dumps(payload)def_serialize_to_xml(self,song):song_element=et.Element('song',attrib={'id':song.song_id})title=et.SubElement(song_element,'title')title.text=song.titleartist=et.SubElement(song_element,'artist')artist.text=song.artistreturnet.tostring(song_element,encoding='unicode')

The final implementation shows the different components of Factory Method. The.serialize() method is the application code that depends on an interface to complete its task.

This is referred to as theclient component of the pattern. The interface defined is referred to as theproduct component. In our case, the product is a function that takes aSong and returns a string representation.

The._serialize_to_json() and._serialize_to_xml() methods are concrete implementations of the product. Finally, the._get_serializer() method is thecreator component. The creator decides which concrete implementation to use.

Because you started with some existing code, all the components of Factory Method are members of the same classSongSerializer.

Usually, this is not the case and, as you can see, none of the added methods use theself parameter. This is a good indication that they should not be methods of theSongSerializer class, and they can become external functions:

classSongSerializer:defserialize(self,song,format):serializer=get_serializer(format)returnserializer(song)defget_serializer(format):ifformat=='JSON':return_serialize_to_jsonelifformat=='XML':return_serialize_to_xmlelse:raiseValueError(format)def_serialize_to_json(song):payload={'id':song.song_id,'title':song.title,'artist':song.artist}returnjson.dumps(payload)def_serialize_to_xml(song):song_element=et.Element('song',attrib={'id':song.song_id})title=et.SubElement(song_element,'title')title.text=song.titleartist=et.SubElement(song_element,'artist')artist.text=song.artistreturnet.tostring(song_element,encoding='unicode')

The mechanics of Factory Method are always the same. A client (SongSerializer.serialize()) depends on a concrete implementation of an interface. It requests the implementation from a creator component (get_serializer()) using some sort of identifier (format).

The creator returns the concrete implementation according to the value of the parameter to the client, and the client uses the provided object to complete its task.

You can execute the same set of instructions in the Python interactive interpreter to verify that the application behavior has not changed:

>>>importserializer_demoassd>>>song=sd.Song('1','Water of Love','Dire Straits')>>>serializer=sd.SongSerializer()>>>serializer.serialize(song,'JSON')'{"id": "1", "title": "Water of Love", "artist": "Dire Straits"}'>>>serializer.serialize(song,'XML')'<song id="1"><title>Water of Love</title><artist>Dire Straits</artist></song>'>>>serializer.serialize(song,'YAML')Traceback (most recent call last):  File"<stdin>", line1, in<module>  File"./serializer_demo.py", line13, inserializeserializer=get_serializer(format)  File"./serializer_demo.py", line23, inget_serializerraiseValueError(format)ValueError:YAML

You create asong and aserializer, and use theserializer to convert the song to itsstring representation specifying aformat. SinceYAML is not a supported format,ValueError is raised.

An Object Serialization Example

The basic requirements for the example above are that you want to serializeSong objects into theirstring representation. It seems the application provides features related to music, so it is plausible that the application will need to serialize other type of objects likePlaylist orAlbum.

Ideally, the design should support adding serialization for new objects by implementing new classes without requiring changes to the existing implementation. The application requires objects to be serialized to multiple formats like JSON and XML, so it seems natural to define an interfaceSerializer that can have multiple implementations, one per format.

The interface implementation might look something like this:

# In serializers.pyimportjsonimportxml.etree.ElementTreeasetclassJsonSerializer:def__init__(self):self._current_object=Nonedefstart_object(self,object_name,object_id):self._current_object={'id':object_id}defadd_property(self,name,value):self._current_object[name]=valuedefto_str(self):returnjson.dumps(self._current_object)classXmlSerializer:def__init__(self):self._element=Nonedefstart_object(self,object_name,object_id):self._element=et.Element(object_name,attrib={'id':object_id})defadd_property(self,name,value):prop=et.SubElement(self._element,name)prop.text=valuedefto_str(self):returnet.tostring(self._element,encoding='unicode')

TheSerializer interface is an abstract concept due to the dynamic nature of thePython language. Static languages likeJava or C# require that interfaces be explicitly defined. In Python, any object that provides the desired methods or functions is said to implement the interface. The example defines theSerializer interface to be an object that implements the following methods or functions:

• .start_object(object_name, object_id)
• .add_property(name, value)
• .to_str()

This interface is implemented by the concrete classesJsonSerializer andXmlSerializer.

The original example used aSongSerializer class. For the new application, you will implement something more generic, likeObjectSerializer:

# In serializers.pyclassObjectSerializer:defserialize(self,serializable,format):serializer=factory.get_serializer(format)serializable.serialize(serializer)returnserializer.to_str()

The implementation ofObjectSerializer is completely generic, and it only mentions aserializable and aformat as parameters.

Theformat is used to identify the concrete implementation of theSerializer and is resolved by thefactory object. Theserializable parameter refers to another abstract interface that should be implemented on any object type you want to serialize.

Let’s take a look at a concrete implementation of theserializable interface in theSong class:

# In songs.pyclassSong:def__init__(self,song_id,title,artist):self.song_id=song_idself.title=titleself.artist=artistdefserialize(self,serializer):serializer.start_object('song',self.song_id)serializer.add_property('title',self.title)serializer.add_property('artist',self.artist)

TheSong class implements theSerializable interface by providing a.serialize(serializer) method. In the method, theSong class uses theserializer object to write its own information without any knowledge of the format.

As a matter of fact, theSong class doesn’t even know the goal is to convert the data to a string. This is important because you could use this interface to provide a different kind ofserializer that converts theSong information to a completely different representation if needed. For example, your application might require in the future to convert theSong object to a binary format.

So far, we’ve seen the implementation of the client (ObjectSerializer) and the product (serializer). It is time to complete the implementation of Factory Method and provide the creator. The creator in the example is thevariablefactory inObjectSerializer.serialize().

Factory Method as an Object Factory

In the original example, you implemented the creator as a function. Functions are fine for very simple examples, but they don’t provide too much flexibility when requirements change.

Classes can provide additional interfaces to add functionality, and they can be derived to customize behavior. Unless you have a very basic creator that will never change in the future, you want to implement it as a class and not a function. These type of classes are called object factories.

You can see the basic interface ofSerializerFactory in the implementation ofObjectSerializer.serialize(). The method usesfactory.get_serializer(format) to retrieve theserializer from the object factory.

You will now implementSerializerFactory to meet this interface:

# In serializers.pyclassSerializerFactory:defget_serializer(self,format):ifformat=='JSON':returnJsonSerializer()elifformat=='XML':returnXmlSerializer()else:raiseValueError(format)factory=SerializerFactory()

The current implementation of.get_serializer() is the same you used in the original example. The method evaluates the value offormat and decides the concrete implementation to create and return. It is a relatively simple solution that allows us to verify the functionality of all the Factory Method components.

Let’s go to the Python interactive interpreter and see how it works:

>>>importsongs>>>importserializers>>>song=songs.Song('1','Water of Love','Dire Straits')>>>serializer=serializers.ObjectSerializer()>>>serializer.serialize(song,'JSON')'{"id": "1", "title": "Water of Love", "artist": "Dire Straits"}'>>>serializer.serialize(song,'XML')'<song id="1"><title>Water of Love</title><artist>Dire Straits</artist></song>'>>>serializer.serialize(song,'YAML')Traceback (most recent call last):  File"<stdin>", line1, in<module>  File"./serializers.py", line39, inserializeserializer=factory.get_serializer(format)  File"./serializers.py", line52, inget_serializerraiseValueError(format)ValueError:YAML

The new design of Factory Method allows the application to introduce new features by adding new classes, as opposed to changing existing ones. You can serialize other objects by implementing theSerializable interface on them. You can support new formats by implementing theSerializer interface in another class.

The missing piece is thatSerializerFactory has to change to include the support for new formats. This problem is easily solved with the new design becauseSerializerFactory is a class.

Supporting Additional Formats

The current implementation ofSerializerFactory needs to be changed when a new format is introduced. Your application might never need to support any additional formats, but you never know.

You want your designs to be flexible, and as you will see, supporting additional formats without changingSerializerFactory is relatively easy.

The idea is to provide a method inSerializerFactory that registers a newSerializer implementation for the format we want to support:

# In serializers.pyclassSerializerFactory:def__init__(self):self._creators={}defregister_format(self,format,creator):self._creators[format]=creatordefget_serializer(self,format):creator=self._creators.get(format)ifnotcreator:raiseValueError(format)returncreator()factory=SerializerFactory()factory.register_format('JSON',JsonSerializer)factory.register_format('XML',XmlSerializer)

The.register_format(format, creator) method allows registering new formats by specifying aformat value used to identify the format and acreator object. The creator object happens to be the class name of the concreteSerializer. This is possible because all theSerializer classes provide a default.__init__() to initialize the instances.

The registration information is stored in the_creatorsdictionary. The.get_serializer() method retrieves the registered creator and creates the desired object. If the requestedformat has not been registered, thenValueError is raised.

You can now verify the flexibility of the design by implementing aYamlSerializer and get rid of the annoyingValueError you saw earlier:

# In yaml_serializer.pyimportyamlimportserializersclassYamlSerializer(serializers.JsonSerializer):defto_str(self):returnyaml.dump(self._current_object)serializers.factory.register_format('YAML',YamlSerializer)

JSON and YAML are very similar formats, so you can reuse most of the implementation ofJsonSerializer and overwrite.to_str() to complete the implementation. The format is then registered with thefactory object to make it available.

Let’s use the Python interactive interpreter to see the results:

>>>importserializers>>>importsongs>>>importyaml_serializer>>>song=songs.Song('1','Water of Love','Dire Straits')>>>serializer=serializers.ObjectSerializer()>>>print(serializer.serialize(song,'JSON')){"id": "1", "title": "Water of Love", "artist": "Dire Straits"}>>>print(serializer.serialize(song,'XML'))<song id="1"><title>Water of Love</title><artist>Dire Straits</artist></song>>>>print(serializer.serialize(song,'YAML')){artist: Dire Straits, id: '1', title: Water of Love}

By implementing Factory Method using an Object Factory and providing a registration interface, you are able to support new formats without changing any of the existing application code. This minimizes the risk of breaking existing features or introducing subtle bugs.

Not All Objects Can Be Created Equal

The biggest challenge to implement a general purpose Object Factory is that not all objects are created in the same way.

Not all situations allow us to use a default.__init__() to create and initialize the objects. It is important that the creator, in this case the Object Factory, returns fully initialized objects.

This is important because if it doesn’t, then the client will have to complete the initialization and use complex conditional code to fully initialize the provided objects. This defeats the purpose of the Factory Method design pattern.

To understand the complexities of a general purpose solution, let’s take a look at a different problem. Let’s say an application wants to integrate with different music services. These services can be external to the application or internal in order to support a local music collection. Each of the services has a different set of requirements.

Imagine that the application wants to integrate with a service provided by Spotify. This service requires an authorization process where a client key and secret are provided for authorization.

The service returns an access code that should be used on any further communication. This authorization process is very slow, and it should only be performed once, so the application wants to keep the initialized service object around and use it every time it needs to communicate with Spotify.

At the same time, other users want to integrate with Pandora. Pandora might use a completely different authorization process. It also requires a client key and secret, but it returns a consumer key and secret that should be used for other communications. As with Spotify, the authorization process is slow, and it should only be performed once.

Finally, the application implements the concept of a local music service where the music collection is stored locally. The service requires that the the location of the music collection in the local system be specified. Creating a new service instance is done very quickly, so a new instance can be created every time the user wants to access the music collection.

This example presents several challenges. Each service is initialized with a different set of parameters. Also, Spotify and Pandora require an authorization process before the service instance can be created.

They also want to reuse that instance to avoid authorizing the application multiple times. The local service is simpler, but it doesn’t match the initialization interface of the others.

In the following sections, you will solve this problems by generalizing the creation interface and implementing a general purpose Object Factory.

Separate Object Creation to Provide Common Interface

The creation of each concrete music service has its own set of requirements. This means a common initialization interface for each service implementation is not possible or recommended.

The best approach is to define a new type of object that provides a general interface and is responsible for the creation of a concrete service. This new type of object will be called aBuilder. TheBuilder object has all the logic to create and initialize a service instance. You will implement aBuilder object for each of the supported services.

Let’s start by looking at the application configuration:

# In program.pyconfig={'spotify_client_key':'THE_SPOTIFY_CLIENT_KEY','spotify_client_secret':'THE_SPOTIFY_CLIENT_SECRET','pandora_client_key':'THE_PANDORA_CLIENT_KEY','pandora_client_secret':'THE_PANDORA_CLIENT_SECRET','local_music_location':'/usr/data/music'}

Theconfig dictionary contains all the values required to initialize each of the services. The next step is to define an interface that will use those values to create a concrete implementation of a music service. That interface will be implemented in aBuilder.

Let’s look at the implementation of theSpotifyService andSpotifyServiceBuilder:

# In music.pyclassSpotifyService:def__init__(self,access_code):self._access_code=access_codedeftest_connection(self):print(f'Accessing Spotify with{self._access_code}')classSpotifyServiceBuilder:def__init__(self):self._instance=Nonedef__call__(self,spotify_client_key,spotify_client_secret,**_ignored):ifnotself._instance:access_code=self.authorize(spotify_client_key,spotify_client_secret)self._instance=SpotifyService(access_code)returnself._instancedefauthorize(self,key,secret):return'SPOTIFY_ACCESS_CODE'

The example shows aSpotifyServiceBuilder that implements.__call__(spotify_client_key, spotify_client_secret, **_ignored).

This method is used to create and initialize the concreteSpotifyService. It specifies the required parameters and ignores any additional parameters provided through**_ignored. Once theaccess_code is retrieved, it creates and returns theSpotifyService instance.

Notice thatSpotifyServiceBuilder keeps the service instance around and only creates a new one the first time the service is requested. This avoids going through the authorization process multiple times as specified in the requirements.

Let’s do the same for Pandora:

# In music.pyclassPandoraService:def__init__(self,consumer_key,consumer_secret):self._key=consumer_keyself._secret=consumer_secretdeftest_connection(self):print(f'Accessing Pandora with{self._key} and{self._secret}')classPandoraServiceBuilder:def__init__(self):self._instance=Nonedef__call__(self,pandora_client_key,pandora_client_secret,**_ignored):ifnotself._instance:consumer_key,consumer_secret=self.authorize(pandora_client_key,pandora_client_secret)self._instance=PandoraService(consumer_key,consumer_secret)returnself._instancedefauthorize(self,key,secret):return'PANDORA_CONSUMER_KEY','PANDORA_CONSUMER_SECRET'

ThePandoraServiceBuilder implements the same interface, but it uses different parameters and processes to create and initialize thePandoraService. It also keeps the service instance around, so the authorization only happens once.

Finally, let’s take a look at the local service implementation:

# In music.pyclassLocalService:def__init__(self,location):self._location=locationdeftest_connection(self):print(f'Accessing Local music at{self._location}')defcreate_local_music_service(local_music_location,**_ignored):returnLocalService(local_music_location)

TheLocalService just requires a location where the collection is stored to initialize theLocalService.

A new instance is created every time the service is requested because there is no slow authorization process. The requirements are simpler, so you don’t need aBuilder class. Instead, a function returning an initializedLocalService is used. This function matches the interface of the.__call__() methods implemented in the builder classes.

A Generic Interface to Object Factory

A general purpose Object Factory (ObjectFactory) can leverage the genericBuilder interface to create all kinds of objects. It provides a method to register aBuilder based on akey value and a method to create the concrete object instances based on thekey.

Let’s look at the implementation of our genericObjectFactory:

# In object_factory.pyclassObjectFactory:def__init__(self):self._builders={}defregister_builder(self,key,builder):self._builders[key]=builderdefcreate(self,key,**kwargs):builder=self._builders.get(key)ifnotbuilder:raiseValueError(key)returnbuilder(**kwargs)

The implementation structure ofObjectFactory is the same you saw inSerializerFactory.

The difference is in the interface that exposes to support creating any type of object. The builder parameter can be any object that implements thecallable interface. This means aBuilder can be a function, a class, or an object that implements.__call__().

The.create() method requires that additional arguments are specified as keyword arguments. This allows theBuilder objects to specify the parameters they need and ignore the rest in no particular order. For example, you can see thatcreate_local_music_service() specifies alocal_music_location parameter and ignores the rest.

Let’s create the factory instance and register the builders for the services you want to support:

# In music.pyimportobject_factory# Omitting other implementation classes shown abovefactory=object_factory.ObjectFactory()factory.register_builder('SPOTIFY',SpotifyServiceBuilder())factory.register_builder('PANDORA',PandoraServiceBuilder())factory.register_builder('LOCAL',create_local_music_service)

Themusic module exposes theObjectFactory instance through thefactory attribute. Then, the builders are registered with the instance. For Spotify and Pandora, you register an instance of their corresponding builder, but for the local service, you just pass the function.

Let’s write a small program that demonstrates the functionality:

# In program.pyimportmusicconfig={'spotify_client_key':'THE_SPOTIFY_CLIENT_KEY','spotify_client_secret':'THE_SPOTIFY_CLIENT_SECRET','pandora_client_key':'THE_PANDORA_CLIENT_KEY','pandora_client_secret':'THE_PANDORA_CLIENT_SECRET','local_music_location':'/usr/data/music'}pandora=music.factory.create('PANDORA',**config)pandora.test_connection()spotify=music.factory.create('SPOTIFY',**config)spotify.test_connection()local=music.factory.create('LOCAL',**config)local.test_connection()pandora2=music.services.get('PANDORA',**config)print(f'id(pandora) == id(pandora2):{id(pandora)==id(pandora2)}')spotify2=music.services.get('SPOTIFY',**config)print(f'id(spotify) == id(spotify2):{id(spotify)==id(spotify2)}')

The application defines aconfig dictionary representing the application configuration. The configuration is used as the keyword arguments to the factory regardless of the service you want to access. The factory creates the concrete implementation of the music service based on the specifiedkey parameter.

You can now run our program to see how it works:

$pythonprogram.pyAccessing Pandora with PANDORA_CONSUMER_KEY and PANDORA_CONSUMER_SECRETAccessing Spotify with SPOTIFY_ACCESS_CODEAccessing Local music at /usr/data/musicid(pandora) == id(pandora2): Trueid(spotify) == id(spotify2): True

You can see that the correct instance is created depending on the specified service type. You can also see that requesting the Pandora or Spotify service always returns the same instance.