In this article written by Dusty Phillips, author of the book Python 3 Object-oriented Programming – Second Edition we’ll be discussing the object-oriented features of data structures, when they should be used instead of a regular class, and when they should not be used. In particular, we’ll be covering:

• Tuples and named tuples
• Dictionaries

(For more resources related to this topic, see here.)

Empty objects

Let’s start with the most basic Python built-in, one that we’ve seen many times already, the one that we’ve extended in every class we have created: the object. Technically, we can instantiate an object without writing a subclass:

>>> o = object()

>>> o.x = 5

Traceback (most recent call last):

  File "<stdin>", line 1, in <module>

AttributeError: 'object' object has no attribute 'x'

Unfortunately, as you can see, it’s not possible to set any attributes on an object that was instantiated directly. This isn’t because the Python developers wanted to force us to write our own classes, or anything so sinister. They did this to save memory; a lot of memory. When Python allows an object to have arbitrary attributes, it takes a certain amount of system memory to keep track of what attributes each object has, for storing both the attribute name and its value. Even if no attributes are stored, memory is allocated for potential new attributes. Given the dozens, hundreds, or thousands of objects (every class extends object) in a typical Python program; this small amount of memory would quickly become a large amount of memory. So, Python disables arbitrary properties on object, and several other built-ins, by default.

It is possible to restrict arbitrary properties on our own classes using slots. You now have a search term if you are looking for more information. In normal use, there isn’t much benefit to using slots, but if you’re writing an object that will be duplicated thousands of times throughout the system, they can help save memory, just as they do for object.

It is, however, trivial to create an empty object class of our own; we saw it in our earliest example:

class MyObject:

    pass

And, as we’ve already seen, it’s possible to set attributes on such classes:

>>> m = MyObject()

>>> m.x = "hello"

>>> m.x

'hello'

If we wanted to group properties together, we could store them in an empty object like this. But we are usually better off using other built-ins designed for storing data. It has been stressed that classes and objects should only be used when you want to specify both data and behaviors. The main reason to write an empty class is to quickly block something out, knowing we’ll come back later to add behavior. It is much easier to adapt behaviors to a class than it is to replace a data structure with an object and change all references to it. Therefore, it is important to decide from the outset if the data is just data, or if it is an object in disguise. Once that design decision is made, the rest of the design naturally falls into place.

Tuples and named tuples

Tuples are objects that can store a specific number of other objects in order. They are immutable, so we can’t add, remove, or replace objects on the fly. This may seem like a massive restriction, but the truth is, if you need to modify a tuple, you’re using the wrong data type (usually a list would be more suitable). The primary benefit of tuples’ immutability is that we can use them as keys in dictionaries, and in other locations where an object requires a hash value.

Tuples are used to store data; behavior cannot be stored in a tuple. If we require behavior to manipulate a tuple, we have to pass the tuple into a function (or method on another object) that performs the action.

Tuples should generally store values that are somehow different from each other. For example, we would not put three stock symbols in a tuple, but we might create a tuple of stock symbol, current price, high, and low for the day. The primary purpose of a tuple is to aggregate different pieces of data together into one container. Thus, a tuple can be the easiest tool to replace the “object with no data” idiom.

We can create a tuple by separating the values with a comma. Usually, tuples are wrapped in parentheses to make them easy to read and to separate them from other parts of an expression, but this is not always mandatory. The following two assignments are identical (they record a stock, the current price, the high, and the low for a rather profitable company):

>>> stock = "FB", 75.00, 75.03, 74.90

>>> stock2 = ("FB", 75.00, 75.03, 74.90)

If we’re grouping a tuple inside of some other object, such as a function call, list comprehension, or generator, the parentheses are required. Otherwise, it would be impossible for the interpreter to know whether it is a tuple or the next function parameter. For example, the following function accepts a tuple and a date, and returns a tuple of the date and the middle value between the stock’s high and low value:

import datetime

def middle(stock, date):

    symbol, current, high, low = stock

    return (((high + low) / 2), date)

 

mid_value, date = middle(("FB", 75.00, 75.03, 74.90),

        datetime.date(2014, 10, 31))

