Factory Method Pattern

Introducing Factory Method

The Problems With Complex Conditional Code
Looking for a Common Interface
Refactoring Code Into the Desired Interface
Basic Implementation of Factory Method

factory pattern separates creating the object from its interface implementation
convert a Song object into its string representation

# In serializer_demo.py

import json
import xml.etree.ElementTree as et

class Song:
    def __init__(self, song_id, title, artist):
        self.song_id = song_id
        self.title = title
        self.artist = artist


class SongSerializer:
    def serialize(self, song, format):
        if format == 'JSON':
            song_info = {
                'id': song.song_id,
                'title': song.title,
                'artist': song.artist
            }
            return json.dumps(song_info)
        elif format == 'XML':
            song_info = et.Element('song', attrib={'id': song.song_id})
            title = et.SubElement(song_info, 'title')
            title.text = song.title
            artist = et.SubElement(song_info, 'artist')
            artist.text = song.artist
            return et.tostring(song_info, encoding='unicode')
        else:
            raise ValueError(format)

from REPL

>>>: import serializer_demo as sd
>>>: 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 "", line 1, in 
  File "./serializer_demo.py", line 30, in serialize
    raise ValueError(format)
ValueError: YAML

The Problems With Complex Conditional Code

the SongSerializer shown above violates the single responsibilty principle
the .serialize() faces possible/probable future issues

when a new format is introduced the method will have to change to implement the serialization to that format
when the Song object changes by adding or removing properties the implementation will have to change in order to accommodate the new structure
when the string representation for a format changes (plain JSON vs JSON API)

Looking for a Common Interface

the common interface is a function which takes a Song object and returns a string
provide separate implementations for each logical path
provide a separate component that decides the concrete implementation to use based on the specified format
component evaluates the value of format and returns the concrete implementation identified by its value

Refactoring Code Into the Desired Interface

first step is to refactor logical paths

class SongSerializer:
    def serialize(self, song, format):
        if format == 'JSON':
            return self._serialize_to_json(song)
        elif format == 'XML':
            return self._serialize_to_xml(song)
        else:
            raise ValueError(format)

    def _serialize_to_json(self, song):
        payload = {
            'id': song.song_id,
            'title': song.title,
            'artist': song.artist
        }
        return json.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.title
        artist = et.SubElement(song_element, 'artist')
        artist.text = song.artist
        return et.tostring(song_element, encoding='unicode')

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
the .serialize method still contains the if-else complexity
wrapper that complexity into a separate function

class SongSerializer:
    def serialize(self, song, format):
        serializer = self._get_serializer(format)
        return serializer(song)

    def _get_serializer(self, format):
        if format == 'JSON':
            return self._serialize_to_json
        elif format == 'XML':
            return self._serialize_to_xml
        else:
            raise ValueError(format)

    def _serialize_to_json(self, song):
        payload = {
            'id': song.song_id,
            'title': song.title,
            'artist': song.artist
        }
        return json.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.title
        artist = et.SubElement(song_element, 'artist')
        artist.text = song.artist
        return et.tostring(song_element, encoding='unicode')

the .serialize() method is the client component of the factory pattern
the interface is referred to as the product component
product is a function which takes a Song and returns a string
the .get_serializer(), ._serialize_to_xml() and ._serialize_to_json() methods are concrete implementations of the product
neither method uses the self argument in its implementation so there is no need for them to be class methods
The .serialize() method retains it self argument because it is part of the factory pattern product
with a touch more refactoring

class SongSerializer:
    def serialize(self, song, format):
        serializer = get_serializer(format)
        return serializer(song)

def get_serializer(format):
    if format == 'JSON':
        return _serialize_to_json
    elif format == 'XML':
        return _serialize_to_xml
    else:
        raise ValueError(format)


def _serialize_to_json(song):
    payload = {
        'id': song.song_id,
        'title': song.title,
        'artist': song.artist
    }
    return json.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.title
    artist = et.SubElement(song_element, 'artist')
    artist.text = song.artist
    return et.tostring(song_element, encoding='unicode')

usage

>>> import serializer_demo as sd
>>> 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>", line 1, in <module>
  File "./serializer_demo.py", line 13, in serialize
    serializer = get_serializer(format)
  File "./serializer_demo.py", line 23, in get_serializer
    raise ValueError(format)
ValueError: YAML

Recognizing Opportunities to Use Factory Method

An Object Serialization Example
Factory Method as an Object Factory
Supporting Additional Formats

