Understanding Why You Should Do This

You may be asking why a class factory is even valuable in this case. After all, there are only three possibilities. These classes could just be hard-coded, rather than dynamically created on the fly. That said, it is easy to extrapolate a case from this example where a hard-coded class is no longer tenable.

After all, there are lots of websites with a non-trivial number of authentication paradigms. For example, some use custom usernames, while others use an e-mail address. For development services, you are likely to have an API key and potentially one or more secret tokens.

There is really no way to programmatically determine what credentials a website requires (at least not reliably), but consider a service that did try to represent credentials from lots of different, supported third-party sites. That service would likely store the required keys and types of values in a database.

Now, suddenly, you have a class with attributes generated based on a database lookup. This is important because database lookups happen at runtime, not at coding time. Now, suddenly, you have a functionally infinite number of possibilities for how the expected_keys attribute of the classes might need to be written, and it is no longer feasible to code them all up front.

Storing that kind of data in the database also means that, as the data changes, the code need not do so. A website may alter or augment what kind of credentials it supports, and this would require adding or removing rows from the database, but the Credential class would still be up to the task.

Attribute Dictionaries

Just because some attributes are only known at execution time does not always mean that a class factory is the correct approach. Often, attributes can be written to the class on the fly, or a class can simply store a dictionary with an arbitrary set of attributes.

If this is a sufficient solution, it is likely an easier and more straightforward one.

class MyClass(object):
    attrs = {}

The most common case where attribute dictionaries are most likely to fall short is in a situation where you are subclassing an existing class over which you do not have direct control, and you require the class's existing functionality to work against the modified attributes. You will see a subclassing example shortly.

Fleshing Out the Credential Class

Consider a credentials database with a single table, and that table has two columns: a service name (such as Apple or Amazon), and a credential key (such as username).

This mock database is obviously still far too simple to cover all use cases. In this example, support for alternative modes of login (such as OpenID) has been dropped. Also, the example does not have any concept for presenting credentials in a specific order (username before password, for example). All of this is fine; it is sufficient for a proof of concept.

Now, consider a class factory that reads from this database (which will simply be stored as a CSV flat file) and returns an appropriate class.

import csv


def get_credential_class(service):
    """Return a class representing a credential for the given service,
    with an attribute representing the expected keys.
    """
    # Open our "database".
    keys = []
    with open('creds.csv', 'r') as csvfile:
        for row in csv.reader(csvfile):
            # If this row does not correspond to the service we
            # are actually asking for (e.g., if it is a row for
            # Apple and we are asking for an Amazon credential class),
            # skip it.
            if row[0].lower() != service.lower():
                continue

            # Add the key to the list of expected keys.
            keys.append(row[1])

    # Return a class with a proper __init__ method which expects
    # all expected keys.
    class Credential(object):
        expected_keys = keys

        def __init__(self, **kwargs):
            # Sanity check: Do our keys match?
            if set(self.expected_keys) != set([i for i in kwargs.keys()]):
                raise ValueError('Keys do not match.')

            # Write the keys to the credential object.
            for k, v in kwargs.items():
                setattr(self, k, v)

    return Credential

The inputs for the get_credential_class function have now been entirely replaced. Instead of describing the type of credential, you simply specify whom the credential is for.

For example, a sample CSV “database” might look like this:

Amazon,username
Amazon,password
Apple,email_address
Apple,password
GitHub,username
GitHub,password
GitHub,auth_token

The value that get_credential_class takes is a string, and it corresponds to the first column in the CSV file. Therefore, calling get_credential_class('GitHub') will return a class with expected keys of username, password, and auth_token. The lines in the CSV file corresponding to Apple and Amazon will be skipped.

The Form Example

One place where you can see this concept at work is in the forms API of a popular web framework, Django. This framework includes an abstract class, django.forms.Form, which is used to create HTML forms.

Django forms have a custom metaclass that takes the attributes declared on the form and erects a distinction between form fields and form data. Creating a credential form in this API is very easy if you know what your fields are.

from django import forms


class CredentialForm(forms.Form):
    username = forms.CharField()
    password = forms.CharField(widget=forms.PasswordInput)

On the other hand, if you do not know what your fields are (as in the case of the previous example), this is a more complicated task. A class factory becomes the perfect approach.

import csv

from django import forms


def get_credential_form_class(service):
    """Return a class representing a credential for the given service,
    with attributes representing the expected keys.
    """
    # Open our "database".
    keys = []
    with open('creds.csv', 'r') as csvfile:
        for row in csv.reader(csvfile):
            # If this row does not correspond to the service we
            # are actually asking for (e.g. if it is a row for
            # Apple and we are asking for an Amazon credential class),
            # skip it.
            if row[0].lower() != service.lower():
                continue

            # Add the key to the list of expected keys.
            keys.append(row[1])

    # Put together the appropriate credential fields.
    attrs = {}
    for key in keys:
        field_kw = {}
        if 'password' in key:
            field_kw['widget'] = forms.PasswordInput
        attrs[key] = forms.CharField(**field_kw)

    # Return a form class with the appropriate credential fields.
    metaclass = type(forms.Form)
    return metaclass('CredentialForm', (forms.Form,), attrs)

In this case, you have substituted your custom Credential class for a Django form subclass. It is no longer the case that you are just setting an expected_keys attribute. Rather, you are setting one attribute for each expected key. The previous code puts these together in a dictionary (doing a blatant hand-wave for passwords and PasswordInput), and then creates a new form subclass and returns it.