The tuple is created directly inside the function call by separating the values with commas and enclosing the entire tuple in parenthesis. This tuple is then followed by a comma to separate it from the second argument.

This example also illustrates tuple unpacking. The first line inside the function unpacks the stock parameter into four different variables. The tuple has to be exactly the same length as the number of variables, or it will raise an exception. We can also see an example of tuple unpacking on the last line, where the tuple returned inside the function is unpacked into two values, mid_value and date. Granted, this is a strange thing to do, since we supplied the date to the function in the first place, but it gave us a chance to see unpacking at work.

Unpacking is a very useful feature in Python. We can group variables together to make storing and passing them around simpler, but the moment we need to access all of them, we can unpack them into separate variables. Of course, sometimes we only need access to one of the variables in the tuple. We can use the same syntax that we use for other sequence types (lists and strings, for example) to access an individual value:

>>> stock = "FB", 75.00, 75.03, 74.90

>>> high = stock[2]

>>> high

75.03

We can even use slice notation to extract larger pieces of tuples:

>>> stock[1:3]

(75.00, 75.03)

These examples, while illustrating how flexible tuples can be, also demonstrate one of their major disadvantages: readability. How does someone reading this code know what is in the second position of a specific tuple? They can guess, from the name of the variable we assigned it to, that it is high of some sort, but if we had just accessed the tuple value in a calculation without assigning it, there would be no such indication. They would have to paw through the code to find where the tuple was declared before they could discover what it does.

Accessing tuple members directly is fine in some circumstances, but don’t make a habit of it. Such so-called “magic numbers” (numbers that seem to come out of thin air with no apparent meaning within the code) are the source of many coding errors and lead to hours of frustrated debugging. Try to use tuples only when you know that all the values are going to be useful at once and it’s normally going to be unpacked when it is accessed. If you have to access a member directly or using a slice and the purpose of that value is not immediately obvious, at least include a comment explaining where it came from.

Named tuples

So, what do we do when we want to group values together, but know we’re frequently going to need to access them individually? Well, we could use an empty object, as discussed in the previous section (but that is rarely useful unless we anticipate adding behavior later), or we could use a dictionary (most useful if we don’t know exactly how many or which specific data will be stored), as we’ll cover in the next section.

If, however, we do not need to add behavior to the object, and we know in advance what attributes we need to store, we can use a named tuple. Named tuples are tuples with attitude. They are a great way to group read-only data together.

Constructing a named tuple takes a bit more work than a normal tuple. First, we have to import namedtuple, as it is not in the namespace by default. Then, we describe the named tuple by giving it a name and outlining its attributes. This returns a class-like object that we can instantiate with the required values as many times as we want:

from collections import namedtuple

Stock = namedtuple("Stock", "symbol current high low")

stock = Stock("FB", 75.00, high=75.03, low=74.90)

The namedtuple constructor accepts two arguments. The first is an identifier for the named tuple. The second is a string of space-separated attributes that the named tuple can have. The first attribute should be listed, followed by a space (or comma if you prefer), then the second attribute, then another space, and so on. The result is an object that can be called just like a normal class to instantiate other objects. The constructor must have exactly the right number of arguments that can be passed in as arguments or keyword arguments. As with normal objects, we can create as many instances of this “class” as we like, with different values for each.

The resulting namedtuple can then be packed, unpacked, and otherwise treated like a normal tuple, but we can also access individual attributes on it as if it were an object:

>>> stock.high

75.03

>>> symbol, current, high, low = stock

>>> current

75.00

Remember that creating named tuples is a two-step process. First, use collections.namedtuple to create a class, and then construct instances of that class.

Named tuples are perfect for many “data only” representations, but they are not ideal for all situations. Like tuples and strings, named tuples are immutable, so we cannot modify an attribute once it has been set. For example, the current value of my company’s stock has gone down since we started this discussion, but we can’t set the new value:

>>> stock.current = 74.98

Traceback (most recent call last):

  File "<stdin>", line 1, in <module>

AttributeError: can't set attribute

If we need to be able to change stored data, a dictionary may be what we need instead.

Dictionaries