when a client depends on an interface and there are multiple concrete implementations the factory pattern should be used
need to provide a parameter to identify the concrete implementation
use it in the creator to decide the concrete implementation

use case examples

Replacing complex logical code - complex logical structures in the format if/elif/else are hard to maintain
new logical paths are needed as requirements change
an put the body of each logical path into separate functions or classes with a common interface
Constructing related objects from external data - different types of employees
client passes a parameter identifying the type of concrete employee to produce
Supporting multiple implementations of the same feature - multiple algorithms with different levels of accuracy to perform a transformation
client passes a parameter identifying the type of concrete algorithm to produce
Combining similar features under a common interface - filters for image processing
client passes a parameter identifying the type of concrete filter to produce
Integrating related external services - define a common interface for a service type
use Factory Method to create the correct integration based on a user preference.

essentially the factory pattern hides the ugliness

An Object Serialization Example

design should support adding serialization for new objects by implementing new classes without requiring changes to the existing implementation
objectifying the serializers

# In serializers.py

import json
import xml.etree.ElementTree as et

class JsonSerializer:
    def __init__(self):
        self._current_object = None

    def start_object(self, object_name, object_id):
        self._current_object = {
            'id': object_id
        }

    def add_property(self, name, value):
        self._current_object[name] = value

    def to_str(self):
        return json.dumps(self._current_object)


class XmlSerializer:
    def __init__(self):
        self._element = None

    def start_object(self, object_name, object_id):
        self._element = et.Element(object_name, attrib={'id': object_id})

    def add_property(self, name, value):
        prop = et.SubElement(self._element, name)
        prop.text = value

    def to_str(self):
        return et.tostring(self._element, encoding='unicode')

Serializer interface is an object which implements

start_object(object_name, object_id)
add_property(self, name, value)
to_str()

replace the SongSerializer type with generic serializer type

class ObjectSerializer:
    def serialize(self, serializable, format):
        serializer = factory.get_serializer(format)
        serializable.serialize(serializer)
        return serializer.to_str()

implementation of ObjectSerializer is completely generic
only mentions a serializable and a format as parameters
a concrete implementation of the serializable interface in the Song class

# In songs.py

class Song:
    def __init__(self, song_id, title, artist):
        self.song_id = song_id
        self.title = title
        self.artist = artist

    def serialize(self, serializer):
        serializer.start_object('song', self.song_id)
        serializer.add_property('title', self.title)
        serializer.add_property('artist', self.artist)

the Song class is unaware of what the serializer will do with the data serialize() provides
if the serializer has a to_str() the client could get the string by calling

serialized_song = serializer.to_str()

Factory Method as an Object Factory

above a factory method is used as a simple example
a factory class can provide more functionality and be customized by subclasses
interface for SerializerFactory

# In serializers.py

class SerializerFactory:
    def get_serializer(self, format):
        if format == 'JSON':
            return JsonSerializer()
        elif format == 'XML':
            return XmlSerializer()
        else:
            raise ValueError(format)

factory = SerializerFactory()

Supporting Additional Formats

the SerializerFactory class above will have to change as additional formats are added
the object factory class needs to 'know' about the available formats before it can be used

a better design would add a new format and serializer without changing the class itself

# In serializers.py

class SerializerFactory:

    def __init__(self):
        self._creators = {}

    def register_format(self, format, creator):
        self._creators[format] = creator

    def get_serializer(self, format):
        creator = self._creators.get(format)
        if not creator:
            raise ValueError(format)
        return creator()


factory = SerializerFactory()
factory.register_format('JSON', JsonSerializer)
factory.register_format('XML', XmlSerializer)

adding a new format and serializer

# In yaml_serializer.py

import yaml
import serializers

class YamlSerializer(serializers.JsonSerializer):
    def to_str(self):
        return yaml.dump(self._current_object)


serializers.factory.register_format('YAML', YamlSerializer)

the registration interface/pattern supports new formats without changing existing code

A General Purpose Object Factory

Not All Objects Can Be Created Equal
Separate Object Creation to Provide Common Interface
A Generic Interface to Object Factory

an Object Factory gives additional flexibility to the design when requirements change
want an implementation of Object Factory that can be reused in any situation without replicating the implementation

Not All Objects Can Be Created Equal

not all objects are created in the same way
not all situations allow using a default .__init__() to create and initialize the objects
the Object Factory must return fully initialized objects