It is worth calling out explicitly that Django's Form class uses a custom metaclass, which subclasses type. Therefore, it is important that you call its constructor, rather than type directly. You do this on the last two lines by asking forms.Form for its metaclass, and then using that constructor directly.

It is also worth noting that this is a case where it really is necessary to use the metaclass constructor, rather than creating the class using the class keyword. You are not able to create the class using the class keyword here because, even within a function, you would have to create the class and then write the attributes to the class, and the metaclass behavior will not be applied to the attributes assigned to the class after it is built. (Chapter 5 covers this in more detail.)

Class Attributes Versus Instance Attributes

The following two code blocks do not produce equivalent classes or instances:

##########################
###  CLASS ATTRIBUTE   ###
##########################

class C(object):
    foo = 'bar'


##########################
### INSTANCE ATTRIBUTE ###
##########################

class I(object):
    def __init__(self):
        self.foo = 'bar'

The first and most obvious thing that is different about these classes is where the foo attribute can be accessed. It is not particularly surprising that C.foo is a string, and I.foo raises AttributeError.

>>> C.foo
'bar'
>>> I.foo
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: type object 'I' has no attribute 'foo'

After all, foo was instantiated as an attribute on C, but not on I. Since I is being accessed directly, rather than by way of an instance, the __init__ function has not even run yet. Even if an instance of I had been created, the instance would have the foo attribute while the class would not.

>>> i = I()
>>> i.foo
'bar'
>>> I.foo
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: type object 'I' has no attribute 'foo'

There is, however, a lesser-noticed difference between C and I, which involves what happens if the foo attribute is modified against one of their instances.

Consider the following two instantiated C instances:

>>> c1 = C()
>>> c2 = C()

Now, say you modify the foo attribute on one of them, as shown here:

>>> c1.foo = 'baz'

You see that the c2 instance still uses the attribute of the class, while c1 has its own.

>>> c1.foo
'baz'
>>> c2.foo
'bar'

The lookup happening here is not quite the same. c1 has written an instance attribute, called foo, with the value of 'baz'. However, c2 has no such instance attribute. However, because the class, C, does, the lookup uses the class attribute.

Consider what happens if you modify the class attribute, as shown here:

>>> C.foo = 'bacon'
>>> c1.foo
'baz'
>>> c2.foo
'bacon'

Here, c1.foo was unaffected, because c1 has an instance attribute called foo. However, the value of c2.foo has changed, because it has no such attribute on the instance. Therefore, when the attribute of the class changes, you observe the change on the instance.

You can view this within Python's internal data model by examining the __dict__ attribute of both instances.

>>> c1.__dict__
{'foo': 'baz'}
>>> c2.__dict__
{}

Under normal circumstances, the special __dict__ attribute is what stores all the attributes (and their values) for an object. There are exceptions to this rule. A class may define a custom __getattr__ or __getattribute__ method (as discussed in Chapter 4, “Magic Methods”), or may define a special attribute __slots__, which also introduces alternative attribute behavior. (This is rarely needed except in particular situations where memory use is paramount, and is not discussed in this book.) Notice that c1 has a foo key in its __dict__, and c2 does not.

The Class Method Limitation

This situation gets really interesting when classes define class methods. Remember that class methods are methods that do not expect or require an instance of the class to execute, but do require the class itself. They are usually declared by decorating a method with the @classmethod decorator, and their first argument is traditionally called cls rather than self.

Consider the following C class with a class method that accesses and returns foo from the class:

class C(object):
    foo = 'bar'

    @classmethod
    def classfoo(cls):
        return cls.foo

In the context of the classfoo method, the foo attribute is being accessed explicitly on the class, rather than on the instance. Re-run the example using the new class definition, and then consider the following:

>>> c1.foo
'baz'
>>> c1.classfoo()
'bacon'
>>> c2.classfoo()
'bacon'

There is, in fact, no actual way to access the instance attribute from the class method. That is the entire point of class methods, after all. They do not require an instance.

Tying This in with Class Factories

One of the biggest reasons to need class factories is when you are subclassing existing classes that rely on class attributes that must be adjusted.

Essentially, in code that you do not control, if an existing class sets a class attribute that must be customized, class factories are an attractive approach to generating appropriate subclasses with the overridden attributes.

Consider a situation where a class has an attribute that must be overridden at runtime (or where there are too many options for subclassing in static code to be reasonable). In this case, a class factory can be a very useful approach. Following is a continuation of the use of C as an instructive example:

def create_C_subclass(new_foo):
    class SubC(C):
        foo = new_foo
    return SubC

What matters here is that it is not necessary to know what the value of foo should be until the class is created, which is when the function runs. Like most other use of class factories, then, this is about knowing the attribute value at runtime.

Running your classfoo class method on C subclasses created this way gives you what you expect.

>>> S = create_C_subclass('spam')
>>> S.classfoo()
'spam'
>>> E = create_C_subclass('eggs')
>>> E.classfoo()
'eggs'

It is worth noting that, in many cases, it is much easier to simply create a subclass that accepts this value as part of its __init__ method. However, there are some cases where this is an insufficient solution. If the parent class relies on class methods, for example, then writing a new value to an instance will not cause the class methods to receive the new value, and this model of subclass creation becomes a valuable solution.