Dictionaries are incredibly useful containers that allow us to map objects directly to other objects. An empty object with attributes to it is a sort of dictionary; the names of the properties map to the property values. This is actually closer to the truth than it sounds; internally, objects normally represent attributes as a dictionary, where the values are properties or methods on the objects (see the __dict__ attribute if you don’t believe me). Even the attributes on a module are stored, internally, in a dictionary.

Dictionaries are extremely efficient at looking up a value, given a specific key object that maps to that value. They should always be used when you want to find one object based on some other object. The object that is being stored is called the value; the object that is being used as an index is called the key. We’ve already seen dictionary syntax in some of our previous examples.

Dictionaries can be created either using the dict() constructor or using the {} syntax shortcut. In practice, the latter format is almost always used. We can prepopulate a dictionary by separating the keys from the values using a colon, and separating the key value pairs using a comma.

For example, in a stock application, we would most often want to look up prices by the stock symbol. We can create a dictionary that uses stock symbols as keys, and tuples of current, high, and low as values like this:

stocks = {"GOOG": (613.30, 625.86, 610.50),

          "MSFT": (30.25, 30.70, 30.19)}

As we’ve seen in previous examples, we can then look up values in the dictionary by requesting a key inside square brackets. If the key is not in the dictionary, it will raise an exception:

>>> stocks["GOOG"]

(613.3, 625.86, 610.5)

>>> stocks["RIM"]

Traceback (most recent call last):

  File "<stdin>", line 1, in <module>

KeyError: 'RIM'

We can, of course, catch the KeyError and handle it. But we have other options. Remember, dictionaries are objects, even if their primary purpose is to hold other objects. As such, they have several behaviors associated with them. One of the most useful of these methods is the get method; it accepts a key as the first parameter and an optional default value if the key doesn’t exist:

>>> print(stocks.get("RIM"))

None

>>> stocks.get("RIM", "NOT FOUND")

'NOT FOUND'

For even more control, we can use the setdefault method. If the key is in the dictionary, this method behaves just like get; it returns the value for that key. Otherwise, if the key is not in the dictionary, it will not only return the default value we supply in the method call (just like get does), it will also set the key to that same value. Another way to think of it is that setdefault sets a value in the dictionary only if that value has not previously been set. Then it returns the value in the dictionary, either the one that was already there, or the newly provided default value.

>>> stocks.setdefault("GOOG", "INVALID")

(613.3, 625.86, 610.5)

>>> stocks.setdefault("BBRY", (10.50, 10.62, 10.39))

(10.50, 10.62, 10.39)

>>> stocks["BBRY"]

(10.50, 10.62, 10.39)

The GOOG stock was already in the dictionary, so when we tried to setdefault it to an invalid value, it just returned the value already in the dictionary. BBRY was not in the dictionary, so setdefault returned the default value and set the new value in the dictionary for us. We then check that the new stock is, indeed, in the dictionary.

Three other very useful dictionary methods are keys(), values(), and items(). The first two return an iterator over all the keys and all the values in the dictionary. We can use these like lists or in for loops if we want to process all the keys or values. The items() method is probably the most useful; it returns an iterator over tuples of (key, value) pairs for every item in the dictionary. This works great with tuple unpacking in a for loop to loop over associated keys and values. This example does just that to print each stock in the dictionary with its current value:

>>> for stock, values in stocks.items():

...     print("{} last value is {}".format(stock, values[0]))

...

GOOG last value is 613.3

BBRY last value is 10.50

MSFT last value is 30.25

Each key/value tuple is unpacked into two variables named stock and values (we could use any variable names we wanted, but these both seem appropriate) and then printed in a formatted string.

Notice that the stocks do not show up in the same order in which they were inserted. Dictionaries, due to the efficient algorithm (known as hashing) that is used to make key lookup so fast, are inherently unsorted.

So, there are numerous ways to retrieve data from a dictionary once it has been instantiated; we can use square brackets as index syntax, the get method, the setdefault method, or iterate over the items method, among others.

Finally, as you likely already know, we can set a value in a dictionary using the same indexing syntax we use to retrieve a value:

>>> stocks["GOOG"] = (597.63, 610.00, 596.28)