consider a factory which returns clients for remote services
each service has different authentication requirements
app wants to connect to different music services

Service	Requirements
Spotify	service requires an authorization process where a client key and secret are provided for authorization service returns an access code that should be used on any further communication authorization process can be slow should only be done once
Pandora	requires a client key and secret returns a consumer key and secret to be used for other communications authorization process can be slow should only be done once
local music service	music collection is stored locally 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 new instance can be created every time

Separate Object Creation to Provide Common Interface

the application configuration

# In program.py

config = {
    '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'
}

the implementation of the SpotifyService and SpotifyServiceBuilder

# In music.py

class SpotifyService:
    def __init__(self, access_code):
        self._access_code = access_code

    def test_connection(self):
        print(f'Accessing Spotify with {self._access_code}')


class SpotifyServiceBuilder:
    def __init__(self):
        self._instance = None

    def __call__(self, spotify_client_key, spotify_client_secret, **_ignored):
        if not self._instance:
            access_code = self.authorize(
                spotify_client_key, spotify_client_secret)
            self._instance = SpotifyService(access_code)
        return self._instance

    def authorize(self, key, secret):
        return 'SPOTIFY_ACCESS_CODE'

the implementation of the PandoraService and PandoraServiceBuilder

# In music.py

class PandoraService:
    def __init__(self, consumer_key, consumer_secret):
        self._key = consumer_key
        self._secret = consumer_secret

    def test_connection(self):
        print(f'Accessing Pandora with {self._key} and {self._secret}')


class PandoraServiceBuilder:
    def __init__(self):
        self._instance = None

    def __call__(self, pandora_client_key, pandora_client_secret, **_ignored):
        if not self._instance:
            consumer_key, consumer_secret = self.authorize(
                pandora_client_key, pandora_client_secret)
            self._instance = PandoraService(consumer_key, consumer_secret)
        return self._instance

    def authorize(self, key, secret):
        return 'PANDORA_CONSUMER_KEY', 'PANDORA_CONSUMER_SECRET'

the local service implementation

# In music.py

class LocalService:
    def __init__(self, location):
        self._location = location

    def test_connection(self):
        print(f'Accessing Local music at {self._location}')


def create_local_music_service(local_music_location, **_ignored):
    return LocalService(local_music_location)

A Generic Interface to Object Factory

the generic object factory

# In object_factory.py

class ObjectFactory:
    def __init__(self):
        self._builders = {}

    def register_builder(self, key, builder):
        self._builders[key] = builder

    def create(self, key, **kwargs):
        builder = self._builders.get(key)
        if not builder:
            raise ValueError(key)
        return builder(**kwargs)

create the factory instance and register services

# In music.py
import object_factory

# Omitting other implementation classes shown above

factory = object_factory.ObjectFactory()
factory.register_builder('SPOTIFY', SpotifyServiceBuilder())
factory.register_builder('PANDORA', PandoraServiceBuilder())
factory.register_builder('LOCAL', create_local_music_service)

mule

# In program.py
import music

config = {
    '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)}')

output of program.py

$ python program.py
Accessing Pandora with PANDORA_CONSUMER_KEY and PANDORA_CONSUMER_SECRET
Accessing Spotify with SPOTIFY_ACCESS_CODE
Accessing Local music at /usr/data/music
id(pandora) == id(pandora2): True
id(spotify) == id(spotify2): True

Specializing the Object Factory to Improve Code Readability

it seems awkward to call music.factory.create() to create a music service
push the ugliness down a layer
provide an explicit interface to the context of the application

# In music.py

class MusicServiceProvider(object_factory.ObjectFactory):
    def get(self, service_id, **kwargs):
        return self.create(service_id, **kwargs)


services = MusicServiceProvider()
services.register_builder('SPOTIFY', SpotifyServiceBuilder())
services.register_builder('PANDORA', PandoraServiceBuilder())
services.register_builder('LOCAL', create_local_music_service)

mule

import music

config = {
    '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.services.get('PANDORA', **config)
pandora.test_connection()
spotify = music.services.get('SPOTIFY', **config)
spotify.test_connection()
local = music.services.get('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)}')

mule output

$ python program.py
Accessing Pandora with PANDORA_CONSUMER_KEY and PANDORA_CONSUMER_SECRET
Accessing Spotify with SPOTIFY_ACCESS_CODE
Accessing Local music at /usr/data/music
id(pandora) == id(pandora2): True
id(spotify) == id(spotify2): True