>>> stocks['GOOG']

(597.63, 610.0, 596.28)

Google’s price is lower today, so I’ve updated the tuple value in the dictionary. We can use this index syntax to set a value for any key, regardless of whether the key is in the dictionary. If it is in the dictionary, the old value will be replaced with the new one; otherwise, a new key/value pair will be created.

We’ve been using strings as dictionary keys, so far, but we aren’t limited to string keys. It is common to use strings as keys, especially when we’re storing data in a dictionary to gather it together (instead of using an object with named properties). But we can also use tuples, numbers, or even objects we’ve defined ourselves as dictionary keys. We can even use different types of keys in a single dictionary:

random_keys = {}

random_keys["astring"] = "somestring"

random_keys[5] = "aninteger"

random_keys[25.2] = "floats work too"

random_keys[("abc", 123)] = "so do tuples"

 

class AnObject:

    def __init__(self, avalue):

        self.avalue = avalue

 

my_object = AnObject(14)

random_keys[my_object] = "We can even store objects"

my_object.avalue = 12

try:

    random_keys[[1,2,3]] = "we can't store lists though"

except:

    print("unable to store listn")

 

for key, value in random_keys.items():

    print("{} has value {}".format(key, value))

This code shows several different types of keys we can supply to a dictionary. It also shows one type of object that cannot be used. We’ve already used lists extensively, and we’ll be seeing many more details of them in the next section. Because lists can change at any time (by adding or removing items, for example), they cannot hash to a specific value.

Objects that are hashable basically have a defined algorithm that converts the object into a unique integer value for rapid lookup. This hash is what is actually used to look up values in a dictionary. For example, strings map to integers based on the characters in the string, while tuples combine hashes of the items inside the tuple. Any two objects that are somehow considered equal (like strings with the same characters or tuples with the same values) should have the same hash value, and the hash value for an object should never ever change. Lists, however, can have their contents changed, which would change their hash value (two lists should only be equal if their contents are the same). Because of this, they can’t be used as dictionary keys. For the same reason, dictionaries cannot be used as keys into other dictionaries.

In contrast, there are no limits on the types of objects that can be used as dictionary values. We can use a string key that maps to a list value, for example, or we can have a nested dictionary as a value in another dictionary.

Dictionary use cases

Dictionaries are extremely versatile and have numerous uses. There are two major ways that dictionaries can be used. The first is dictionaries where all the keys represent different instances of similar objects; for example, our stock dictionary. This is an indexing system. We use the stock symbol as an index to the values. The values could even have been complicated self-defined objects that made buy and sell decisions or set a stop-loss, rather than our simple tuples.

The second design is dictionaries where each key represents some aspect of a single structure; in this case, we’d probably use a separate dictionary for each object, and they’d all have similar (though often not identical) sets of keys. This latter situation can often also be solved with named tuples. These should typically be used when we know exactly what attributes the data must store, and we know that all pieces of the data must be supplied at once (when the item is constructed). But if we need to create or change dictionary keys over time or we don’t know exactly what the keys might be, a dictionary is more suitable.

Using defaultdict

We’ve seen how to use setdefault to set a default value if a key doesn’t exist, but this can get a bit monotonous if we need to set a default value every time we look up a value. For example, if we’re writing code that counts the number of times a letter occurs in a given sentence, we could do this:

def letter_frequency(sentence):

    frequencies = {}

    for letter in sentence:

        frequency = frequencies.setdefault(letter, 0)

        frequencies[letter] = frequency + 1

    return frequencies

Every time we access the dictionary, we need to check that it has a value already, and if not, set it to zero. When something like this needs to be done every time an empty key is requested, we can use a different version of the dictionary, called defaultdict:

from collections import defaultdict

def letter_frequency(sentence):

    frequencies = defaultdict(int)

    for letter in sentence:

        frequencies[letter] += 1

    return frequencies

This code looks like it couldn’t possibly work. The defaultdict accepts a function in its constructor. Whenever a key is accessed that is not already in the dictionary, it calls that function, with no parameters, to create a default value.

In this case, the function it calls is int, which is the constructor for an integer object. Normally, integers are created simply by typing an integer number into our code, and if we do create one using the int constructor, we pass it the item we want to create (for example, to convert a string of digits into an integer). But if we call int without any arguments, it returns, conveniently, the number zero. In this code, if the letter doesn’t exist in the defaultdict, the number zero is returned when we access it. Then we add one to this number to indicate we’ve found an instance of that letter, and the next time we find one, that number will be returned and we can increment the value again.

The defaultdict is useful for creating dictionaries of containers. If we want to create a dictionary of stock prices for the past 30 days, we could use a stock symbol as the key and store the prices in list; the first time we access the stock price, we would want it to create an empty list. Simply pass list into the defaultdict, and it will be called every time an empty key is accessed. We can do similar things with sets or even empty dictionaries if we want to associate one with a key.

Of course, we can also write our own functions and pass them into the defaultdict. Suppose we want to create a defaultdict where each new element contains a tuple of the number of items inserted into the dictionary at that time and an empty list to hold other things. Nobody knows why we would want to create such an object, but let’s have a look:

from collections import defaultdict

num_items = 0

def tuple_counter():

    global num_items

    num_items += 1

    return (num_items, [])

 

d = defaultdict(tuple_counter)

When we run this code, we can access empty keys and insert into the list all in one statement:

>>> d = defaultdict(tuple_counter)

>>> d['a'][1].append("hello")

>>> d['b'][1].append('world')

>>> d

defaultdict(<function tuple_counter at 0x82f2c6c>,

{'a': (1, ['hello']), 'b': (2, ['world'])})

When we print dict at the end, we see that the counter really was working.

This example, while succinctly demonstrating how to create our own function for defaultdict, is not actually very good code; using a global variable means that if we created four different defaultdict segments that each used tuple_counter, it would count the number of entries in all dictionaries, rather than having a different count for each one. It would be better to create a class and pass a method on that class to defaultdict.

Counter

You’d think that you couldn’t get much simpler than defaultdict(int), but the “I want to count specific instances in an iterable” use case is common enough that the Python developers created a specific class for it. The previous code that counts characters in a string can easily be calculated in a single line:

from collections import Counter

def letter_frequency(sentence):

    return Counter(sentence)

The Counter object behaves like a beefed up dictionary where the keys are the items being counted and the values are the number of such items. One of the most useful functions is the most_common() method. It returns a list of (key, count) tuples ordered by the count. You can optionally pass an integer argument into most_common() to request only the top most common elements. For example, you could write a simple polling application as follows:

from collections import Counter

 

responses = [

    "vanilla",

    "chocolate",

    "vanilla",

    "vanilla",

    "caramel",

    "strawberry",

    "vanilla"

]

 

print(

    "The children voted for {} ice cream".format(

        Counter(responses).most_common(1)[0][0]

    )

)

Presumably, you’d get the responses from a database or by using a complicated vision algorithm to count the kids who raised their hands. Here, we hardcode it so that we can test the most_common method. It returns a list that has only one element (because we requested one element in the parameter). This element stores the name of the top choice at position zero, hence the double [0][0] at the end of the call. I think they look like a surprised face, don’t you? Your computer is probably amazed it can count data so easily. It’s ancestor, Hollerith’s Tabulating Machine for the 1890 US census, must be so jealous!

Summary

We’ve covered several built-in data structures and attempted to understand how to choose one for specific applications. Sometimes, the best thing we can do is create a new class of objects, but often, one of the built-ins provides exactly what we need. When it doesn’t, we can always use inheritance or composition to adapt them to our use cases. We can even override special methods to completely change the behavior of built-in syntaxes.

Be sure to pick up the full title, Python 3 Object-oriented Programming – Second Edition, to continue your learning in the world of OOP Python. If you want to go above and beyond then there’s no better way than building on what you’ve discovered with Mastering Object-oriented Python and Learning Object-Oriented Programming too!

Resources for Article:

 

---

Further resources on this subject:

• Python LDAP applications – extra LDAP operations and the LDAP URL library [article]
• Exception Handling in MySQL for Python [article]
• Data Transactions Made Easy with MySQL and Python [article]

---