It had a small but loyal customer base, a reliable supply of moonflower, and
three owls that carried order confirmations and other notifications to customers across the kingdom.

The shop’s ordering system was simple:

We’ll make significant changes to this code in this article, but bear with me for now.

A customer orders an invisibility potion:

The output looks good:

Invisibility  £12.00
Owl dispatched to Merlin
12.00

I’m using Decimal for the prices here as it’s a better data type for money than float. We discussed this a bit here, too: The Weird and Wonderful World of Descriptors in Python • The Price is Right.

The shop has sold a potion, updated its stock, recorded the sale, and notified the customer.

What could possibly go wrong?

A new label for the Moon Festival

The Moon Festival is approaching, and the shop owner wants special labels:

🌙 Moon Festival Invisibility 🌙   £12.00

We could change .sell():

You can read more about the ‘rogue asterisk’ in the signature, a.k.a keyword-only arguments, in this post: A Story About Parameters and Arguments in Python Functions • “AI Coffee” Grand Opening This Monday.

Now this works:

Here’s the output from this code:

🌙 Moon Festival Invisibility 🌙  £12.00
Owl dispatched to Merlin
12.00

The change is small. Perhaps this class is still perfectly fine.

The shop owner then asks for a test that checks the label without selling a potion. This is where you start to see the design problem.

At the moment, the only place that creates a label is inside .sell(). There is no suitable way to check the label policy independently. The code does not offer a way to ask for a label without also selling a potion.

The design problem is that PotionShop currently is in charge of label creation, even though the label policy can change independently of the policy that deals with sales. How about moving label creation to its own class?

Now you can check that the label is correct without having to sell an item in the first place:

This code would raise an AssertionError if the string that labels.make() returns is not identical to the required output. In this case, there are no errors.

In a real project, you could use a testing platform to run these checks. But I’ll use plain assert statements throughout to keep things simpler in this tutorial.

The shop delegates label-making to this object:

You should also remove the three lines that create a label you had further down within .sell().

We’re using composition here. The Potion Shop has a label maker, and you pass a LabelMaker object to the .label_maker attribute in the PotionShop object. The PotionShop object can now delegate label making to an object dedicated to this task.

From this point onwards, the shop receives the label-making collaborator:

PotionShop still coordinates the sale, but the label policy can now change without changing PotionShop. We started separating responsibilities. Making labels is no longer the responsibility of the PotionShop object. But we still have a bit more to go.

You got a taste of what the Single Responsibility Principle does in the example so far. But the code still has other transgressions of this principle. Let’s work through them in the rest of this post.

The owls go on strike

A few days later, the owls refuse to fly during a thunderstorm. The potions can still be prepared, but the notification service is unavailable.

The shop needs to stop sending notifications temporarily.

Before changing the notification system, we first make the owl’s availability explicit:

But you also want to add a test to check the price is correct.

Your code extracts the price from the .recipes class attribute as part of the .sell() method. So, this is how you can test the price is what you’re expecting:

You get the following output and no AssertionError in this case:

Invisibility  £12.00
Owl dispatched to Merlin

However, you should also test this when the owls are unavailable. Of course, this shouldn’t make any difference to the price:

But, your code doesn’t get that far. The .sell() method calculates the price and prints the label. But the owl service raises OwlUnavailable and the code stops before you can verify the price is right:

Invisibility  £12.00
​
Traceback (most recent call last):
  ...
OwlUnavailable: The owls are currently unavailable

The price is not the problem. The test cannot inspect the price without also triggering an owl notification.

The shop’s different jobs are now getting in each other’s way. But before we fix this problem, let’s make the mess bigger.

A discount for cauldron owners

The owner has another idea. Customers who bring their own cauldron should receive a 10% discount.

We add another parameter:

You use .quantize(), which is a method in the Decimal class, to ensure the discounted value is rounded to two decimal places. Let’s try this with a shop whose notification service is available:

The output shows the correct discounted price:

Invisibility  £10.80
Owl dispatched to Merlin
10.80

Let’s see what happens if the owls are unavailable:

Your code raises an error since the owls aren’t flying:

Invisibility  £10.80
Traceback (most recent call last):
  ...
OwlUnavailable: The owls are currently unavailable

But there’s an even bigger problem now. Can you spot it?

Even though the code stopped execution and raised an error, it had already changed the stock and recorded a sale. Let’s use a try..except block to see what’s happening:

Here’s the output:

Invisibility  £10.80
Catching the ‘OwlUnavailable’ Exception
{’moonflower’: 8, ‘dragon_scale’: 0}
[(’Merlin’, ‘invisibility’, Decimal(’10.80’))]

You started off with 10 units of moonflower and 2 units of dragon scales in the potion shop. These values are currently hardcoded in the class’s .__init__() special method (which is in itself not a good idea, but more on this later.)

The recipe uses two units of each, as shown in the .recipes class attribute (which will also change soon.)

So you end up using up the stock even though .sell() raised an exception! You can see from the output that the sale was also registered.

One failure too many

The .sell() method is now responsible for:

• Looking up recipes

• Removing ingredients

• Calculating prices

• Applying discounts

• Coordinating label creation*

• Recording sales

• Sending notifications

* Creating labels is the one we have already improved. It’s the others that are still a problem!

And the owner has just mentioned loyalty points, premium labels, email notifications, and a special discount for customers who arrive by broomstick.

The .sell() method is becoming the place where every new request arrives.

And it’s not just PotionShop.sell() that’s trying to do too much. The PotionShop class also takes care of the recipes available in the .recipes class attribute and the stock available in the shop.

It is time to separate these responsibilities.

Separating the recipe book

Let’s start with the recipes. The shop should not need to know the details of every recipe. That is the recipe book’s job:

This class is responsible for the recipe book. And nothing else. You add the .find() method to make it easier for a user to use the class without knowing the details of how it’s built. It’s usually best for a class to manage its own data. So, rather than requiring the user to know that the recipes are stored in a dictionary, you provide the .find() method that does the work.

Suppose the potion maker changes a recipe or adds a new potion. Those changes belong in RecipeBook; the steps for selling a potion don’t need to change.

We can test this class without creating a shop, changing stock, printing labels, or sending owls:

This code doesn’t raise an exception since the price is correct.

Separating inventory

Inventory management also doesn’t belong to the PotionShop class:

The two loops in .remove_stock() are deliberate. If we reduced each quantity as we went, we could use some ingredients and then discover that there isn’t enough of another. The sale would fail, but the stock would already be partly changed. Checking every quantity first avoids that partial update.

We can see what happens when there isn’t enough stock:

The operation fails before changing any stock:

Not enough dragon_scale
{’moonflower’: 10, ‘dragon_scale’: 2}

After a successful sale, a delivery can add stock again:

Here’s the output from this code:

{’moonflower’: 13, ‘dragon_scale’: 0}

Inventory owns both the stock data and the operations that change its quantities. It does not need to know who bought the potion or whether the label is festive.

Separating prices and labels

Pricing has its own rules:

Once again, this class now has just one responsibility: to deal with the pricing.

You can check the pricing strategy works without having to sell a product and everything else.

10.80

Labels have their own rules too. You dealt with this earlier in the tutorial when you created LabelMaker

PriceCalculator and LabelMaker could both be functions here. We’re using classes because they act as collaborators that the shop receives from outside. Later, we’ll see how protocols or abstract base classes can describe interchangeable collaborators more explicitly. For now, the important point is the separation of responsibilities and not the fact that each responsibility has become a class.

Neither class needs an inventory, a sales ledger, or an owl.

Putting the shop back together

We still need something to coordinate the sale. First, we give the sales ledger and the notifier small, focused interfaces:

Notice the "pending" state in the ledger. Separating responsibilities does not make the sale process independent of anything else. Inventory has already changed before later steps run. Here, the narrower goal is to make notification failure visible so that the recorded sale can be investigated.

Now we can keep PotionShop as a thin coordinator. It still represents the sale process, but it delegates each part of that process to the object that owns the relevant behaviour:

We can now assemble the shop and sell a potion:

Here’s the output:

🌙 Moon Festival Invisibility 🌙 £10.80
Owl dispatched to Merlin
10.80
{’customer’: ‘Merlin’, ‘potion’: ‘invisibility’, ‘price’: Decimal(’10.80’), ‘notification’: ‘sent’}

If notification fails after the ledger records the sale, the sale remains
visible with a pending notification:

Here’s the output:

Invisibility  £12.00
{’customer’: ‘Merlin’, ‘potion’: ‘invisibility’, 
 ‘price’: Decimal(’12.00’), ‘notification’: ‘pending’}
​

The coordinator still changes if the business process changes. That’s fine: coordinating a sale is its responsibility. But recipe changes belong in RecipeBook, inventory changes belong in Inventory, pricing changes belong in PriceCalculator, label changes belong in LabelMaker, and notification changes belong in Notifier.

The Single Responsibility Principle

This is the idea behind the Single Responsibility Principle:

A class should have one reason to change.

I always find these “official” definitions a bit cryptic when I read them at first. Here, “reason” is about the policy or stakeholder driving the change. The pricing rules may change because the shop owner changes the discounts. The label design may change because the person responsible for packaging wants something different. The notification service may change because the owls are on strike.

That does not mean that every class should have one method. Nor does it mean that every noun in the story needs its own class.

PriceCalculator can have several related methods. Inventory can have several operations. The important question is whether the methods belong to the same coherent responsibility.

The thin PotionShop coordinator is also a class with a responsibility. It coordinates the sale. A change to that business process may quite reasonably affect it.

When unrelated changes keep arriving at the same class, the class becomes harder to test and more likely to break. Extract a collaborator when it may need to change for a different reason from the surrounding code, or when separating it makes an important test simpler. A good class name alone isn’t a reason to create one.

The potion shop did not become troublesome because it had a particular number of lines. It became troublesome because recipes, inventory, pricing, labels, sales, and notifications all had different reasons to change.

A useful question to ask is:

What different kinds of change could affect this class?

If the answers are “the pricing rules”, “the label design”, “the storage system”, and “the notification service”, you may have several responsibilities sharing one home.

And if the project keeps growing, we may need to rethink the floor plan.

This is the first article in a series on the SOLID principles. I’ll look at what each principle means, but more importantly, why it matters and what can go wrong when we ignore it.

Code in this article uses Python 3.14.

Do you want to keep up with how Python programming and the art of making things are changing in this rapidly changing world? Then don’t miss out on the exclusive content for premium members here on The Python Coding Stack.

Subscribe now

I’ll be sharing more about how my programming, my daily work, and everything has changed over the recent months.

For more Python resources, you can also visit Real Python—you may even stumble on one of my own articles or courses there!

Also, are you interested in technical writing? You’d like to make your own writing more narrative, more engaging, more memorable? Have a look at Breaking the Rules.

And you can find out more about me at stephengruppetta.com

Appendix: Code Blocks

Code Block #1

from decimal import Decimal
​
class PotionShop:
    recipes = {
        “invisibility”: {
            “ingredients”: {
                “moonflower”: 2,
                “dragon_scale”: 2,
            },
            “price”: Decimal(”12.00”),
        }
    }
​
    def __init__(self):
        self.stock = {
            “moonflower”: 10,
            “dragon_scale”: 2,
        }
        self.sales = []
​
    def sell(self, potion_name, customer):
        potion = self.recipes[potion_name]
​
        for ingredient, quantity in potion[”ingredients”].items():
            if self.stock[ingredient] < quantity:
                raise ValueError(f”Not enough {ingredient}”)
​
        for ingredient, quantity in potion[”ingredients”].items():
            self.stock[ingredient] -= quantity
​
        price = potion[”price”]
        self.sales.append((customer, potion_name, price))
​
        print(f”{potion_name.title()}\t£{price:.2f}”)
        self.send_owl(
            customer,
            {”potion_name”: potion_name, “price”: price},
        )
​
        return price
​
    def send_owl(self, customer, message_content):
        print(f”Owl dispatched to {customer}”)
        return message_content

Code Block #2

shop = PotionShop()
print(shop.sell(”invisibility”, “Merlin”))

Code Block #3

# ...
​
class PotionShop:
    # ...
​
    def sell(
            self,
            potion_name,
            customer,
            *,
            moon_festival=False,
    ):
        # ...
​
        label = potion_name.title()
        if moon_festival:
            label = f”🌙 Moon Festival {label} 🌙”
​
        print(f”{label}\t£{price:.2f}”)
​
        # ...
    # ...

Code Block #4

shop = PotionShop()
print(shop.sell(”invisibility”, “Merlin”, moon_festival=True))

Code Block #5

# ...
​
class LabelMaker:
    def make(self, potion_name, moon_festival=False):
        label = potion_name.title()
​
        if moon_festival:
            label = f”🌙 Moon Festival {label} 🌙”
​
        return label
​
# ...

Code Block #6

labels = LabelMaker()
assert labels.make(
    “invisibility”,
    moon_festival=True,
) == “🌙 Moon Festival Invisibility 🌙”

Code Block #7

# ...
​
class PotionShop:
    # ...
​
    def __init__(self, label_maker):
        self.label_maker = label_maker
        # ...
​
    def sell(
            self,
            potion_name,
            customer,
            *,
            moon_festival=False,
    ):
        # ...
        label = self.label_maker.make(
            potion_name,
            moon_festival=moon_festival,
        )
        # ...
​
    # ...

Code Block #8

shop = PotionShop(LabelMaker())

Code Block #9

# ...
​
class OwlUnavailable(Exception):
    pass
​
# ...
​
class PotionShop:
    # ...
​
    def __init__(self, label_maker, owl_available=True):
        self.label_maker = label_maker
        self.owl_available = owl_available
        # ...
​
    # ...
​
    def send_owl(self, customer, message_content):
        if not self.owl_available:
            raise OwlUnavailable(
                “The owls are currently unavailable”
            )
        print(f”Owl dispatched to {customer}”)
        return message_content

Code Block #10

shop = PotionShop(LabelMaker())
​
assert shop.sell(”invisibility”, “Merlin”) == Decimal(”12.00”)

Code Block #11

shop = PotionShop(LabelMaker(), owl_available=False)
​
assert shop.sell(”invisibility”, “Merlin”) == Decimal(”12.00”)

Code Block #12

class PotionShop:
    # ...
​
    def sell(
        self,
        potion_name,
        customer,
        *,
        moon_festival=False,
        own_cauldron=False,
    ):
        # ...
​
        price = potion[”price”]
​
        if own_cauldron:
            price = (price * Decimal(”0.90”)).quantize(Decimal(”0.01”))
​
        # ...
​
        return price
​
    # ...

Code Block #13

shop = PotionShop(LabelMaker())
print(
    shop.sell(
        “invisibility”,
        “Merlin”,
        own_cauldron=True,
    )
)

Code Block #14

shop = PotionShop(LabelMaker(), owl_available=False)
print(
    shop.sell(
        “invisibility”,
        “Merlin”,
        own_cauldron=True,
    )
)

Code Block #15

shop = PotionShop(LabelMaker(), owl_available=False)
try:
    print(
        shop.sell(
            “invisibility”,
            “Merlin”,
            own_cauldron=True,
        )
    )
except OwlUnavailable:
    print(”Catching the ‘OwlUnavailable’ Exception”)
    print(shop.stock)
    print(shop.sales)

Code Block #16

class RecipeBook:
    def __init__(self):
        self.recipes = {
            “invisibility”: {
                “ingredients”: {
                    “moonflower”: 2,
                    “dragon_scale”: 2,
                },
                “price”: Decimal(”12.00”),
            }
        }
​
    def find(self, potion_name):
        return self.recipes[potion_name]

Code Block #17

recipe_book = RecipeBook()
assert recipe_book.find(”invisibility”)[”price”] == Decimal(”12.00”)

Code Block #18

class Inventory:
    def __init__(self, stock):
        self.stock = stock
​
    def remove_stock(self, ingredients):
        for ingredient, quantity in ingredients.items():
            if self.stock[ingredient] < quantity:
                raise ValueError(f”Not enough {ingredient}”)
​
        for ingredient, quantity in ingredients.items():
            self.stock[ingredient] -= quantity
​
    def add_stock(self, ingredients):
        for ingredient, quantity in ingredients.items():
            self.stock[ingredient] = self.stock.get(ingredient, 0) + quantity

Code Block #19

inventory = Inventory({
    “moonflower”: 10,
    “dragon_scale”: 2,
})
​
try:
    inventory.remove_stock({
        “moonflower”: 2,
        “dragon_scale”: 3,
    })
except ValueError as error:
    print(error)
​
print(inventory.stock)

Code Block #20

inventory.remove_stock({
    “moonflower”: 2,
    “dragon_scale”: 2,
})
inventory.add_stock({”moonflower”: 5})
print(inventory.stock)

Code Block #21

class PriceCalculator:
    def calculate(self, recipe, own_cauldron=False):
        price = recipe[”price”]
​
        if own_cauldron:
            price = (
                price * Decimal(”0.90”)
            ).quantize(Decimal(”0.01”))
​
        return price

Code Block #22

pricing = PriceCalculator()
print(
    pricing.calculate(
        {”price”: Decimal(”12.00”)},
        own_cauldron=True,
    )
)

Code Block #23

class SalesLedger:
    def __init__(self):
        self.sales = []
​
    def record(self, customer, potion_name, price):
        sale = {
            “customer”: customer,
            “potion”: potion_name,
            “price”: price,
            “notification”: “pending”,
        }
        self.sales.append(sale)
        return sale
​
    def mark_notified(self, sale):
        sale[”notification”] = “sent”
​
class Notifier:
    def send(self, customer, potion_name, price):
        print(f”Owl dispatched to {customer}”)

Code Block #24

class PotionShop:
    def __init__(
        self,
        recipe_book,
        inventory,
        pricing,
        labels,
        ledger,
        notifier,
    ):
        self.recipe_book = recipe_book
        self.inventory = inventory
        self.pricing = pricing
        self.labels = labels
        self.ledger = ledger
        self.notifier = notifier
​
    def sell(self, potion_name, customer, *, moon_festival=False,
             own_cauldron=False):
        recipe = self.recipe_book.find(potion_name)
        self.inventory.remove_stock(recipe[”ingredients”])
​
        price = self.pricing.calculate(
            recipe,
            own_cauldron=own_cauldron,
        )
        label = self.labels.make(
            potion_name,
            moon_festival=moon_festival,
        )
        sale = self.ledger.record(customer, potion_name, price)
​
        print(f”{label}\t£{price:.2f}”)
        self.notifier.send(customer, potion_name, price)
        self.ledger.mark_notified(sale)
​
        return price

Code Block #25

ledger = SalesLedger()
shop = PotionShop(
    RecipeBook(),
    Inventory({”moonflower”: 10, “dragon_scale”: 2}),
    PriceCalculator(),
    LabelMaker(),
    ledger,
    Notifier(),
)
​
print(
    shop.sell(
        “invisibility”,
        “Merlin”,
        moon_festival=True,
        own_cauldron=True,
    )
)
​
assert ledger.sales[0][”notification”] == “sent”
print(ledger.sales[0])

Code Block #26

class FailingNotifier:
    def send(self, customer, potion_name, price):
        raise OwlUnavailable(”The owls are currently unavailable”)
​
ledger = SalesLedger()
shop = PotionShop(
    RecipeBook(),
    Inventory({”moonflower”: 10, “dragon_scale”: 2}),
    PriceCalculator(),
    LabelMaker(),
    ledger,
    FailingNotifier(),
)
​
try:
    shop.sell(”invisibility”, “Merlin”)
except OwlUnavailable:
    pass
​
print(ledger.sales[0])
assert ledger.sales[0][”notification”] == “pending”

stephengruppetta.com

Following what’s happening when you have a chain of iterators in Python can feel like playing that game. But, unlike the street game, there are no scams when you’re playing the iterator game. Let’s make sure you’ll always win.

I’ll keep this article short. I wrote many articles about iterables and iterators. If you need to refresh your memory, have a look at The Anatomy of a for Loop and A One-Way Stream of Data • Iterators in Python (Data Structure Categories #6).

Follow The Data in a Chain of Iterators

Let’s keep the example simple. Start with this list in a REPL session:

A list is iterable. You can create an iterator from any iterable. Let’s create an iterator from this list:

The built-in function iter() creates an iterator from an iterable. Iterators don’t contain data. They don’t create copies of the data. They’re lightweight objects that create a stream. They’ll fetch data from the original source, which is the list boring_numbers in this case, as and when needed.

Iterators can only fetch an item once. So, they’re a one-way stream. Once you use an item, it’s gone from the iterator – but not from the original list, which remains unchanged.

Therefore, first_iter is an iterator that relies on data from the list boring_numbers. But let’s not fetch any items from the first_iter iterator. Not yet, anyway.

Create a second iterator. This time, you’ll use a generator expression. Generators are iterators, so you create a second iterator with this code:

Note that the expression on the right-hand side of the equals sign is enclosed in parentheses – the round ones, to be clear. This is a generator expression, which creates a generator iterator. Read Pay As You Go • Generate Data Using Generators (Data Structure Categories #7) for more on generators.

As we said, generators are iterators.

The second_iter iterator generates data from first_iter, which is itself an iterator. Iterators are also iterable, which is why you can use them directly in a for clause or anywhere else you’d generally use an iterable. The second_iter iterator will yield the values as floats. But you’ve not yielded any value from this iterator either. Not yet.

Let’s go a step further and create a third iterator, which is also a generator in this case. You build this third iterator from the second one, second_iter:

The generator iterator third_iter yields the sum of 0.5 and the value yielded by second_iter.

Incidentally, I used a “standard” iterator and two generator iterators in this example. However, for the journey we’re following in this article, it doesn’t matter whether we’re using a basic iterator or a generator iterator. If you prefer, you can repeat this exercise with iterators you get from iter() directly.

Support The Python Coding Stack

Don’t Blink • Follow the Data

You started with a list called boring_numbers. This data structure contains* the data. It’s where the data lives. We’ll be following the data in this section. So it’s important to know where it’s stored!

*Note: Lists, like all data structures, don’t really contain data in the purest sense of the word. See What’s In A List—Yes, But What’s Really In A Python List for more on this. But in general, it’s fine to talk about a list ‘containing’ items of data.

You then create three iterators. The first uses data from boring_numbers. The second iterator uses data from the first. And the third iterator uses data from the second.

But you haven’t tried to fetch any value from any of the iterators yet.

Let’s look at what each iterator is doing at the moment before you fetch any values. The first iterator, first_iter, is pointing at the first item in boring_numbers. It’s ready to read this value and yield it.

The second iterator, second_iter, is pointing at the first item in first_iter. But first_iter doesn’t have any data. Iterators don’t have their own data. But that’s OK. Whenever second_iter needs to fetch the value, it will ask first_iter to fetch and yield its “first” value. I put “first” in quotation marks because you’ll see later that this may or may not be the first value.

Finally, third_iter is pointing at the first item in second_iter. The same logic applies. When third_iter needs the first item, it will ask second_iter for its “first” item, and second_iter will need to ask first_iter for its “first” item. And first_iter is pointing at the first item in the list boring_numbers.

Are you with me? Let’s complicate things a bit…

Note how your code so far includes the following lines:

None of the iterators has yielded any value. For now.

Let’s jumble things up and start by fetching the first value from second_iter:

You ask for the next value in second_iter, which is the first one since you haven’t yielded any values yet.

As you’ve seen earlier, second_iter needs the first value from first_iter. So, behind the scenes, Python calls next(first_iter), which yields the first item from boring_numbers.

So, first_iter reads the first value from boring_numbers, which is the integer 1, and it yields it to second_iter, which then yields the transformed version to the REPL as the return value of next(second_iter). That’s why the output is the float 1.0. The first iterator, first_iter, now moves to point at the second item in boring_numbers, ready for when it’s needed.

Note that boring_numbers doesn’t change in this process. The first item in boring_numbers remains there. It doesn’t disappear.

So far, so good?

Continue in the same REPL session and try the following:

You ask third_iter to give you its “next” value. You haven’t used third_iter anywhere so far. So, you might expect it to yield the “first” value.

And it does.

But its interpretation of what’s the “first” item may be different to what you expect.

Let’s follow the data. When you call next(third_iter), the third iterator asks second_iter for its next item. The second iterator, second_iter, relies on first_iter, so it asks first_iter for its next item. And first_iter, as you may recall, is currently pointing at the second item in boring_numbers, which is the integer 2.

So:

1. The first iterator first_iter gets the integer 2 from boring_numbers and yields it to second_iter. And first_iter now points at the third item in boring_numbers.

2. Then, second_iter transforms this value into a float and yields 2.0 to third_iter.

3. Finally, third_iter adds 0.5 to this value and yields 2.5, which is what you see displayed in the REPL.

When you called next(second_iter) earlier in the code, you used up the first item in second_iter, which in turn used up the first item in first_iter. Since this first value is gone and since third_iter depends on the data yielded by second_iter and first_iter, the earlier call to next(second_iter) also affected the iterator that’s downstream, third_iter.

What will happen if you call next(first_iter) now? Try to follow the data in your head before trying it out or reading on.

.

.

Have you worked it out?

.

.

Let’s run the code:

Although it’s the first time you explicitly use first_iter in your code, you already used two of its values when your code yielded values from iterators downstream. Therefore, the next item in first_iter is the third item in boring_numbers, the integer 3.

Let’s finish with one more expression, still running in the same REPL session:

You call next(third_iter), which asks second_iter for its next item. And second_iter asks first_iter for its next item. At this stage in the process, first_iter is pointing at the fourth item in the original source of data, which is the list boring_numbers. That’s why the output is 4.5.

Independent Iterators

Consider the following code, which is similar to the one you wrote above but has one extra line:

The iterators first_iter and another_first_iter both use the same source of data, boring_numbers. However, they are independent iterators. Note that when you use up some of the elements in first_iter, the independent another_first_iter is not affected. The first time you ask for the first item in another_first_iter, you get the integer 1.

Final Words

Iterators don’t contain data. They rely on data that’s stored elsewhere. But you can have a chain of iterators, each asking the previous one to yield a value. Weird things can happen if you’re not careful. But now you know how to follow the data when you have a chain of iterators.

As a rule of thumb, if you create an iterator that depends on another iterator, you should only use the final iterator to avoid these issues. So, in the example above, you should only yield values from third_iter.

Have a play with this example and make your own chains of iterators, too. And once you’re comfortable with this, get ready to be confused again with my next article, which will discuss itertools.tee()!

And next time you pass by someone in the street offering to let you play the three-cups-and-ball game, don’t feel overconfident because of your iterator knowledge – it won’t help you find the ball.

Code in this article uses Python 3.14

The code images used in this article are created using Snappify. [Affiliate link]

Join The Club, the exclusive area for paid subscribers for more Python posts, videos, a members’ forum, and more.

Subscribe now

For more Python resources, you can also visit Real Python—you may even stumble on one of my own articles or courses there!

Also, are you interested in technical writing? You’d like to make your own writing more narrative, more engaging, more memorable? Have a look at Breaking the Rules.

And you can find out more about me at stephengruppetta.com

Further reading related to this article’s topic:

• The Anatomy of a for Loop

• A One-Way Stream of Data • Iterators in Python (Data Structure Categories #6)

• Pay As You Go • Generate Data Using Generators (Data Structure Categories #7)

• What’s In A List—Yes, But What’s Really In A Python List

Appendix: Code Blocks

Code Block #1

boring_numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

Code Block #2

# ...
first_iter = iter(boring_numbers)

Code Block #3

# ...
second_iter = (float(number) for number in first_iter)

Code Block #4

# ...
third_iter = (num + 0.5 for num in second_iter)

Code Block #5

boring_numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
first_iter = iter(boring_numbers)
second_iter = (float(number) for number in first_iter)
third_iter = (num + 0.5 for num in second_iter)

Code Block #6

# ...
next(second_iter)
# 1.0

Code Block #7

# ...
next(third_iter)
# 2.5

Code Block #8

# ...
next(first_iter)
# 3

Code Block #9

# ...
next(third_iter)
# 4.5

Code Block #10

boring_numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
first_iter = iter(boring_numbers)
another_first_iter = iter(boring_numbers)
second_iter = (float(number) for number in first_iter)
third_iter = (num + 0.5 for num in second_iter)
next(second_iter)
# 1.0
next(third_iter)
# 2.5
next(first_iter)
# 3
next(third_iter)
# 4.5
next(another_first_iter)
# 1

For more Python resources, you can also visit Real Python—you may even stumble on one of my own articles or courses there!

Also, are you interested in technical writing? You’d like to make your own writing more narrative, more engaging, more memorable? Have a look at Breaking the Rules.

And you can find out more about me at stephengruppetta.com

However, there are some headaches and rabbit holes along the way.

And one of these challenges is when you start exploring the “get*” dunder methods. You come across .__getitem__(), .__getattr__(), .__getattribute__(), and .__get__() and you think:

“Aren’t they all the same thing? They’re all ‘getting’ stuff, right?”

Well, yes, they’re all “getting stuff”, which is why they have “get” in their names. But, as you probably guessed by now, they do different things.

One Deals With [] • The Others Deal With .

Let’s start with the odd one out, which is also possibly the least challenging of the lot. The .__getitem__() special method deals with the square bracket notation, [], which you place after an object’s name. These are the square brackets you use to get an item from a list or a dictionary, say. You’ll see later that the other special methods with “get” in their name deal with the dot, ., which you use in a different context in Python.

With lists, or any other sequence, you use the square brackets with an index that represents the position of an item within the data structure. So, numbers[0] gives you the value of the first item in numbers if numbers is a sequence.

With dictionaries, or mappings in general, you place the key inside the square brackets to fetch the value associated with that key, such as points["Sam"], which gives the value associated with the key "Sam" if it exists.

Let’s explore a custom class:

You pass a mapping to PointsTable when creating an instance of the class. The data is stored as a dictionary in the ._data attribute.

Now, let’s say you’d like to access points from a PointsTable instance using the square bracket notation, as you would do with a dictionary:

Unfortunately, this doesn’t work:

Traceback (most recent call last):
  ...
    print(table[”Mark”])
          ~~~~~^^^^^^^^
TypeError: ‘PointsTable’ object is not subscriptable

The PointsTable instance is not a dictionary. It includes a dictionary as a data attribute. The PointsTable object itself is not subscriptable, which means you can’t use the square bracket notation to fetch an item.

When Python sees the square bracket notation after an object identifier, such as table, it calls the class’s .__getitem__() special method. If it’s not there, as in this case, Python raises a TypeError saying the object is not subscriptable.

But what does this tell you? If you want to use the square brackets notation, you just need to define .__getitem__() in the class:

Now, Python finds the .__getitem__() special method. It takes whatever you placed within the square brackets and passes it as an argument to .__getitem__(). Therefore, table["Mark"] returns whatever the call to PointsTable.__getitem__(table, "Mark") returns:

17

The code outputs Mark’s points. The PointsTable class is now subscriptable since it has a .__getitem__() special method. The term item generally refers to the objects contained within a data structure. Therefore, __getitem__() is there to let you get an item from within a data structure.

Let’s make this example a bit more interesting before we move on to the other special methods with “get” in their name.

Try the following:

This raises an error:

Traceback (most recent call last):
  File ..., line 18, in <module>
    print(table[”Mark”, “Stephen”])
          ~~~~~^^^^^^^^^^^^^^^^^^^
  File ..., line 6, in __getitem__
    return self._data[item]
           ~~~~~~~~~~^^^^^^
KeyError: (’Mark’, ‘Stephen’)

There’s no key equal to ("Mark", "Stephen"). So, you get a KeyError. Note how Python places parentheses around the two names when showing you the KeyError, even though you didn’t use the parentheses within the square brackets in table["Mark", "Stephen"]. This gives you a clue to what’s happening. But let’s explore this so we’re sure and we don’t just rely on our hunches:

You add two print() calls in .__getitem__(). Here’s what they print out before Python raises the KeyError:

item=(’Mark’, ‘Stephen’)
type(item)=<class ‘tuple’>

The object Python passes to .__getitem__() is the tuple ("Mark", "Stephen"). You decide to make your PointsTable class super-flexible so you can include more than one name within the square brackets notation:

The .__getitem__() method now checks whether item is a tuple first. If it is, then .__getitem__() returns a tuple with all the values. If item is not a tuple, then it must be just a single key, and the square brackets behave in the normal way:

(17, 20)
(22, 20, 19)
17

But note that you can no longer use an actual tuple as a dictionary key. This is fine in this example since all the keys are strings with people’s names.

So, .__getitem__() gives you full control over what happens when you use the square brackets notation to fetch an item from an object. Now, let’s move on to the other “get*” special methods.

Support The Python Coding Stack

Accessing Data Using The Dot Notation, .

You decide you also want PointsTable to work with the dot notation, so that you can use table.Mark to get the number of points Mark has.

Note that I’m adding more features to this class to demonstrate various special methods in this article. I’m not suggesting it’s necessarily always desirable to try to be too fancy with your classes!

Let’s try it out directly first, without making any changes to the class:

Unfortunately, table.Mark raises an error:

Traceback (most recent call last):
  File ..., line 32, in <module>
    print(table.Mark)
          ^^^^^^^^^^
AttributeError: ‘PointsTable’ object has no attribute ‘Mark’

Python is looking for an attribute called Mark. Attributes are the things you can access using the dot notation in Python. Typically, these are data attributes, methods, properties, and other things you can access using the dot. However, as with everything else, Python provides special methods to handle this. But this is where it gets a bit complicated.

.__getattr__()

Let’s take this one step at a time. Let’s add the .__getattr__() special method. You can guess that this special method name stands for get attribute (but it’s not the only special method that stands for get attribute!) Let’s add this method:

The .__getattr__() special method has a print() call to show when it’s called. This line is not required, but it will help you figure out when Python calls this special method. It’s a way of peeking into Python’s inner workings! For completeness, I added a similar line to .__getitem__() as well.

There are two print() calls at the bottom: one uses the square brackets notation, which you dealt with in the previous section, and the other uses the dot notation. Now, both work:

Calling __getitem__ with argument item=’Mark’
17
Calling __getattr__ with argument name=’Mark’
17

As you’ve seen in the previous section, the square brackets notation relies on .__getitem__().

And as the third and fourth lines in this printout show, Python used .__getattr__() to deal with table.Mark.

Python passed the attribute name to the .__getattr__() special method’s name parameter. This method then fetches the value associated with this name from the dictionary ._data.

This trick only works for keys that are valid attribute names and that don’t clash with real attributes or methods. That’s one reason dictionary-style access is often preferable for arbitrary user data. But let’s stick with this exercise in this article.

Also, you wrote the code such that if self._data[name] raises a KeyError, then .__getattr__() raises an AttributeError, which is what you’d expect if you try to use a name that’s not an attribute after the dot:

This raises an AttributeError:

AttributeError: ‘PointsTable’ object has no attribute ‘Matilda’

It seems that .__getattr__() is analogous to .__getitem__() – the first deals with . and the second with []. But...

But things are a bit more complex. What if you try to access a standard attribute, say a data attribute or a method? You haven’t defined any methods in this class, but you do have a data attribute, ._data. It’s marked with a leading underscore, showing you shouldn’t access it directly. But you can “break the rules”. Python won’t stop you:

The output is the following:

{’Stephen’: 20, ‘Mark’: 17, ‘Kate’: 19, ‘Sarah’: 22}

Perhaps, this is not surprising. But note that there’s no printout that says that .__getattr__() was called, as you got when you used table.Mark. Let’s look at both outputs together:

The output now is the following:

Calling __getattr__ with argument name=’Mark’
17
{’Stephen’: 20, ‘Mark’: 17, ‘Kate’: 19, ‘Sarah’: 22}

Python called the .__getattr__() special method when you accessed .Mark, but not when you accessed ._data.

This means there’s something else happening behind the scenes.

.__getattribute__()

This is where .__getattribute__() enters the scene. No prizes for guessing that this method name stands for get attribute, but then so did .__getattr__(). This is confusing.

And here’s the thing. It’s .__getattribute__() that gets called each and every time you use the dot notation with an instance. Let’s define it:

Note that this code breaks lots of things as it is now. We’ll fix it soon. Let’s first look at the output from this code:

Calling __getattribute__ with argument name=’Mark’
None
Calling __getattribute__ with argument name=’_data’
None

As you can see, Python calls .__getattribute__() for both table.Mark and table._data. However, the current .__getattribute__() method does nothing else. Therefore, it returns None. You’ll see soon that this is a bigger problem than you might think.

Let’s try using the dot notation to access an attribute that doesn’t exist:

Every time you use the dot, ., Python calls .__getattribute__(), which, for now, does nothing except print out the self-serving statement to show it was called:

Calling __getattribute__ with argument name=’Mark’
None
Calling __getattribute__ with argument name=’_data’
None
Calling __getattribute__ with argument name=’Janine’
None

Therefore, you can’t access any attribute at the moment. All data attributes and methods are out of reach. You should be careful when overriding .__getattribute__(). In fact, you’ll rarely need to write your own .__getattribute__().

Let’s fix this code by calling object.__getattribute__() from within PointsTable.__getattribute__(). Recall that all Python classes inherit from object. And object.__getattribute__() is where the important logic that Python uses to decide what to do when you use the . lives. You can access object using super():

Note that in this class, .__getattribute__() is not doing anything different to the default version except for printing out a statement. I’m using this for demonstration purposes only.

Let’s deal with one print() call at a time. The code above includes print(table._data). You’re fetching the value of a data attribute:

Calling __getattribute__ with argument name=’_data’
{’Stephen’: 20, ‘Mark’: 17, ‘Kate’: 19, ‘Sarah’: 22}

Python calls PointsTable.__getattribute__(), which in turn calls the base class’s object.__getattribute__(). This special method recognises that ._data is an instance variable and fetches its value from the object’s .__dict__.

But let’s see what happens with the .Mark attribute access. Recall that .Mark is not a data attribute or method:

Here’s the output now. Look at the various printouts, too:

Calling __getattribute__ with argument name=’Mark’
Calling __getattr__ with argument name=’Mark’
Calling __getattribute__ with argument name=’_data’
17

When Python sees table.Mark, it calls PointsTable.__getattribute__(table, "Mark"). This call gives rise to the first line printed out above. The base class’s .__getattribute__() doesn’t recognise "Mark" as a data attribute, a method name, or anything else it’s expecting (such as descriptors, which we will discuss soon). So, object.__getattribute__() actually raises an AttributeError in this case, which you can’t see in the output above.

That’s because when .__getattribute__() raises an AttributeError during normal attribute access using the dot, Python checks whether there’s a .__getattr__() defined. If there is, it uses it as a fallback. That’s what happens in this case. You can see that .__getattr__() is called next – that’s the second line printed out above.

But .__getattr__() contains this line: return self._data[name]. There’s a dot in that line, too. So Python needs to access .__getattribute__() again, this time using "_data" as the argument. Since ._data is a data attribute, object.__getattribute__() doesn’t need to use .__getattr__() as a fallback since it knows how to deal with data attributes.

Confused? You’re not alone. This is confusing, I know. And there’s a bit more. But we’ll make sure things are clear by the end of this article.

But first, let’s focus on table.Mark again and let’s comment out, just for now, the definition of .__getattr__():

The base class’s .__getattribute__() method works hard to determine whether "Mark" is an attribute it expects. It doesn’t find it, and now, there’s no fallback .__getattr__(), so Python raises an error:

Calling __getattribute__ with argument name=’Mark’
Calling __getattribute__ with argument name=’__dict__’
Calling __getattribute__ with argument name=’__class__’
Traceback (most recent call last):
  ...
AttributeError: ‘PointsTable’ object has no attribute ‘Mark’

You can see a couple of extra printouts, too. These are side effects of Python preparing the error message since we get the printout each time Python uses the dot notation, even when it does so behind the scenes. Let’s not go too far down the rabbit hole in this article. We may never come out again if we go too deep!

You’ve seen that when you use the dot notation, Python calls object.__getattribute__() eventually. That’s why you should include super().__getattribute__() when you override this special method, unless you have a clear (niche) reason why you don’t want to do this. This special method looks in a number of places for the attribute. I’m going to skip a few steps in the hierarchy for now. But we’ll revisit these in the next section (remember, we’re not done yet since there’s still .__get__() to deal with).

The .__getattribute__() special method looks for instance attributes. Let’s temporarily turn .Mark into an instance attribute:

Now, .Mark is a data attribute, so .__getattribute__() finds it:

Calling __getattribute__ with argument name=’Mark’
This is Mark as a data attribute

If it’s not an instance variable, object.__getattribute__() also checks whether it’s a class attribute. Let’s test this:

Here’s the output:

Calling __getattribute__ with argument name=’Mark’
This is Mark as a class attribute

Note that the line in .__init__() that defines .Mark as a data attribute is commented out now because instance attributes take precedence over class attributes. Only when all else fails (including the steps I skipped for now), does Python check whether the fallback special method .__getattr__() is there.

So, when you use the dot notation for attribute access (the simplified version, for now):

1. Python calls .__getattribute__()

2. It checks for known attributes, such as instance attributes and class attributes (and a bit more – coming soon)

3. If it doesn’t find anything, then .__getattribute__() raises an AttributeError. However, Python does one final check before letting this error through to the user: is there a .__getattr__()? If there is, Python calls it to see whether it contains instructions for handling this unknown attribute.

I’m simplifying slightly here. Descriptors complicate the order, and we’ll return to them in the next section.

Note that in real code, you rarely need to define .__getattribute__(). You can rely on the default provided in the object base class in most cases. Most custom attribute behaviour should use .__getattr__() rather than .__getattribute__(). Use .__getattribute__() only when you need to intercept every attribute access. There is rarely a need for this, though.

Common uses for .__getattr__() include delegating missing attributes to another object, implementing lazy loading, or exposing dynamic attributes from structured data.

Here’s the tidied-up code in full so far:

The Asymmetry Between .__getattr__() and .__setattr__()

A short note: There’s an asymmetry between .__getattr__() and .__setattr__() despite their names following the same pattern. As you’ve seen above, .__getattr__() is only used as a fallback when .__getattribute__() doesn’t find the attribute through “normal routes”.

However, .__setattr__() doesn’t have a counterpart analogous to .__getattribute__(). Therefore, .__setattr__() is always used when setting the value of an attribute. Life is simpler in the “setting” world!

In this article, I’m focusing on the “getting” part of things, but some of the same logic applies to “setting”, too.

The Fourth Horseman: .__get__()

I’ve had this article in my pipeline here on The Python Coding Stack for a very long time. But I never wrote it because I knew that dealing with .__get__() would be a pain and would need a lot of time and space. However, in March, I published The Weird and Wonderful World of Descriptors in Python. If you haven’t read that article yet, well, now is the time!

And therefore I can cheat in this article. I can avoid talking about .__get__() in detail. What follows in this section is a summary of the world of descriptors. See the full article for more details.

If a class has .__get__(), it’s a descriptor class. If it only has .__get__() and it does not define .__set__() or .__delete__(), which are the other methods that make up the descriptor protocol, then the class creates non-data descriptors. Classes that include .__set__() or .__delete__() create data descriptors. This distinction matters when we get back to .__getattribute__() and the order it uses to look for known attributes.

Let’s explore this with a dummy example. This code defines two descriptor classes and another class to test the priority order that object.__getattribute__() uses for different attribute types:

DataDescriptor defines .__get__() and .__set__() methods, which is why it creates data descriptors. However, NonDataDescriptor creates non-data descriptors since the class only defines .__get__().

All the special methods in all classes (except .__init__()) have print() calls so you can see when Python calls them. Before we look at the output from this code, let’s review the five attributes you use in the print() calls and where they appear in the class definitions:

1. .first is defined as a data descriptor at the top of the TestingAttributeAccess class. Recall from the article on descriptors that you initially define descriptors as class attributes within a class. You also assign a value to .first within the class’s .__init__(). More on this soon.

2. .second is also defined as a descriptor at the top of the TestingAttributeAccess class, but it’s a non-data descriptor since the NonDataDescriptor class only defines .__get__(). You also assign a value to self.second within .__init__(). We’ll see how the class actually deals with .second soon, since it treats it differently from .first.

3. .third is also defined as a non-data descriptor. However, there is no other assignment to third within .__init__(). This is the key difference between .second and .third in this code.

4. .fourth is a class attribute. It’s not a descriptor and it’s not an instance attribute.

5. .fifth is not defined anywhere in the class, but you still call print(test.fifth).

Let’s look at the whole output from this code and then break it down into steps later:

Calling DataDescriptor.__set__ with value=”’first’: a data attribute defined in .__init__”

Printing `test.first`
Calling __getattribute__ with argument name=’first’
Calling DataDescriptor.__get__
This is the Data Descriptor

Printing `test.second`
Calling __getattribute__ with argument name=’second’
‘second’: a data attribute defined in .__init__

Printing `test.third`
Calling __getattribute__ with argument name=’third’
Calling NonDataDescriptor.__get__
This is the Non-Data Descriptor

Printing `test.fourth`
Calling __getattribute__ with argument name=’fourth’
I’m just a normal class attribute!

Printing `test.fifth`
Calling __getattribute__ with argument name=’fifth’
Calling __getattr__ with argument name=’fifth’
This is the fallback value from __getattr__

There’s plenty to digest there. So, let’s break it down in stages.

0. Creating an instance of TestingAttributeAccess

I want to focus on the “getting” bit from the various print() calls. However, there’s this line output first, so let’s deal with it, too:

Calling DataDescriptor.__set__ with value=”’first’: a data attribute defined in .__init__”

This happens when you create the instance of TestingAttributeAccess and assign it to the variable name test. Why? Because first has already been defined as a data descriptor at the time of the class definition. Therefore, when you assign a value to .first during initialisation, the descriptor protocol kicks in.

When you call TestingAttributeAccess(), Python calls the class’s .__init__() and soon finds this expression: self.first = ...

Therefore, Python calls DataDescriptor.__set__() to set the value of this attribute. Note that DataDescriptor.__set__() doesn’t really set anything in this case. Normally, something more meaningful would happen in .__set__(). See The Weird and Wonderful World of Descriptors in Python for more on this.

1. test.first

The next section in the code’s output is the following:

Printing `test.first`
Calling __getattribute__ with argument name=’first’
Calling DataDescriptor.__get__
This is the Data Descriptor

This output is created when you write print(test.first). The dot notation triggers Python to call .__getattribute__(). So, let’s start exploring the hierarchy of checks in .__getattribute__(). What does this special method look for first?

The first thing .__getattribute__() checks is whether the attribute is a data descriptor.

Since .first is a data descriptor, the search stops there. Python calls DataDescriptor.__get__() and returns whatever the .__get__() method returns. This is the string "This is the Data Descriptor" in this demo example.

2. test.second

Let’s look at the next segment in the code’s output. This is generated when you call print(test.second):

Printing `test.second`
Calling __getattribute__ with argument name=’second’
‘second’: a data attribute defined in .__init__

You know the drill by now. The dot notation is the trigger that makes Python call .__getattribute__(). It checks whether the attribute is a data descriptor. But .second is not a data descriptor. You initially define it as a non-data descriptor. Since it’s definitely not a data descriptor, it’s time to move on to the second check in the hierarchy.

The second thing .__getattribute__() checks is whether the attribute is an instance attribute.

Is this attribute name in the object’s .__dict__ dictionary? Instance attributes come second in the hierarchy. Now, you’ve seen that .second is not a data descriptor, which is why we moved to the second check. But is test.second an instance attribute or a non-data descriptor?

You can see from the printout that Python never called NonDataDescriptor.__get__() even though you originally defined .second as a NonDataDescriptor object. The swap occurred when you created the TestingAttributeAccess instance. Python calls the class’s .__init__(), which contains this assignment line: self.second = ....

Since .second is not a data descriptor (it’s a non-data descriptor) and doesn’t have a .__set__(), the descriptor protocol doesn’t kick in here to set the value of this attribute. This is different from .first, which was a data descriptor and, therefore, its .__set__() was responsible for setting the value.

Since the .second non-data descriptor doesn’t have a .__set__(), Python does what it always does in these cases: it assigns the new object, the string "'second': a data attribute defined in .__init__", to test.second. Therefore, test.second is now an instance attribute containing the string rather than the original non-data descriptor.

Although test.second would originally access the non-data descriptor, you created an instance attribute when you initialised the object. It’s now a data attribute, which is an instance attribute.

Note that TestingAttributeAccess.second is still there as a class attribute, and that’s still the non-data descriptor. But test.second now points to another object, the string.

Therefore, when later in the code you call print(test.second), Python calls .__getattribute__() and starts looking through its hierarchy. It’s not a data descriptor. It is an instance attribute. Therefore, it returns its value.

3. test.third

The next block of output is the one generated when you call print(test.third). Recall that .third is a NonDataDescriptor object. So was .second initially. However, unlike .second, Python never creates an instance attribute that’s assigned to test.third since you don’t assign to self.third in .__init__(). Here’s the output:

Printing `test.third`
Calling __getattribute__ with argument name=’third’
Calling NonDataDescriptor.__get__
This is the Non-Data Descriptor

In print(test.third), there’s a dot again, so Python calls .__getattribute__(). This method first checks whether .third is a data descriptor. It is not. Then it checks whether .third is an instance attribute. It is not. So...

The third thing .__getattribute__() checks is whether the attribute is a non-data descriptor.

Non-data descriptors come next in the hierarchy. That’s why you can see the printout saying that Python calls NonDataDescriptor.__get__ and then prints the attribute’s value, which is the value it gets from the non-data descriptor’s .__get__().

Incidentally, ordinary instance methods are functions that also implement the .__get__() special method. They are non-data descriptors. So, methods are found in this third check in the hierarchy of checks when you use the dot notation.

4. test.fourth

It’s test.fourth‘s turn. Here’s the output you get from print(test.fourth):

Printing `test.fourth`
Calling __getattribute__ with argument name=’fourth’
I’m just a normal class attribute!

There’s a dot, so there’s a call to .__getattribute__() which checks whether .fourth is a data descriptor, an instance attribute, or a non-data descriptor, in that order. It’s none of these. Time for the fourth check.

The fourth thing .__getattribute__() checks is whether the attribute is a class attribute.

And look at that! The .fourth attribute is indeed a class attribute.

5. test.fifth

And finally, it’s .fifth‘s turn. You call print(test.fifth) and you get the following:

Printing `test.fifth`
Calling __getattribute__ with argument name=’fifth’
Calling __getattr__ with argument name=’fifth’
This is the fallback value from __getattr__

Yes, yes, there’s a dot again, so Python calls .__getattribute__(). No, it’s not a data descriptor. No, it’s not an instance attribute. No, it’s not a non-data descriptor. No, it’s not a class attribute. It’s nothing. The attribute .fifth doesn’t exist.

When .__getattribute__() fails to find the attribute, Python calls .__getattr__() if this special method exists.

And that’s it. Simple, eh?!?!

Let’s finish off by summarising the order in which Python deals with looking for attributes when you use the dot notation:

1. The first thing .__getattribute__() checks is whether the attribute is a data descriptor.

2. The second thing .__getattribute__() checks is whether the attribute is an instance attribute.

3. The third thing .__getattribute__() checks is whether the attribute is a non-data descriptor.

4. The fourth thing .__getattribute__() checks is whether the attribute is a class attribute.

5. Finally, when .__getattribute__() fails to find the attribute, Python calls .__getattr__() if this special method exists.

The fifth step occurs when you access attributes using the dot notation. If you call .__getattribute__() explicitly, which you rarely need to do, Python doesn’t automatically look for .__getattr__().

Note that Python looks for descriptors, instance and class attributes in the class and its base classes, too, following the method resolution order.

Final Words

Wait for this. I’ve been waiting all article to write this:

Now, you won’t forget the four “get*” special methods.

Got it! (My son just walked out disapprovingly when he read this.)

You may never need to use all of these methods. Maybe you’ll never need to use any of them. But if you ever wondered why there are these four special methods with similar names, now you know what they do. And you dug a bit more underneath the Python surface along the way. And that’s always fun.

Photo by Robert Clark

Code in this article uses Python 3.14

The code images used in this article are created using Snappify. [Affiliate link]

Join The Club, the exclusive area for paid subscribers for more Python posts, videos, a members’ forum, and more.

Subscribe now

You can also support this publication by making a one-off contribution of any amount you wish.

Support The Python Coding Stack

For more Python resources, you can also visit Real Python—you may even stumble on one of my own articles or courses there!

Also, are you interested in technical writing? You’d like to make your own writing more narrative, more engaging, more memorable? Have a look at Breaking the Rules.

And you can find out more about me at stephengruppetta.com

Further reading related to this article’s topic:

• The Manor House, the Oak-Panelled Library, the Vending Machine, and Python’s `_getitem__()`

• The Weird and Wonderful World of Descriptors in Python • The Price is Right

Appendix: Code Blocks

Code Block #1

class PointsTable:
    def __init__(self, data):
        self._data = dict(data)

table = PointsTable(
    {
        "Stephen": 20,
        "Mark": 17,
        "Kate": 19,
        "Sarah": 22,
    }
)

Code Block #2

# ...
print(table["Mark"])

Code Block #3

class PointsTable:
    def __init__(self, data):
        self._data = dict(data)

    def __getitem__(self, item):
        return self._data[item]

table = PointsTable(
    {
        "Stephen": 20,
        "Mark": 17,
        "Kate": 19,
        "Sarah": 22,
    }
)

print(table["Mark"])

Code Block #4

# ...
print(table["Mark", "Stephen"])

Code Block #5

class PointsTable:
    def __init__(self, data):
        self._data = dict(data)

    def __getitem__(self, item):
        print(f"{item=}")
        print(f"{type(item)=}")
        return self._data[item]

table = PointsTable(
    # ...
)

print(table["Mark", "Stephen"])

Code Block #6

class PointsTable:
    def __init__(self, data):
        self._data = dict(data)

    def __getitem__(self, item):
        if isinstance(item, tuple):
            return tuple(self._data[key] for key in item)
        return self._data[item]

table = PointsTable(
    # ...
)

print(table["Mark", "Stephen"])
print(table["Sarah", "Stephen", "Kate"])
print(table["Mark"])

Code Block #7

# ...
print(table.Mark)

Code Block #8

class PointsTable:
    # ...

    def __getitem__(self, item):
        print(f"Calling __getitem__ with argument {item=}")
        if isinstance(item, tuple):
            return tuple(self._data[key] for key in item)
        return self._data[item]

    def __getattr__(self, name):
        print(f"Calling __getattr__ with argument {name=}")
        try:
            return self._data[name]
        except KeyError:
            raise AttributeError(
                f"'{type(self).__name__}' object has "
                f"no attribute '{name}'"
            ) from None

table = PointsTable(
    # ...
)

print(table["Mark"])
print(table.Mark)

Code Block #9

# ...
print(table.Matilda)

Code Block #10

# ...
print(table._data)

Code Block #11

# ...
print(table.Mark)
print(table._data)

Code Block #12

class PointsTable:
    def __init__(self, data):
        self._data = dict(data)

    def __getitem__(self, item):
        # ...

    def __getattr__(self, name):
        # ...

    def __getattribute__(self, name):
        print(f"Calling __getattribute__ with argument {name=}")

table = PointsTable(
    # ...
)

print(table.Mark)
print(table._data)

Code Block #13

# ...
print(table.Mark)
print(table._data)
print(table.Janine)

Code Block #14

class PointsTable:
    def __init__(self, data):
        self._data = dict(data)

    def __getitem__(self, item):
        # ...

    def __getattr__(self, name):
        # ...

    def __getattribute__(self, name):
        print(f"Calling __getattribute__ with argument {name=}")
        return super().__getattribute__(name)

table = PointsTable(
    # ...
)

print(table._data)

Code Block #15

# ...
print(table.Mark)

Code Block #16

class PointsTable:
    def __init__(self, data):
        self._data = dict(data)

    def __getitem__(self, item):
        # ...

    # def __getattr__(self, name):
    #     print(f"Calling __getattr__ with argument {name=}")
    #     try:
    #         return self._data[name]
    #     except KeyError:
    #         raise AttributeError(
    #             f"'{type(self).__name__}' object has "
    #             f"no attribute '{name}'"
    #         ) from None

    def __getattribute__(self, name):
        print(f"Calling __getattribute__ with argument {name=}")
        return super().__getattribute__(name)

table = PointsTable(
    # ...
)

print(table.Mark)

Code Block #17

class PointsTable:
    def __init__(self, data):
        self._data = dict(data)
        self.Mark = "This is Mark as a data attribute"

    def __getitem__(self, item):
        # ...

    # def __getattr__(self, name):
    # ...

    def __getattribute__(self, name):
        print(f"Calling __getattribute__ with argument {name=}")
        return super().__getattribute__(name)

table = PointsTable(
    # ...
)

print(table.Mark)

Code Block #18

class PointsTable:
    Mark = "This is Mark as a class attribute"

    def __init__(self, data):
        self._data = dict(data)
        # self.Mark = "This is Mark as a data attribute"

    def __getitem__(self, item):
        # ...

    # def __getattr__(self, name):
    # ...

    def __getattribute__(self, name):
        print(f"Calling __getattribute__ with argument {name=}")
        return super().__getattribute__(name)

table = PointsTable(
    # ...
)

print(table.Mark)

Code Block #19

class PointsTable:
    def __init__(self, data):
        self._data = dict(data)

    def __getitem__(self, item):
        print(f"Calling __getitem__ with argument {item=}")
        if isinstance(item, tuple):
            return tuple(self._data[key] for key in item)
        return self._data[item]

    def __getattr__(self, name):
        print(f"Calling __getattr__ with argument {name=}")
        try:
            return self._data[name]
        except KeyError:
            raise AttributeError(
                f"'{type(self).__name__}' object has "
                f"no attribute '{name}'"
            ) from None

    def __getattribute__(self, name):
        print(f"Calling __getattribute__ with argument {name=}")
        return super().__getattribute__(name)

table = PointsTable(
    {
        "Stephen": 20,
        "Mark": 17,
        "Kate": 19,
        "Sarah": 22,
    }
)

print(table._data)  # Only .__getattribute__() used
print(table.Mark)  # Fallback .__getattr__() needed here

Code Block #20

class DataDescriptor:
    def __get__(self, instance, owner):
        print("Calling DataDescriptor.__get__")
        return "This is the Data Descriptor"

    def __set__(self, instance, value):
        print(f"Calling DataDescriptor.__set__ with {value=}")

class NonDataDescriptor:
    def __get__(self, instance, owner):
        print("Calling NonDataDescriptor.__get__")
        return "This is the Non-Data Descriptor"

class TestingAttributeAccess:
    first = DataDescriptor()
    second = NonDataDescriptor()
    third = NonDataDescriptor()
    fourth = "I'm just a normal class attribute!"

    def __init__(self):
        self.first = "'first': a data attribute defined in .__init__"
        self.second = "'second': a data attribute defined in .__init__"

    def __getattribute__(self, name):
        print(f"Calling __getattribute__ with argument {name=}")
        return super().__getattribute__(name)

    def __getattr__(self, name):
        print(f"Calling __getattr__ with argument {name=}")
        return "This is the fallback value from __getattr__"

test = TestingAttributeAccess()
print("\nPrinting `test.first`")
print(test.first)
print("\nPrinting `test.second`")
print(test.second)
print("\nPrinting `test.third`")
print(test.third)
print("\nPrinting `test.fourth`")
print(test.fourth)
print("\nPrinting `test.fifth`")
print(test.fifth)

For more Python resources, you can also visit Real Python—you may even stumble on one of my own articles or courses there!

Also, are you interested in technical writing? You’d like to make your own writing more narrative, more engaging, more memorable? Have a look at Breaking the Rules.

And you can find out more about me at stephengruppetta.com

But one thing kept catching my attention: all the noise outside. Everyone’s talking about AI writing code, agents shipping products, the death of programming. And every so often, someone asks me — usually with that slightly guilty look of someone who thinks they’re about to insult my livelihood — “but do you really still need to learn Python? In this age?”

So I’ve been thinking about it. Properly. And I wanted to share where I’ve landed, because I think the answer matters and it’s different from what some hot takes suggest.

Do I still need to learn to code?

The way we write computer programs is changing. I don’t have a crystal ball for what programming looks like in five or ten years.

But here’s the thing: neither does anyone else.

Here’s what I know from watching others and experimenting with AI tools in my own work: right now, the people getting the most out of AI are the ones who already know how to code.

Here’s the hierarchy as I see it today:

• No coding knowledge = Little benefit from AI

• Little coding knowledge = Intermediate benefit from AI

• Intermediate coding knowledge = Great benefit from AI

• Great coding knowledge = Superpower-like benefit from AI

We’re in an era where some coding knowledge takes you much further than it could have a few years ago. That’s not an argument against learning to code. It’s an argument for it.

“But what about those vibe coding people? They seem to be shipping things.” Some are. I’ll be honest about that.

The projects I’ve seen from pure vibe coders tend to be smaller, tend to follow well-trodden patterns, and often hit a ceiling when something goes slightly wrong or slightly off-piste. Which is fine for a side project. I just created a useful dashboard to help me organise my day the way I want to using this approach.

But it tells you something: the AI does the heavy lifting on the known stuff. The moment something needs genuine thinking, you need the human who knows what’s going on beneath the surface.

AI-Assisted Human Coding and Human-Assisted AI Coding

Most serious work right now is a partnership.

Sometimes it’s AI-assisted human coding. The human drives, AI assists.

Sometimes it’s human-assisted AI programming. The AI writes most of the code, but the human knows what to ask for, how to steer it toward good design, how to evaluate whether the output actually makes sense.

Even when the coding looks like it’s done by AI, the person prompting and reviewing it is generally an experienced programmer. They’ve learned enough Python to know what’s reasonable, what’s a red flag, and when the AI is confidently wrong.

I’ve been experimenting with agentic AI over the past few weeks. I’ve tackled side projects I’d never have had the time for before. I didn’t have the time to start then, let alone finish them. Some of that output will show up in other places — stay tuned! But not here. The Python Coding Stack is the place for my writing.

The Programming Mindset When Talking to AI Agents

Here’s one thing I noticed. Talking to AI agents isn’t like talking to humans. But it isn’t like talking to computers (a.k.a. programming) either.

You need both qualities at the same time.

You need the clarity and communication skills you’d use with a person — explaining context, setting direction, knowing what matters, using clear language.

And you need the precision you’d use when programming — no ambiguity, clear intent, structure.

A good programmer who’s also a good communicator is the best human to work with AI agents.

That’s not coincidental. The same thought habits that make you an effective programmer also make you an effective prompter and reviewer when AI is involved.

I’ll share some of the prompts I’m using in a future post and analyse them to discuss why I wrote what I wrote. Learning to code well gives you an unfair advantage in this new world.

There’s Never Been a Better Time to Learn Python

Here’s what I’ve convinced myself of after all this. There’s never been a better time to learn Python.

A few years ago, you needed to reach an intermediate-to-advanced level before you could do something genuinely useful with Python. The bar was high. Now, with AI assistance, the bar is lower. Less Python knowledge takes you further than ever.

What used to need expertise can now be explored with curiosity and a bit of intermediate-ish-level Python.

That’s not replacing deeper learning. It’s making the entry point more accessible. And once you’re in, you can go as deep as you want.

So yes, I’ll keep coding in Python. Sometimes with a bit of help from AI. Sometimes with a lot of help from AI.

And yes, I’ll keep writing about Python here, as I’ve always done.

The Fun Factor

Here’s the thing we don’t talk about enough when discussing programming. It’s fun. It’s challenging. It’s rewarding. It’s fulfilling. It’s stimulating. It keeps my brain active.

I code because I enjoy it. I’ll keep writing about Python because I enojoy that, too,, and because I find value in sharing here — for myself and, hopefully, for you too.

Normal service resumes here. More Python posts coming. And maybe, just maybe, some of the AI things I’m learning will make their way in, too.

Psst–did you know you can become a premium member to be a part of The Club? It would mean so much to me!

Subscribe now

Quick question:

Photo by Maksim Goncharenok

Join The Club, the exclusive area for paid subscribers for more Python posts, videos, a members’ forum, and more.

Subscribe now

You can also support this publication by making a one-off contribution of any amount you wish.

Support The Python Coding Stack

For more Python resources, you can also visit Real Python—you may even stumble on one of my own articles or courses there!

Also, are you interested in technical writing? You’d like to make your own writing more narrative, more engaging, more memorable? Have a look at Breaking the Rules.

And you can find out more about me at stephengruppetta.com

What happens when you write coffee.selling_price?

Sure, I know you know. The code returns the value of the .selling_price attribute. But what really happens behind the scenes?

Python operations rely on special methods. The dot you use to access attributes is no exception. But strange and weird things can happen when you use the dot.

Normally, the Product class determines what happens when you write coffee.selling_price. It checks whether the instance has a .selling_price attribute, typically by looking in its .__dict__ dictionary of attributes. If the instance doesn’t have this attribute, Python checks whether it’s a class attribute.

But sometimes the class doesn’t get to decide what happens when you write coffee.selling_price. The object in .selling_price could take control of the attribute lookup.

Let’s explore the weird and wonderful world of descriptors in Python. For such a long time, I struggled to understand descriptors. But, as with many topics, at some stage, everything clicks. The story makes sense. Hopefully, this article can help you make sense of descriptors.

But first, we’ll start with properties.

The Product Class

Let’s create a Product class to deal with products for sale in a shop:

You create a Product instance by providing a name, a cost price, and a selling price. There’s a data attribute for each of these values. There’s also a .profit_margin data attribute.

However, there’s a serious flaw in this code. Have you spotted it?

Let’s try it out:

This code outputs the following:

coffee.profit_margin=2.0

So far, so good. But now try the following update:

Here’s the output from this version:

coffee.profit_margin=2.0

The profit margin still shows as £2. This is incorrect since you modified the selling price to £5.50 soon after creating the Product instance. The cost price is still £2.50. Therefore, the profit margin should be £3.

The .profit_margin data attribute is only calculated once in the .__init__() method, which is called when you create and initialise the object. The code doesn’t update the .profit_margin data attribute when you update the selling price.

You can choose to use a method instead of a data attribute, say .calculate_profit_margin(). However, you think the class’s interface would be neater and easier to use if .profit_margin were still a data attribute like .cost_price and .selling_price.

The solution is to create a property. I promise that this is related to this week’s topic – properties are a great stepping stone towards descriptors:

You start by creating a method called .profit_margin(). Note how you name this in the style of a data attribute rather than a method – it describes data rather than an action. However, you use the decorator @property to create a property object.

Whenever you access the .profit_margin attribute, without the parentheses, Python calls the .profit_margin() method behind the scenes. Therefore, each time you access the attribute .profit_margin, which is now a property, Python calculates and returns the current value:

coffee.profit_margin=3.0

The .profit_margin attribute looks and feels like a data attribute but behaves like a method.

There’s another benefit in this case. This attribute is read-only:

You try to assign a new value to the .profit_margin attribute, but Python raises an error:

Traceback (most recent call last):
  ...
    coffee.profit_margin = 4
    ^^^^^^^^^^^^^^^^^^^^
AttributeError: property ‘profit_margin’ of 
    ‘Product’ object has no setter

In this case, this is the desired behaviour since a user shouldn’t be able to set the profit margin directly. It should be calculated from the cost price and the selling price.

Validating Prices

But let’s move to the central theme of this article. You want to add validation to the prices. For example, you want to ensure they can’t be below zero.

Let’s work on the cost price only for now. The following version won’t work for the same reason you saw earlier:

You add the validation in the .__init__() method. This will apply only to the initialisation process, not to any later changes to the cost price.

So, the validation works fine in this case:

This raises the exception:

Traceback (most recent call last):
  ...
ValueError: Cost price cannot be negative

However, the code won’t stop you from changing the cost price to a negative value later:

Here’s the output:

coffee.cost_price=-1

Solution? Create a property:

Note that I removed the validation code from the .__init__() method. The definition of the .cost_price data attribute in .__init__() has also gone.

But what do you include in the cost_price() method? Unlike the .profit_margin property, which can be calculated from existing attributes, you still need somewhere to store the current value for the cost price. You still need a data attribute that you create in the .__init__() method.

You can create a non-public data attribute:

The data attribute ._cost_price has a leading underscore, which is a Python convention indicating that the user shouldn’t access this attribute directly. Python doesn’t prevent the user from accessing this non-public attribute, but the leading underscore shows the programmer’s intent that this attribute should be left alone when using the class.

Whenever you access the .cost_price property, Python executes the code you define in the method that you decorate with the @property decorator. In this case, Python returns the value of the ._cost_price data attribute.

Therefore, you still have a data attribute – the one with the leading underscore. However, the user doesn’t access it directly. Instead, they access it through the property .cost_price:

Here’s the output from this code:

coffee.cost_price=2.5

However, this makes the cost price read-only. That’s not what you’re trying to achieve:

This raises an error since you can’t assign values to the .cost_price property:

Traceback (most recent call last):
  ...
    coffee.cost_price = 3
    ^^^^^^^^^^^^^^^^^
AttributeError: property ‘cost_price’ of 
    ‘Product’ object has no setter

Note what the error message says: 'Product' object has no setter. The setter is the method that allows you to set the value of a property. But you can add this setter to your code:

There are no issues with setting the value for coffee.cost_price now that you have a setter, too. And the validation works when you try to set the cost price value to a negative value:

This raises an error:

Traceback (most recent call last):
  ...
    coffee.cost_price = -3
    ^^^^^^^^^^^^^^^^^
ValueError: Cost price cannot be negative

However, there’s still a flaw in this code. The negative cost price validation still fails in some circumstances. Can you figure out when it fails?

Try this code:

Here’s the output:

coffee.cost_price=-2.5

Validation occurs only when you set the cost_price attribute. However, look carefully at the code in your .__init__() method. It still sets the actual data attribute ._cost_price directly. This bypasses the verification.

Luckily, there’s an easy fix:

You can use the property in the .__init__() method, too. This triggers the property’s setter, which creates the ._cost_price data attribute and stores the value in it.

Avoiding float for prices

Let’s add a bit more to the validation code. It’s best not to use float when dealing with prices since floats suffer from rounding errors, which may lead to issues when dealing with money (especially if the rounding goes against you!)

Here’s the classic example showing the floating-point rounding errors:

Some floats cannot be represented precisely in binary, leading to rounding errors.

One option is to work in cents or pence or whatever the smaller unit of the currency you’re using. This means you’re working with integers. However, an alternative is to use decimal.Decimal instead:

Note that you should pass the floats as strings to Decimal and let the Decimal class deal with that. If you use float objects, you’ve already included the rounding errors in your starting value!

Let’s make sure the cost price uses Decimal internally without forcing the user to use this data type:

In true duck typing fashion, rather than choosing which data types you’re willing to accept when setting the cost price, you try to convert the input value to Decimal. Any data type that can be converted to Decimal is acceptable. The Decimal type raises an InvalidOperation exception, defined within decimal, when you pass an unacceptable type. So, you use InvalidOperation in the except block.

You probably want to perform the same validation for the selling price, too:

This works. However, there’s a lot of boilerplate code. And the validation is repeated in two setter methods. Sure, you can create a helper function to avoid the repetition. But what if you had more types of prices to include in your class? Perhaps there’s a wholesale_price and a discounted_price, say. You’d have to create properties for each one.

Before I move on from properties, here’s a link to another article I wrote about properties: The Properties of Python’s property .

Now let’s explore a different option.

Descriptors

Spoiler alert: you’ve already been using descriptors. Python’s property uses the descriptor protocol behind the scenes. Indeed, you use descriptors each time you access a method, or when you use the @classmethod and @staticmethod decorators.

But let’s get back to what happens when you use the dot after an object name, such as coffee.cost_price. The quick answer often states that Python looks at the instance’s .__dict__ attribute, which is a dictionary containing the instance’s data attributes. If the attribute is not there, Python looks in the class’s .__dict__ to check whether the attribute is a class attribute.

However, there’s a bit more happening.

The . notation calls the .__getattribute__() special method, which looks for the attribute using a broader set of rules and priorities.

The first thing it looks for is whether the attribute is a descriptor – technically, a data descriptor.

But what’s a descriptor?

Creating a descriptor class

Let’s create one. Create a Price class:

An object that has either of these special methods is a descriptor. (Note that there’s another special method that’s part of the descriptor protocol, .__delete__(), which is also sufficient to create a descriptor. I won’t be discussing .__delete__() in this article.)

So what? This is where descriptors start getting weird – yes, right at the start! Let’s pause with this class and get back to the Product class. Define .cost_price and .selling_price as class attributes and assign instances of the new Price class to them:

The rest of the code remains the same except that four methods are gone. These are the getter and setter methods you had defined previously to ensure that .cost_price and .selling_price are properties. You no longer need them. You’ll see why soon.

Why define class attributes? Class attributes are created when you define the class, unlike instance attributes, which are created when you create instances. Therefore, the attributes .cost_price and .selling_price exist and are equal to instances of a descriptor class at the time of class definition. This matters, as you’ll also see shortly.

So, what’s special about descriptors? Remember when we discussed how the . triggers the .__getattribute__() special method, which is responsible for looking for the attribute and returning its value? Well, as it happens, Python doesn’t look in the instance’s .__dict__ attribute first, after all.

The first thing it checks is whether the attribute is a descriptor. More specifically, it checks whether the attribute is a data descriptor, which is a descriptor that has .__set__() or .__delete__(). But our descriptor class, Price, has a .__set__(), so this priority applies to a Price object.

Here’s the key to understanding descriptors:

Since .cost_price and .selling_price are descriptors, the Product class defers to the Price class to decide how to get or set a value for this attribute.

Let me repeat that.

Normally, the class that defines an instance determines its behaviour. The special methods in Product determine how a Product instance behaves, such as what its string representations are, whether it’s iterable, whether it has a length, and so on. We haven’t defined any of these special methods in Product, but if we did, they would determine the object’s behaviour in those contexts.

However, when you use the dot on an instance of a Product class, if the attribute you’re accessing is a descriptor, such as .cost_price and .selling_price, it’s Price.__get__() and Price.__set__() that determine what to do when you get or set the values of .cost_price and .selling_price.

Code in the Price class determines what happens when you access an attribute in a Product instance.

And since you define .cost_price and .selling_price as class attributes that contain descriptors – instances of Price – then the descriptor special methods kick in even in Product.__init__() when you write self.cost_price = cost_price and self.selling_price = selling_price.

Understanding how descriptors work

Let’s prove this by adding some code to the Price class. This code is here to let us track what’s happening. You’ll write “proper” code later:

The .__get__() and .__set__() methods print out phrases to allow you to see when these methods are called. The .__get__() special method also returns a string. A reminder that these special methods are defined in the Price class.

Here’s the code so far, which includes a statement in the main scope that creates an instance of the Product class:

Here’s what you see when you run this code:

Calling Price.__set__()
Calling Price.__set__()

The code calls the Price.__set__() method twice: once when creating self.cost_price and another time when creating self.selling_price in Product.__init__().

Let’s also fetch one of the attributes:

Here’s the output from this code:

Calling Price.__set__()
Calling Price.__set__()
Calling Price.__get__()
Price coming soon...

You still get the two “breadcrumbs” that show that the code called Price.__set__() twice. But now you can also see that the code calls Price.__get__() since you wrote print(coffee.selling_price). And when you access the .selling_price attribute, Python returns the value returned by Price.__get__(), which is the string saying "Price coming soon...".

Therefore, attribute access for .selling_price and .cost_price, which are attributes in Product, is now controlled by the Price class, which is the descriptor class.

Yes, the Price class has taken over control of attribute access in the Product class (but only for the attributes that are descriptors of the Price class, .cost_price and .selling_price.)

Let’s look at the signatures of the .__get__() and .__set__() special methods to figure out how they work. Let’s focus on .__get__() first. Here’s the method’s signature and a few more printouts to help us figure out what’s what:

There are three parameters defined in the signature for .__get__(). You won’t be surprised to see self as the first parameter, which is the case for all instance methods in classes. There are also two other parameters named instance and owner. Let’s figure out what they are.

You’ve seen earlier that the current code calls .__get__() once when the code evaluates coffee.selling_price, which you use as an argument for print(). Here’s the output of the code now:

Calling Price.__set__()
Calling Price.__set__()
Calling Price.__get__()
self=<__main__.Price object at 0x100bc8f50>
instance=<__main__.Product object at 0x100bd9160>
owner=<class ‘__main__.Product’>
Price coming soon...

The new additions are the printouts on the fourth, fifth, and sixth lines showing the values assigned to the parameters self, instance, and owner in Price.__get__(). First, a reminder that this method is triggered when you run the following expression:

Here’s what the outputs for the three parameters show:

• self=<__main__.Price object ...>: Therefore, self refers to the instance of the Price class itself, as self always does in classes. This is the descriptor instance. It’s the same descriptor object the attribute coffee.selling_price invokes (but not the object that coffee.selling_price returns, as you’ll see soon.)

• instance=<__main__.Product object ...>: This output shows that instance is an object of type Product. It’s the object that has the descriptor as one of its attributes. In this example, this is the coffee object.

• owner=<__main__.Product>: This is the Product class itself (not an instance of the class).

Therefore, in the expression coffee.selling_price, coffee is the Product instance and .selling_price is the Price instance, which is the descriptor.

And when Python evaluates the expression coffee.selling_price, it defers the decision of which value to display to the Price class. Python calls Price.__get__() with the following arguments:

• The selling_price descriptor is passed to self

• The coffee object, an instance of Product, is passed to instance

• The Product class is passed to owner

I’ve repeated myself in the previous few paragraphs, but that’s deliberate. I get confused following the flow from the Product class to calling a method in the descriptor class, Price. I need this repetition. Maybe it helps you, too.

As a side note, which I’ll mostly ignore in this article: It’s possible to call the descriptor using the class rather than an instance, such as the following:

Here’s the output from this code:

Calling Price.__get__()
self=<__main__.Price object at 0x102a79090>
instance=None
owner=<class ‘__main__.Product’>
Price coming soon...

In this case, None is assigned to instance since there’s no Product instance involved.

Let’s look at the .__set__() special method now:

The signature still includes self and instance, and these refer to the same objects as they did in .__get__(). The third parameter is value, which stores the object you want to use when setting the attribute’s value. Let’s focus on creating an instance of Product as you did earlier:

This code accesses descriptors using the dot notation twice within Product.__init__() since it sets the values of .cost_price and .selling_price, which contain Price objects. Here’s the output from this code:

Calling Price.__set__()
self=<__main__.Price object at 0x104cf5010>
instance=<__main__.Product object at 0x104cf5160>
value=3.2

Calling Price.__set__()
self=<__main__.Price object at 0x104ce4f50>
instance=<__main__.Product object at 0x104cf5160>
value=5

The two calls are triggered by two different descriptors, .cost_price and .selling_price. Therefore, self refers to different objects in these calls, as you can see from the different identity values displayed.

However, the descriptors belong to the same instance, the Product object you named coffee. You can see that the printout references the same Product object on both occasions.

The value is the number you’re trying to assign to the descriptors.

Writing the .__get__() and .__set__() methods

Now you know how and when Python calls the .__get__() and .__set__() methods, you can add code within them. You can use the same reasoning you used when creating properties earlier.

To keep track of what’s happening, let’s build the code you need in stages.

First, let’s focus exclusively on the .cost_price attribute. You’ll write the validation as if it’s just for cost price — and you’ll soon see why that breaks once selling price joins the party. You’ll deal with .selling_price later.

You can use the same validation code you used earlier when working with properties. This code should now go in the .__set__() method within the Price class:

Let’s see what’s new in this version:

1. I removed most of the print() calls, which were useful merely to explore what objects are passed to these special methods. I left the ones showing when the code calls these methods for now.

2. The .__set__() method includes the try..except block, which ensures the value is a Decimal, and the if statement, which checks that the value is not negative.

3. The final line in .__set__() sets the ._cost_price attribute in the instance object, using the value in value. The function call setattr(instance, "_cost_price", value) is equivalent to instance._cost_price = value. In this case, instance is the Product object, such as coffee. There’s a good reason to use the setattr() built-in function rather than assigning the value directly using the dot notation. You’ll find out later when you also deal with the selling price.
   Note that you use the leading underscore in "_cost_price" since you wish to create the non-public attribute ._cost_price rather than assign the value to the .cost_price attribute (the one without the leading underscore).

Let’s try this out. Note that this code is hard-coded to work only for the .cost_price attribute for now:

Oops! This doesn’t work:

Calling Price.__set__()
Calling Price.__set__()
Calling Price.__get__()
None

The final line shows that the code outputs None. That’s because coffee.cost_price triggers the Price.__get__() method, which you haven’t completed yet! You can still check whether we’re on track by printing the actual data attribute ._cost_price:

You should avoid accessing non-public attributes outside of the class definition in general. But I give you permission to break the rule here since we’re merely exploring what’s happening behind the scenes!

Calling Price.__set__()
Calling Price.__set__()
5

Note how there’s no printout saying "Calling Price.__get__()" now since you’re accessing the data attribute ._cost_price, not the descriptor .cost_price.

But did you notice that this still shows the wrong value? The cost price should be £3.20. It’s the selling price that’s £5.00. Remember how you’re hard-coding the string "_cost_price" in the call to setattr()? This means that when you try to set the selling price, the code currently overwrites the cost price. But don’t worry, we’ll fix this soon.

Time to focus on .__get__(). Since you created the non-public data attribute ._cost_price when setting the value using .__set__(), you can now get the value of that attribute using getattr():

Recall that in .__get__(), the parameter instance refers to the Product instance, such as coffee. Therefore, getattr(instance, "_cost_price") is equivalent to coffee._cost_price in this example.

Let’s try this out, this time using the .cost_price descriptor directly when accessing the value of the cost price:

Here’s the output showing all the breadcrumbs confirming that two attributes are set and that you fetch the value of one of them once. The output also shows the value of the attribute, which is still wrong since £5 is the selling price:

Calling Price.__set__()
Calling Price.__set__()
Calling Price.__get__()
5

We’ll soon stop the selling price from overwriting the cost price.

But first, let’s check that the validation logic works:

This raises an error:

Traceback (most recent call last):
  ... in <module>
    coffee = Product(”Espresso”, -3.2, 5)
  ... in Product.__init__
    self.cost_price = cost_price
    ^^^^^^^^^^^^^^^
  ... in Price.__set__
    raise ValueError(f”’cost_price’ can’t be less than zero”)
    
ValueError: ‘cost_price’ can’t be less than zero

And so does this:

This time, the error message is different:

...
TypeError: Invalid format for ‘cost_price’: three point two

Another minor note for completeness’s sake. We mentioned that you can call the descriptor through the class, such as Product.cost_price. Since instance is None in this case, the code in .__get__() raises an error since None doesn’t have a ._cost_price attribute (or any attribute, for that matter!) To account for this, you can add the following code in .__get__():

If you call the descriptor from a class, you just get the descriptor back. There’s no instance, so there’s no value to fetch in this case! But let’s move on…

Your call…

The Python Coding Place offers something for everyone:

• a super-personalised one-to-one 6-month mentoring option
$ 4,750

• individual one-to-one sessions
$ 125

• a self-led route with access to 60+ hrs of exceptional video courses and a support forum
$ 400

Which The Python Coding Place student are you?

Making a general descriptor class

This works. But it only works for the .cost_price attribute since there are a few references to this attribute hard-coded in the .__get__() and .__set__() methods:

1. You use the string "_cost_price" when calling getattr() and setattr().

2. You also refer to the attribute name 'cost_price' in the error messages.

Hard-coding the cost price attribute names also has the undesirable effect of overwriting the cost price with the selling price!

Ideally, you’d like to access the public attribute name "cost_price" (the name of the descriptor) and the non-public data attribute name "_cost_price" dynamically. Recall that these are attributes in the Product class. Python passes the descriptor object self to the .__get__ and .__set__() methods, but not its attribute name within Product.

But descriptors can also deal with this problem. A descriptor allows you to pass the attribute name from the Product class to the Price class using .__set_name__() in the descriptor class:

I’ve put similar print() calls to the ones you used earlier to help us identify what’s what. Remove the code that creates the instance coffee, so that your module only defines the two classes, Price and Product, and nothing else. Run your script, and you’ll see this output:

Calling Price.__set_name__()
self=<__main__.Price object at 0x101bbcec0>
owner=<class ‘__main__.Product’>
name=’cost_price’

Calling Price.__set_name__()
self=<__main__.Price object at 0x101bacf50>
owner=<class ‘__main__.Product’>
name=’selling_price’

Python calls Price.__set_name__ when you create the descriptors within Product. Recall that you create the descriptors when you assign them to the class attributes. These attributes, and therefore the descriptors, are created when you define the Product class and not when you create Product instances.

As before, self refers to the descriptor object itself. The owner parameter still refers to the class in which the descriptors are defined, Product in this example.

Finally, name is a string containing the attribute name you use within the Product class. Therefore, name is either "cost_price" or "selling_price".

You can now use this name within code in the Price class. First, let’s tidy up the .__set_name__() method:

You create two instance attributes in the Price object to refer to the private and public names. You may recall that I mentioned Python prefers the term “non-public” over “private”. However, the Python documentation also occasionally uses the term “private”, including when discussing descriptors. It’s common to see .private_name used as the instance attribute within a descriptor. I’ll acquiesce.

Now, you can update the rest of the code:

You use self.private_name as an argument in getattr() and setattr() instead of the hard-coded string you had before. And you use self.public_name in the error messages. Note that I’ve also removed the breadcrumb calls to print() since we no longer need to show when Python calls each of these methods.

Let’s test:

You can set and get values, including within the .profit_margin property:

3.2
5
1.8

But you can’t set invalid values. Try coffee.cost_price = -2 and coffee.cost_price = "three point two" to confirm the validation code works.

Here’s the full code containing both classes:

How About Properties, Then?

You use a property for the .profit_margin attribute in Product. This is a simple read-only attribute you use to calculate the value each time you need the attribute. You could use properties for .selling_price and .cost_price, but there’s plenty of boilerplate code needed for each attribute. Annoying, especially if you need many price-related attributes in your class, not just cost and selling prices.

Descriptors allow you to put the validation logic into a separate class. And descriptors aren’t restricted to data validation. You can use descriptors whenever you need to execute any logic each time you get or set the value of an attribute. And you can use the Price descriptor elsewhere, too. It’s not restricted to the Product class.

But remember the property object? This is itself a descriptor. Here’s evidence of this:

This code returns True. The .profit_margin attribute is a property. It has the .__get__() special method, which is sufficient to make it a descriptor. A property is a descriptor.

Note that you’re accessing this property through the class name within hasattr(). Remember the code checking whether instance is None in .__get__()? You used the if instance is None: check to return the descriptor itself when you call the descriptor from a class. That’s why you can introspect the descriptor through Product.profit_margin. But don’t worry too much about this detail!

Final Words

How often have you used a method, such as in this case?

Millions of times, you say? You may already be aware that this call to the .append() method is similar to this more verbose version:

In this version, you use append() as a function. It’s a function that’s an attribute of the list class. Therefore, you pass the object as its first argument – this is the object that is assigned to the first parameter self in the append() signature.

Well, as it happens, Python uses the descriptor protocol to automatically equate numbers.append(30) to the function call list.append(numbers, 30).

Functions are objects. And function objects are descriptors in Python. When you access them through an instance of a class, such as in numbers.append(30), Python goes through the function’s .__get__() method and calls list.append(numbers, 30) so that you don’t have to worry about it:

Functions have a .__get__() method, which makes them descriptors. Since you can’t set the value for a function object, they don’t have a .__set__() method. Descriptors that only have a .__get__() special method, such as functions, are non-data descriptors. Non-data descriptors don’t get the same precedence as data descriptors when Python is figuring out what to do when you use the dot notation. But that’s a topic for another day…

As with many topics, learning about descriptors helps you learn about descriptors (duh!), but it also helps you understand Python better.

So, descriptors are a useful tool whenever you want to perform additional tasks, such as validation, whenever you get or set the value of an attribute. What makes them a bit weird until you get used to them is that the logic is defined in the descriptor class itself. The benefit of this is that you can use descriptors across many classes and rely on the same logic, without having to define that logic in each class.

For example, you can use Price() objects, which are descriptors, in any class where you need to use prices and apply the same validation you defined in this article. And you can add functions to any class safe in the knowledge that the descriptor protocol will ensure they’re treated as instance methods when they’re accessed (unless you use the @classmethod or @staticmethod decorators, which – you guessed it – also use the descriptor protocol to perform their magic.)

In summary, a descriptor is an object that hijacks the attribute access process triggered by the dot notation. Normally, when you access an attribute of an object, the object’s class deals with finding the value. However, when the attribute is a descriptor, the descriptor class takes over.

Did you enjoy this article? Did you understand how descriptors work? That’s not an easy feat!

Do you want to become a premium subscriber and join The Club to help support this publication and ensure there are more articles like this one?

Subscribe now

Photo by Ej Agumbay

Code in this article uses Python 3.14

The code images used in this article are created using Snappify. [Affiliate link]

For more Python resources, you can also visit Real Python—you may even stumble on one of my own articles or courses there!

Also, are you interested in technical writing? You’d like to make your own writing more narrative, more engaging, more memorable? Have a look at Breaking the Rules.

And you can find out more about me at stephengruppetta.com

Further reading related to this article’s topic:

• The Properties of Python’s property

Appendix: Code Blocks

Code Block #1

class Product:
    def __init__(self, name, cost_price, selling_price):
        self.name = name
        self.cost_price = cost_price
        self.selling_price = selling_price
        self.profit_margin = self.selling_price - self.cost_price

Code Block #2

# ...
coffee = Product("Espresso", 2.5, 4.5)
print(f"{coffee.profit_margin=}")

Code Block #3

# ...
coffee = Product("Espresso", 2.5, 4.5)
coffee.selling_price = 5.5
print(f"{coffee.profit_margin=}")

Code Block #4

class Product:
    def __init__(self, name, cost_price, selling_price):
        self.name = name
        self.cost_price = cost_price
        self.selling_price = selling_price

    @property
    def profit_margin(self):
        return self.selling_price - self.cost_price

coffee = Product("Espresso", 2.5, 4.5)
coffee.selling_price = 5.5
print(f"{coffee.profit_margin=}")

Code Block #5

# ...
coffee.profit_margin = 4

Code Block #6

class Product:
    def __init__(self, name, cost_price, selling_price):
        self.name = name
        if cost_price < 0:
            raise ValueError("Cost price cannot be negative")
        self.cost_price = cost_price
        self.selling_price = selling_price

    @property
    def profit_margin(self):
        return self.selling_price - self.cost_price
      
# ...

Code Block #7

# ...
coffee = Product("Espresso", -2.5, 4.5)

Code Block #8

# ...
coffee = Product("Espresso", 2.5, 4.5)  # Back to correct cost price
coffee.cost_price = -1
print(f"{coffee.cost_price=}")

Code Block #9

class Product:
    def __init__(self, name, cost_price, selling_price):
        self.name = name
        self.selling_price = selling_price
        
    @property
    def cost_price(self):
        # ???
        ...

    @property
    def profit_margin(self):
        return self.selling_price - self.cost_price
      
# ...

Code Block #10

class Product:
    def __init__(self, name, cost_price, selling_price):
        self.name = name
        self._cost_price = cost_price
        self.selling_price = selling_price

    @property
    def cost_price(self):
        return self._cost_price

    @property
    def profit_margin(self):
        return self.selling_price - self.cost_price
      
# ...

Code Block #11

# ...
coffee = Product("Espresso", 2.5, 4.5)
print(f"{coffee.cost_price=}")

Code Block #12

# ...
coffee = Product("Espresso", 2.5, 4.5)
coffee.cost_price = 3
print(f"{coffee.cost_price=}")

Code Block #13

class Product:
    def __init__(self, name, cost_price, selling_price):
        self.name = name
        self._cost_price = cost_price
        self.selling_price = selling_price

    @property
    def cost_price(self):
        return self._cost_price

    @cost_price.setter
    def cost_price(self, value):
        if value < 0:
            raise ValueError("Cost price cannot be negative")
        self._cost_price = value

    @property
    def profit_margin(self):
        return self.selling_price - self.cost_price

coffee = Product("Espresso", 2.5, 4.5)
coffee.cost_price = 3
print(f"{coffee.cost_price=}")

Code Block #14

# ...
coffee = Product("Espresso", 2.5, 4.5)
coffee.cost_price = -3
print(f"{coffee.cost_price=}")

Code Block #15

# ...
coffee = Product("Espresso", -2.5, 4.5)
print(f"{coffee.cost_price=}")

Code Block #16

class Product:
    def __init__(self, name, cost_price, selling_price):
        self.name = name
        self.cost_price = cost_price
        self.selling_price = selling_price

    @property
    def cost_price(self):
        return self._cost_price

    @cost_price.setter
    def cost_price(self, value):
        if value < 0:
            raise ValueError("Cost price cannot be negative")
        self._cost_price = value

    @property
    def profit_margin(self):
        return self.selling_price - self.cost_price
      
# ...

Code Block #17

0.1 + 0.2
# 0.30000000000000004

Code Block #18

from decimal import Decimal
Decimal("0.1") + Decimal("0.2")
# Decimal('0.3')

Code Block #19

from decimal import Decimal, InvalidOperation

class Product:
    def __init__(self, name, cost_price, selling_price):
        self.name = name
        self.cost_price = cost_price
        self.selling_price = selling_price

    @property
    def cost_price(self):
        return self._cost_price

    @cost_price.setter
    def cost_price(self, value):
        try:
            value = Decimal(str(value))
        except InvalidOperation:
            raise TypeError("Invalid format for cost price")
        if value < 0:
            raise ValueError("Cost price cannot be negative")
        self._cost_price = value

    @property
    def profit_margin(self):
        return self.selling_price - self.cost_price
      
# ...

Code Block #20

from decimal import Decimal, InvalidOperation

class Product:
    def __init__(self, name, cost_price, selling_price):
        self.name = name
        self.cost_price = cost_price
        self.selling_price = selling_price

    @property
    def cost_price(self):
        return self._cost_price

    @cost_price.setter
    def cost_price(self, value):
        try:
            value = Decimal(str(value))
        except InvalidOperation:
            raise TypeError("Invalid format for cost price")
        if value < 0:
            raise ValueError("Cost price cannot be negative")
        self._cost_price = value

    @property
    def selling_price(self):
        return self._selling_price

    @selling_price.setter
    def selling_price(self, value):
        try:
            value = Decimal(str(value))
        except InvalidOperation:
            raise TypeError("Invalid format for selling price")
        if value < 0:
            raise ValueError("Selling price cannot be negative")
        self._selling_price = value

    @property
    def profit_margin(self):
        return self.selling_price - self.cost_price

Code Block #21

# ...

class Price:
    """Descriptor to handle price validation and Decimal conversion."""
    
    def __get__(self, instance, owner):
        ...

    def __set__(self, instance, value):
        ...
        
# ...

Code Block #22

# ...

class Product:
    cost_price = Price()
    selling_price = Price()

    def __init__(self, name, cost_price, selling_price):
        self.name = name
        self.cost_price = cost_price
        self.selling_price = selling_price

    @property
    def profit_margin(self):
        return self.selling_price - self.cost_price

# ...

Code Block #23

# ...

class Price:
    def __get__(self, instance, owner):
        print("Calling Price.__get__()")
        return "Price coming soon..."

    def __set__(self, instance, value):
        print("Calling Price.__set__()")

# ...

Code Block #24

class Price:
    def __get__(self, instance, owner):
        print("Calling Price.__get__()")
        return "Price coming soon..."

    def __set__(self, instance, value):
        print("Calling Price.__set__()")

class Product:
    cost_price = Price()
    selling_price = Price()

    def __init__(self, name, cost_price, selling_price):
        self.name = name
        self.cost_price = cost_price
        self.selling_price = selling_price

    @property
    def profit_margin(self):
        return self.selling_price - self.cost_price


coffee = Product("Espresso", 3.2, 5)

Code Block #25

# ...
coffee = Product("Espresso", 3.2, 5)
print(coffee.selling_price)

Code Block #26

class Price:
    def __get__(self, instance, owner):
        print("Calling Price.__get__()")
        print(f"{self=}")
        print(f"{instance=}")
        print(f"{owner=}")
        return "Price coming soon..."
      
      # ...

Code Block #27

coffee.selling_price

Code Block #28

# ...
print(Product.selling_price)

Code Block #29

class Price:
    # ...

    def __set__(self, instance, value):
        print("Calling Price.__set__()")
        print(f"{self=}")
        print(f"{instance=}")
        print(f"{value=}")
# ...

Code Block #30

# ...
coffee = Product("Espresso", 3.2, 5)

Code Block #31

from decimal import Decimal, InvalidOperation

class Price:
    def __get__(self, instance, owner):
        print("Calling Price.__get__()")
        # more code coming soon here

    def __set__(self, instance, value):
        print("Calling Price.__set__()")
        try:
            value = Decimal(str(value))
        except InvalidOperation:
            raise TypeError(f"Invalid format for 'cost_price': {value}")

        if value < 0:
            raise ValueError(f"'cost_price' can't be less than zero")

        setattr(instance, "_cost_price", value)

# ...

Code Block #32

# ...

coffee = Product("Espresso", 3.2, 5)
print(coffee.cost_price)

Code Block #33

# ...

coffee = Product("Espresso", 3.2, 5)
print(coffee._cost_price)

Code Block #34

from decimal import Decimal, InvalidOperation

class Price:
    def __get__(self, instance, owner):
        print("Calling Price.__get__()")
        return getattr(instance, "_cost_price")

    def __set__(self, instance, value):
        print("Calling Price.__set__()")
        try:
            value = Decimal(str(value))
        except InvalidOperation:
            raise TypeError(f"Invalid format for 'cost_price': {value}")

        if value < 0:
            raise ValueError(f"'cost_price' can't be less than zero")

        setattr(instance, "_cost_price", value)

Code Block #35

# ...

coffee = Product("Espresso", 3.2, 5)
print(coffee.cost_price)

Code Block #36

# ...

coffee = Product("Espresso", -3.2, 5)

Code Block #37

# ...
coffee = Product("Espresso", "three point two", 5)

Code Block #38

from decimal import Decimal, InvalidOperation

class Price:
    def __get__(self, instance, owner):
        print("Calling Price.__get__()")
        if instance is None:
            return self
        return getattr(instance, "_cost_price")
    # ...

Code Block #39

from decimal import Decimal, InvalidOperation

class Price:
    def __set_name__(self, owner, name):
        print("Calling Price.__set_name__()")
        print(f"{self=}")
        print(f"{owner=}")
        print(f"{name=}")
        
		# ...

Code Block #40

from decimal import Decimal, InvalidOperation

class Price:
    def __set_name__(self, owner, name):
        print("Calling Price.__set_name__()")
        self.public_name = name
        self.private_name = f"_{name}"

# ...

Code Block #41

from decimal import Decimal, InvalidOperation

class Price:
    def __set_name__(self, owner, name):
        self.public_name = name
        self.private_name = f"_{name}"

    def __get__(self, instance, owner):
        if instance is None:
            return self
        return getattr(instance, self.private_name)

    def __set__(self, instance, value):
        try:
            value = Decimal(str(value))
        except InvalidOperation:
            raise TypeError(
                f"Invalid format for '{self.public_name}': {value}"
            )

        if value < 0:
            raise ValueError(
                f"'{self.public_name}' can't be less than zero"
            )

        setattr(instance, self.private_name, value)

# ...

Code Block #42

# ...
coffee = Product("Espresso", 3.2, 5)
print(coffee.cost_price)
print(coffee.selling_price)
print(coffee.profit_margin)

Code Block #43

from decimal import Decimal, InvalidOperation

class Price:
    def __set_name__(self, owner, name):
        self.public_name = name
        self.private_name = f"_{name}"

    def __get__(self, instance, owner):
        if instance is None:
            return self
        return getattr(instance, self.private_name)

    def __set__(self, instance, value):
        try:
            value = Decimal(str(value))
        except InvalidOperation:
            raise TypeError(
                f"Invalid format for '{self.public_name}': {value}"
            )

        if value < 0:
            raise ValueError(
                f"'{self.public_name}' can't be less than zero"
            )

        setattr(instance, self.private_name, value)

class Product:
    cost_price = Price()
    selling_price = Price()

    def __init__(self, name, cost_price, selling_price):
        self.name = name
        self.cost_price = cost_price
        self.selling_price = selling_price

    @property
    def profit_margin(self):
        return self.selling_price - self.cost_price

Code Block #44

# ...
print(hasattr(Product.profit_margin, "__get__"))

Code Block #45

numbers = [10, 20]
numbers.append(30)
numbers
# [10, 20, 30]

Code Block #46

numbers = [10, 20]
list.append(numbers, 30)
numbers
# [10, 20, 30]

Code Block #47

def some_function():
    ...
hasattr(some_function, "__get__")
# True
hasattr(some_function, "__set__")
# False

Join The Club, the exclusive area for paid subscribers for more Python posts, videos, a members’ forum, and more.

Subscribe now

You can also support this publication by making a one-off contribution of any amount you wish.

Support The Python Coding Stack

For more Python resources, you can also visit Real Python—you may even stumble on one of my own articles or courses there!

Also, are you interested in technical writing? You’d like to make your own writing more narrative, more engaging, more memorable? Have a look at Breaking the Rules.

And you can find out more about me at stephengruppetta.com

But today, I’ll write a short post about some tools I came across that may be interesting. I’ll keep the post short since, if you’re interested, you can easily explore the packages independently – you won’t need my explanatory efforts.

Remember some of the earliest code you ever wrote? It may have looked like this:

first = input(”Enter the first number: “)
second = input(”Enter the second number: “)
print(
    f”The sum of the two numbers is {float(first) + float(second)}”
)

Those days are long gone. But what if you wanted this code to work for any number of inputs, not just two?

I’m not talking about the code to work out the sum itself. You’d probably use a list to collect all the numbers and the sum() built-in function, or just use a running total. Whatever.

The annoying part is making user-friendly strings when asking for the input – it’s fine to write "first" and "second" when there are only two prompts – and then when showing the result, which currently says "two numbers". But what if you have more?

I came across this need several times, but my solution has always been to change the string so that it’s general enough to work in all cases. I’m lazy, I know.

In any case, recently I decided to look for solutions. And of course, they exist! Everything seems to exist in the Python ecosystem. Several solutions…

num2words

The first solution is probably the simplest: the num2words package doesn’t do much beyond converting numbers to words, as its name suggests. You’ll need to install num2words using pip, uv, or whatever you use to install packages.

>>> import num2words
>>> num2words.num2words(34)
‘thirty-four’

The main function in the num2words module is also called num2words(), as often happens with such modules!

How far can it go?

>>> num2words.num2words(5468.23)
‘five thousand, four hundred and sixty-eight point two three’

Working in Spanish?

>>> num2words.num2words(5468.23, lang=”es”)
‘cinco mil cuatrocientos sesenta y ocho punto dos tres’

Or Japanese?

>>> num2words.num2words(5468.23, lang=”ja”)
‘五千四百六十八点二三’

Read more

In this post, I’ll discuss the OOP mindset–or, let’s say, one way of viewing the object-oriented paradigm. I debated with myself whether to write this article here on The Python Coding Stack. Most articles here are aimed at the “intermediate-ish” Python programmer, whatever “intermediate” means. Most readers may feel they already understand the ethos and philosophy of OOP. I know I keep discovering new perspectives from time to time. So here’s a perspective I’ve been exploring in courses I ran recently.

As you can see, I decided to write this post. At worst, it serves as revision for some readers, perhaps a different route towards understanding why we (sometimes) define classes and (always) use objects in Python. And beginners read these articles, too!

If you feel you’re an OOP Pro, go ahead and skip this post. Or just read it anyway. It’s up to you. You can always catch up with anything you may have missed from The Python Coding Stack’s Archive instead – around 120 full-length articles and counting!

This post is inspired by the introduction to OOP in Chapter 7 in The Python Coding Book – The Relaxed and Friendly Programming Book for Beginners

Meet Mark, a market seller. He sets up a stall in his local market and sells tea, coffee, and home-made biscuits (aka cookies for those in North America).

I’ll write two and a half versions of the code Mark could use to keep track of his stock and sales. The first one–that’s the half–is not very pretty. Don’t write code like this. But it will serve as a starting point for the main theme of this post. The second version is a stepping stone towards the third.

First (Half) Version • Not Pretty

Mark is also learning Python in his free time. He starts writing some code:

He was planning to write some functions to update the stock, change the cost price and selling price, and deal with a sale from his market stall.

But he stopped.

We’ll also stop here with this version.

Mark is a Python beginner, but even he knew this was not the best way to store the relevant data for each product he sells.

Four separate objects? Not ideal. Mark knows that the data in these four lists are linked to each other. The first items in each list belong together, and so on. But he’ll need to manually ensure he maintains these links in the code he writes. Not impossible, but it’s asking for trouble. So many things can go wrong. And he’ll have a tough time writing the code, making all those links in every line he writes.

Mark knows what the link is between the various values. But the computer program doesn’t. The computer program sees four separate data structures, unrelated to each other. You can try writing an update_stock() function with this version to see the challenges, the manual work needed to connect data across separate structures.

Let’s move on.

Second Version • Dictionary and Functions

Mark learnt about dictionaries. They’re a great way to group data together:

Now there’s one data structure that contains the three products he sells. This structure contains three other data structures, each containing all the relevant data for each product.

The data are structured into these dictionaries to show what belongs where. In this version, the Python program “knows” which data items belong together. Each dictionary contains related values.

Well done, Mark! He understood the need to organise the data into a sensible structure. This is not the only combination of nested data structures Mark could use, but this is a valid option. Certainly better than the first version!

He can write some functions now. First up is update_stock():

Let’s ignore the fact that Mark is accessing the global variable products within the function. We’ll have a chat with Mark about this.

Still, there’s now a function called update_stock(). It needs the product name as an argument. It also needs the stock amount to increase (or decrease if the value is negative).

Let’s look at another function Mark wrote:

This function also needs the product name as one of its arguments. It also needs a second argument: the quantity sold.

Mark wrote other functions, but I’ll keep this section brief so I won’t show them. However, many of Mark’s functions have a few things in common:

• They require the product name as one of the arguments. This makes sense since the operations Mark needs to carry out depend on which product he’s dealing with.

• They make changes to the data in one of the inner dictionaries defined within products.

• Some of them return data. Others don’t.

Great. Mark is happy with his effort.

He structured the data sensibly so it’s well organised. Separately, he wrote functions that use data from those data structures–the inner dictionaries in products and sometimes make changes to the data in those data structures.

Your call…

The Python Coding Place offers something for everyone:

• a super-personalised one-to-one 6-month mentoring option
$ 4,750

• individual one-to-one sessions
$ 125

• a self-led route with access to 60+ hrs of exceptional video courses and a support forum
$ 400

Which The Python Coding Place student are you?

Third Version • Class and Objects

Mark’s code stores data. The nested dictionaries in products deal with the storage part. His code also does stuff* with the data through the functions he wrote.

*stuff is not quite a Python technical term, in case you’re wondering. But it’s quite suitable here, I think!

Lots of programs store data and do stuff with data.

Object-oriented programming takes these two separate tasks–storing data and doing stuff with data–and combines them into a single “unit”. In OOP, this “unit” is the object. Objects are at the centre of the OOP paradigm, which is why OOP is called OOP, after all!

1. Mark’s progression from the first version to the second relied on structuring the data into units–the nested dictionary structure.

2. The progression from the second version to the third takes this a step further and structures the data and the functions that act on those data into a single unit: the object.

This structure means that the data for each object is contained within the object, and the actions performed are also contained within that object. Everything is self-contained within the object.

Let’s build a Product class for Mark. But let’s do this step by step, using the code from the second version and gradually morphing it into object-oriented code. This will help us follow the transition.

First, let’s create the class:

Nothing much to see so far. But this is the shell that will contain all the instructions for creating this “unit,” including all the relevant data and functionality.

You can already create an instance of this class – that’s another way of saying an object created from this class:

Whereas Product represents the class, Product() is an instance of the class. Note the parentheses. There’s only one Product, but you can create many instances using Product() .

Bundling In the Functionality • Methods

Now, let me take a route I recently explored for the first time while teaching OOP in a beginners’ course. It’s only subtly different from my “usual” teaching route, but I think it helped me appreciate the topic from a distinct perspective. So, here we go.

Let’s copy and paste the functions from version two directly into this class. Warning: This won’t work. We’ll need to make some changes. But let’s use this as a starting point:

To keep you on your toes, we change the terminology here. These are functions. However, when they’re defined within a class definition, we call them methods. But they’re still functions. Everything you know about functions applies equally to methods.

You’ve seen that each function in version two needed to know which product it was dealing with. That’s why the first parameter is product_name. You used product_name to fetch the correct values when you needed the selling price, the cost price, or the number of items in stock.

However, now that we’re in the OOP domain, the object will contain all the data it needs–you’ll add the data-related code soon. You don’t need to fetch the data from anywhere else, just from the object itself.

Therefore, the functions defined within the class – the methods – no longer need the product name as the first argument. Instead, they need the entire object itself since this object contains all the data the method needs about the object.

We just need a parameter name to describe the object itself. How about self?

The method signatures now include self as the first parameter and whatever else the methods need as the remaining parameters.

Incidentally, although you can technically name this first parameter anything you want, there’s a strong convention to always use self. So it’s best to stick with self!

The methods are the tools you use to bundle functionality into the object. Let’s pause on working on the methods for now and shift our attention to how to store the data, which also needs to be bundled into the object.

Bundling In the Data • Data Attributes

Let’s get back to the code that creates an instance of the Product class:

The expression Product() does a few things behind the scenes. First, it creates a new blank object. Then it initialises this object. To initialise the object, Python needs to “do stuff”. Therefore, it needs a method. But not just any method. A special method:

You can’t choose the name of this method. It must be .__init__(). But it’s still a method. It still takes self as the first parameter since it still needs access to the object itself. This method creates variables that are attached to the object. You can think of the dot as attaching name to self and so on for the others. We tend not to call these variables – more new terminology just for the OOP paradigm – they’re data attributes. They’re object attributes that store data.

For now, these data attributes contain default values: the empty string for the .name data attribute and 0 for the others. However, when you create an object, you often want to supply some or all of the data that the object needs. Often, you want to pass this information when you create the object:

However, when you run the code, you get an error:

Traceback (most recent call last):
  ...
    a_product = Product(”Coffee”, 1.98, 3.2, 100)
TypeError: Product.__init__() takes 1 positional 
    argument but 5 were given

The error message mentions Product.__init__(). Note how you don’t explicitly use .__init__() in the expression to create a Product object. However, Python calls this special method behind the scenes. And when it does, it complains about the arguments you passed:

• "Product.__init__() takes 1 positional argument..." is the first part of the error message. Makes sense, since you have self as the one and only parameter within the definition of the .__init__() special method.

• "...but 5 [arguments] were given", the error message goes on to say. Wait, why 5? You pass four objects when you create Product(): the string "Coffee", the floats 1.98 and 3.2, and the integer 100. Python can’t count, it seems?

Not quite. When Python calls a method, it automatically passes the object as the first argument. You don’t see this. You don’t need to do anything about it. It happens behind the scenes. So, soon after Product() creates a blank new instance, it calls .__init__() and passes the object as the first argument to .__init__(), the one that’s assigned to the parameter self.

Recall that methods are functions. So, Python automatically passes the object as the first argument so that these functions (methods) have access to the object.

That’s why the error message says that five arguments were passed: the object itself and the four remaining arguments.

This tells you that .__init__() needs five parameters. The first is self, which is the first parameter in these methods. Let’s add the remaining four:

The code no longer raises an error since the number of arguments passed to Product() when you create the object – including the object itself, which is implied – matches the number of parameters in .__init__(). However, you want to shift the data into the data attributes you created earlier. These data attributes are the storage devices attached to the object. You want the data to be stored there:

The parameters are used only to transfer the data from the method call to the data attributes. From now on, the data are stored in the data attributes, which are attached to the object.

Note that the data attribute names don’t have to match the parameter names. But why bother coming up with different names? Might as well use the same ones!

Now, you can create any object you wish, each having its own data:

Here’s the output:

Coffee
Tea
3.2
2.25

Every instance of the Product class will have a .name, .cost_price, .selling_price, and .stock. But each instance will have its own values for those data attributes. Each object is distinct from the others. The data is self-contained within the object.

Back to the Functionality • Methods

Let’s look at the class so far, which still has code pasted from version two earlier:

Let’s focus on .update_stock() first. Note how in my writing style guide, I use a leading dot when writing method names, such as .update_stock(). That’s because they’re also attributes of the object. To call a method, you call it through the object, such as a_product.update_stock(30).

Recall that Python will pass the object itself as the first argument to the method. That’s the argument assigned to self. You then pass 30 to the parameter stock_increment.

But this means that this method can only act on an object that already exists, that already has the data attributes it needs. You no longer need to check whether the product exists. If you’re calling this method, you’re calling it on a product. Checks on existence will happen elsewhere in your code.

So, all that’s left is to increment the stock for this object. The current stock is stored in the .stock data attribute – the data attribute that’s connected to the object. But you passed the object to .update_stock(), so you can access self.stock from within the method:

And that’s it. Everything is self-contained within the object. The method acts on the object and modifies one of the object’s data attributes.

How about the .sell() method?

Again, you can remove the validation to check that the product exists. A method is called on a Product object, so it exists. This method then uses three of the object’s data attributes to perform its task.

Note that you can add similar validation in .update_stock() to ensure the stock doesn’t dip below 0. However, stock_increment can be negative to enable reducing the stock. You could even use .update_stock() within .sell() if you wish.

Ah, what about the biscuits? You can still use a list of products, but this time the list contains Product objects:

Or, if you prefer, you can use a dictionary:

Let’s trial out this dictionary and the Product class:

In this basic use case, you use the item input by the user to fetch the corresponding Product object from the products dictionary. You assign this object to the variable name product. Then you can call its methods, such as .sell(), and access its data attributes, such as .name and .stock.

Here’s the output from this code, including sample user inputs:

Enter item: coffee
Enter quantity of Coffee sold: 3
The income from this sale is £9.60
The profit from this sale is £3.66
Remaining Coffee units: 97

Final Words

The aim of this article is not to provide a comprehensive and exhaustive walkthrough of OOP. I wrote elsewhere about OOP. You can start from The Python Coding Book and then read the seven-part series A Magical Tour Through Object-Oriented Programming in Python • Hogwarts School of Codecraft and Algorithmancy.

You can learn about the syntax and the mechanics of defining and using classes. And that’s important if you want to write classes. But just as importantly, you need to adopt an OOP mindset. A central point is how OOP bundles data and functionality into a single unit, the object, and how everything stems from that structure.

In this post, you saw how data is bundled into the object through data attributes. And you bundled the high-level functionality that matters for your object through the methods .update_stock() and .sell(). Mark will need more of these methods, as you can imagine.

However, the object also includes low-level functionality. What should Python do when it needs to print the object? How about if it needs to add it to another object? Should that be possible? Should the object be considered False under any circumstance, say? These operations are defined by an object’s special methods, also known as dunder methods. I proposed thinking of these as “plumbing methods” recently: “Python’s Plumbing” Is Not As Flashy as “Magic Methods” • But Is It Better?

Therefore, there’s plenty of high-level and low-level functionality bundled within the object. And the data, of course.

Here’s another relatively recent post you may enjoy in case you missed it when it was published: My Life • The Autobiography of a Python Object.

In summary, OOP structures data and functionality into a single unit – the object. Then, your code is oriented around this object.

Photo by gomed fashion

Code in this article uses Python 3.14

The code images used in this article are created using Snappify. [Affiliate link]

Join The Club, the exclusive area for paid subscribers for more Python posts, videos, a members’ forum, and more.

Subscribe now

You can also support this publication by making a one-off contribution of any amount you wish.

Support The Python Coding Stack

For more Python resources, you can also visit Real Python—you may even stumble on one of my own articles or courses there!

Also, are you interested in technical writing? You’d like to make your own writing more narrative, more engaging, more memorable? Have a look at Breaking the Rules.

And you can find out more about me at stephengruppetta.com

Further reading related to this article’s topic:

• The Python Coding Book

• A Magical Tour Through Object-Oriented Programming in Python • Hogwarts School of Codecraft and Algorithmancy

• My Life • The Autobiography of a Python Object

Appendix: Code Blocks

Code Block #1

products = ["Coffee", "Tea", "Biscuits"]
cost_price = [1.98, 0.85, 3.1]
selling_price = [3.2, 2.25, 5]
stock = [100, 200, 25]

Code Block #2

products = {
    "Coffee": {
        "cost_price": 1.98,
        "selling_price": 3.2,
        "stock": 100,
    },
    "Tea": {
        "cost_price": 0.85,
        "selling_price": 2.25,
        "stock": 200,
    },
    "Biscuits": {
        "cost_price": 3.1,
        "selling_price": 5,
        "stock": 25,
    },
}

Code Block #3

# ...
def update_stock(product_name, stock_increment):
    if product_name not in products:
        raise KeyError(f"Product {product_name} not found")
    products[product_name]["stock"] += stock_increment
    # We'll need to have a chat with Mark about the issues
    # with accessing global variables from functions.
    # Let's let it pass here!

Code Block #4

# ...
def sell(product_name, quantity):
    if product_name not in products:
        raise KeyError(f"Product {product_name} not found")
    if quantity <= 0:
        raise ValueError("Quantity must be greater than zero")
    if products[product_name]["stock"] < quantity:
        raise ValueError("Not enough stock")
        
    products[product_name]["stock"] -= quantity
    selling_price = products[product_name]["selling_price"]
    cost_price = products[product_name]["cost_price"]

    income = selling_price * quantity
    profit = (selling_price - cost_price) * quantity

    return income, profit

Code Block #5

class Product:
    ...

Code Block #6

class Product:
    ...
    

a_product = Product()

Code Block #7

class Product:
    # Just pasting the functions from Version 2 here for now.
    # This still doesn't work. It's a work-in-progress
    def update_stock(product_name, stock_increment):
        if product_name not in products:
            raise KeyError(f"Product {product_name} not found")
        products[product_name]["stock"] += stock_increment
        # We'll need to have a chat with Mark about the issues
        # with accessing global variables from functions.
        # Let's let it pass here!

    def sell(product_name, quantity):
        if product_name not in products:
            raise KeyError(f"Product {product_name} not found")
        if quantity <= 0:
            raise ValueError("Quantity must be greater than zero")
        if products[product_name]["stock"] < quantity:
            raise ValueError("Not enough stock")

        products[product_name]["stock"] -= quantity
        selling_price = products[product_name]["selling_price"]
        cost_price = products[product_name]["cost_price"]

        income = selling_price * quantity
        profit = (selling_price - cost_price) * quantity

        return income, profit

Code Block #8

class Product:
    def update_stock(self, stock_increment):
        # rest of code pasted from version two (for now)

    def sell(self, quantity):
        # rest of code pasted from version two (for now)

Code Block #9

# ...

a_product = Product()

Code Block #10

class Product:
    # We'll make improvements to this method soon
    def __init__(self):
        self.name = ""
        self.cost_price = 0
        self.selling_price = 0
        self.stock = 0

Code Block #11

# ...

a_product = Product("Coffee", 1.98, 3.2, 100)

Code Block #12

class Product:
    def __init__(self, name, cost_price, selling_price, stock):
        self.name = ""
        self.cost_price = 0
        self.selling_price = 0
        self.stock = 0

Code Block #13

class Product:
    def __init__(self, name, cost_price, selling_price, stock):
        self.name = name
        self.cost_price = cost_price
        self.selling_price = selling_price
        self.stock = stock

Code Block #14

# ...

a_product = Product("Coffee", 1.98, 3.2, 100)
another_product = Product("Tea", 0.85, 2.25, 200)

print(a_product.name)
print(another_product.name)

print(a_product.selling_price)
print(another_product.selling_price)

Code Block #15

class Product:
    def __init__(self, name, cost_price, selling_price, stock):
        self.name = name
        self.cost_price = cost_price
        self.selling_price = selling_price
        self.stock = stock

    # Just pasting the functions from Version 2 here for now.
    # This still doesn't work. It's a work-in-progress
    def update_stock(self, stock_increment):
        if product_name not in products:
            raise KeyError(f"Product {product_name} not found")
        products[product_name]["stock"] += stock_increment
        # We'll need to have a chat with Mark about the issues
        # with accessing global variables from functions.
        # Let's let it pass here!

    def sell(self, quantity):
        if product_name not in products:
            raise KeyError(f"Product {product_name} not found")
        if quantity <= 0:
            raise ValueError("Quantity must be greater than zero")
        if products[product_name]["stock"] < quantity:
            raise ValueError("Not enough stock")

        products[product_name]["stock"] -= quantity
        selling_price = products[product_name]["selling_price"]
        cost_price = products[product_name]["cost_price"]

        income = selling_price * quantity
        profit = (selling_price - cost_price) * quantity

        return income, profit

Code Block #16

# ...
    def update_stock(self, stock_increment):
        self.stock += stock_increment

Code Block #17

# ...
    def sell(self, quantity):
        if quantity <= 0:
            raise ValueError("Quantity must be greater than zero")
        if self.stock < quantity:
            raise ValueError("Not enough stock")

        self.stock -= quantity
        income = self.selling_price * quantity
        profit = (self.selling_price - self.cost_price) * quantity

        return income, profit

Code Block #18

# ...
products = [
    Product("Coffee", 1.98, 3.2, 100),
    Product("Tea", 0.85, 2.25, 200),
    Product("Biscuits", 3.1, 5, 25),
]

Code Block #19

products = {
    "Coffee": Product("Coffee", 1.98, 3.2, 100),
    "Tea": Product("Tea", 0.85, 2.25, 200),
    "Biscuits": Product("Biscuits", 3.1, 5, 25),
}

Code Block #20

# ...

# I've kept this demo code brief and simple, so it lacks
# verification and robustness. You can add this if you wish!

item = input("Enter item: ").title()
qty = int(input(f"Enter quantity of {item} sold: "))

product = products[item]
income, profit = product.sell(qty)

print(f"The income from this sale is £{income:.2f}")
print(f"The profit from this sale is £{profit:.2f}")

print(f"Remaining {product.name} units: {product.stock}")

For more Python resources, you can also visit Real Python—you may even stumble on one of my own articles or courses there!

Also, are you interested in technical writing? You’d like to make your own writing more narrative, more engaging, more memorable? Have a look at Breaking the Rules.

And you can find out more about me at stephengruppetta.com

Everything goes through special methods (dunder methods) in Python

Special methods are everywhere. However, you don’t see them. In fact, you’re not meant to use them directly unless you’re defining them within a class. They’re out of sight. But they keep everything moving smoothly in Python.

Here’s a short essay exploring where these special methods fit within Python.

Why Should I Care About Special Methods?

“Everything goes through special methods in Python.” I should probably preface the phrase with “almost”, but the phrase is already unwieldy as it is.

You want to display an object on the screen? Python looks for guidance in .__str__() or .__repr__().

You want to use the object in a for loop? Is it even possible? Python looks for .__iter__() to check whether it can iterate over the object and how.

Do you want to fetch an individual item from the object? If this makes sense for this object, then it will have a .__getitem__() special method.

How should Python interpret an object’s truthiness? There’s .__bool__() for that. Or .__len__()!

Ah, you’d like to add an object to another object. Does your object have a .__add__() special method?

I could go on. I’ll post links to articles that cover some of these special methods in more detail below.

I’m also running a two-hour workshop this Thursday, 26 February, called Python’s Plumbing • Dunder Methods and Python’s Hidden Interface

Book Workshops

Many operations you take for granted in your code are governed by special methods. Each class defines the special methods it needs, and Python knows how to handle instances of that class through those methods.

But let’s talk about different ways we refer to these special methods.

What’s In A Name?

These methods are called special methods. That’s their official name. These special methods have double underscores at the beginning and end of their names, such as .__init__(), .__str__(), and .__iter__(). This double-underscore notation led to the informal name “dunder methods”. And let’s face it, most people call them “dunder methods” instead of their actual name: “special methods.”

I often call them dunder methods, too. However, the term dunder merely describes the syntax, double underscore, so it doesn’t tell us much about what they do. The term special doesn’t tell us what they do, either, but it shows us they have a special role in Python.

There’s No Such Thing as Magic

Some people also call them magic methods. However, I avoid this term, and I discourage students from using it. It makes these methods look unnecessarily mysterious, perhaps difficult to understand because it’s all down to magic.

But there’s no such thing as magic (unless you’re Harry Potter). And the magic tricks we see from real-world “magicians” are just that – tricks. The magic dissolves away once you know how the trick works.

And if you’re learning Python, then you need to learn how to be a magician. You need to learn the “magic tricks.” Therefore, they’re no longer magic!

Python’s Plumbing (”Plumbing Methods”, Anyone?)

So, “special method” tells us that these methods are important, but it doesn’t tell us what they do. “Dunder method” describes the syntax. “Magic method” misleads us and doesn’t provide any useful insight.

How about “plumbing methods” then? Now, before anyone takes me too seriously, I’m saying this with my tongue firmly in my cheek. I’m not that foolish to suggest a new term for the whole Python community to adopt. And it’s not as flashy as “magic methods” or as cool as “dunder methods”. But bear with me…

Let’s explore the analogy, even if the term won’t catch on.

Disclaimer: I know very little about plumbing. But I think that’s OK for this essay!

There are pipes, valves, and other stuff carrying water (clean or otherwise) around your house. You know they’re there. You need them there. But you don’t see them.

You don’t think about these pipes unless you’re building the house – or unless the pipes are blocked or leaking.

The house’s plumbing keeps things running smoothly. Yet, it’s out of sight, and you don’t normally think about it. You take it for granted.

You see where I’m going, right?

Python’s special methods perform the same role. You don’t normally see them when coding since they’re called implicitly, behind the scenes. You do need to define the special methods you need when you’re defining the class, just like you’ll need to lay the pipes when building or modifying your house.

And if something goes wrong in your code, you may need to dive into how these dunder methods behave, just as when you have a leak and need to explore which pipe is responsible.

Good plumbing is reliable, predictable. Bad plumbing is asking for trouble. The same applies to the infrastructure you create through the special methods you define in classes.

So, there you go, they’re “plumbing methods”. This name tells us what they do!

I’m running a two-hour live workshop this Thursday called Python’s Plumbing • Dunder Methods and Python’s Hidden Interface. This is your last chance to join and I may not run this workshop again for a while.

This workshop is the first of three in the Python Behind the Scenes series. The other two workshops in the series are:

• #2 • Pythonic Iteration: Iterables, Iterators, itertools

• #3 • To Inherit or Not? Inheritance, Composition, Abstract Base Classes, and Protocols

Join all three, or pick and choose:

The Python Coding Stack

When "It Works" Is Not Good Enough • Live Workshops

You’ve been reading articles here on The Python Coding Stack. How about live workshops…

Read more

8 months ago · 1 like · 2 comments · Stephen Gruppetta

Book Workshops

Image by Pete Linforth from Pixabay

For more Python resources, you can also visit Real Python—you may even stumble on one of my own articles or courses there!

Also, are you interested in technical writing? You’d like to make your own writing more narrative, more engaging, more memorable? Have a look at Breaking the Rules.

And you can find out more about me at stephengruppetta.com

Further reading related to this article’s topic:

• This is part of a longer OOP series: Time for Something Special • Special Methods in Python Classes

• The Anatomy of a for Loop

• The Manor House, the Oak-Panelled Library, the Vending Machine, and Python’s __getitem__() [Part 1]

• And Now for Something New

• Why Do 5 + “5” and “5” + 5 Give Different Errors in Python? • Do You Know The Whole Story?

• My Life • The Autobiography of a Python Object

• Telling The Truthy

And in my 10+ years of teaching Python, I also preferred teaching LBYL to beginners and delaying EAFP until later.

But over the years, as I came to understand Python’s psyche better, I gradually shifted my programming style—and then, my teaching style, too.

So, what are LBYL and EAFP? And which one is more suited to Python?

Look Both Sides Before Crossing the Road

You should definitely look before you leap across a busy road…or any road, really. And programming also has a Look Before You Leap concept—that’s LBYL—when handling potential failure points in your code.

Let’s start by considering this basic example. You define a function that accepts a value and a list. The function adds the value to the list if the value is above a user-supplied threshold:

def add_value_above_threshold(value, threshold, data):
    if value >= threshold:
        data.append(value)

You can confirm this short code works as intended:

# ...
prices = []
add_value_above_threshold(12, 5, prices)
add_value_above_threshold(3, 5, prices)
add_value_above_threshold(9, 5, prices)
print(prices)

This code outputs the list with the two prices above the threshold:

[12, 9]

However, you want to ensure this can’t happen:

# ...
products = {}
add_value_above_threshold(12, 5, products)

Now, products is a dictionary, but add_value_above_threshold() was designed to work with lists and not dictionaries:

Traceback (most recent call last):
  ...
    add_value_above_threshold(12, 5, products)
    ~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^
  ...
    data.append(value)
    ^^^^^^^^^^^
AttributeError: ‘dict’ object has no attribute ‘append’

One option is the look before you leap (LBYL):

def add_value_above_threshold(value, threshold, data):
    if not isinstance(data, list):
        print(”Invalid format. ‘data’ must be a list”)
        return
    if value >= threshold:
        data.append(value)

Now, the function prints a warning when you pass a dictionary, and it doesn’t crash the program!

But this is too restrictive.

Let’s assume you decide to use a deque instead of a list:

from collections import deque
​
# ...
​
prices = deque()
add_value_above_threshold(12, 5, prices)
add_value_above_threshold(3, 5, prices)
add_value_above_threshold(9, 5, prices)
print(prices)

This code still complains that it wants a list and doesn’t play ball:

Invalid format. ‘data’ must be a list
Invalid format. ‘data’ must be a list
Invalid format. ‘data’ must be a list
deque([])

But there’s no reason why this code shouldn’t work since deque also has an .append() method.

You could change the call to isinstance() to include the deque data type—isinstance(data, list | deque)—but then there may be other data structures that are valid and can be used in this function. You don’t want to have to write them all.

If you’re well-versed with the categories of data structures—perhaps because you devoured the The Python Data Structure Categories Series—then you might conclude you need to check whether the object is a MutableSequence since all mutable sequences have an .append() method. You can import MutableSequence from collections.abc and use isinstance(data, MutableSequence). Now you’re fine to use lists, deques, or any other mutable sequence.

This version fits better with Python’s duck-typing philosophy. It doesn’t restrict the function to a limited number of data types but to a category of data types. This category is defined by what the data types can do. In duck typing, you care about what an object can do rather than what it is. You can read more about duck typing in Python in this post: When a Duck Calls Out • On Duck Typing and Callables in Python

However, you could still have other data types that have an .append() method but may not fully fit into the MutableSequence category. There’s no reason you should exclude those data types from working with your function.

Perhaps, you could use Python’s built-in hasattr() to check whether the object you pass has an .append() attribute. You’re now checking whether the object has the required attribute rather than what the object is.

But if you’re going through all this trouble, you can go a step further.

Just Go For It and See What Happens

Why not just run the line of code that includes data.append() and see what happens? Ah, but you don’t want the code to fail if you use the wrong data type—you only want to print a warning, say.

That’s where the try..except construct comes in:

def add_value_above_threshold(value, threshold, data):
    if value < threshold:  # inequality flipped to avoid nesting
        return
    try:
        data.append(value)
    except AttributeError:
        print(
            “Provided data structure does not support appending values.”
        )

This is the Easier to Ask for Forgiveness than Permission (EAFP) philosophy. Just try the code. If it doesn’t work, you can then deal with it in the except block. Now, this fits even more nicely with Python’s duck typing philosophy. You’re asking the program whether data can append a value. It doesn’t matter what data is–can it append a value?

You don’t have to think about all the valid data types or which category they fall into. And rather than checking whether the data type has the .append() attribute first, you just try to run the code and deal with the consequences later. That’s why it’s easier to ask for forgiveness than permission.

But don’t use this philosophy when crossing a busy road. Stick with “look before you leap” there!

Another Example Comparing LBYL and EAFP

Read more

And my reaction at first was: “So what?! This tool doesn’t do anything I couldn’t already do with other features in Python.”

So, why does itemgetter() exist?

But, before answering this question, let’s answer a more basic one…

What Does itemgetter() Do?

Read more

So we came up with a system, and I’m writing a Python program to implement it. We keep a list of meals we try out. Each family member assigns a score to each meal. Every Saturday, before we go to the supermarket for the weekly shop, we plan which meals we’ll cook on each day of the week. It’s not based solely on the preference ratings, of course, since my wife and I have the final say to ensure a good balance. Finally, the program provides us with the shopping list with the ingredients we need for all the week’s meals.

I know, we’ve reinvented the wheel. There are countless apps that do this. But the fun is in writing your own code to do exactly what you want.

I want to keep this article focussed on just one thing: alternative constructors using class methods. Therefore, I won’t go through the whole code in this post. Perhaps I’ll write about the full project in a future article.

So, here’s what you need to know to get our discussion started.

Setting the Scene • Outlining the Meal and WeeklyMealPlanner Classes

Let me outline two of the classes in my code. The first is the Meal class. This class – you guessed it – deals with each meal. Here’s the class’s .__init__() method:

The meal has a name so we can easily refer to it, so there’s a .name data attribute. And the meals I cook are different from the meals my wife cooks, which is why there’s a .person_cooking data attribute. This matters as on some days of the week, only one of us is available to prepare dinner, so this attribute becomes relevant!

There are also days when we have busy afternoons and evenings with children’s activities, so we need to cook a quick meal. The .quick_meal data attribute is a Boolean flag to help with planning for these hectic days.

Then there’s the .ingredients data attribute. You don’t need me to explain this one. And since each family member rates each meal, there’s a .ratings dictionary to keep track of the scores.

The class has more methods, such as add_ingredient(), remove_ingredient(), add_rating(), and more. There’s also code to save to and load from CSV and JSON files. But these are not necessary for today’s article, so I’ll leave them out.

There’s also a WeeklyMealPlanner class:

The ._meals data attribute is a dictionary with the days of the week as keys and Meal instances as values. It’s defined as a non-public attribute to be used with the read-only property .meals. The .meals property returns a shallow copy of the ._meals dictionary. This makes it safer as it’s harder for a user to make changes directly to this dictionary. The dictionary is modified only through methods within WeeklyMealPlanner. I’ve omitted the rest of the methods in this class as they’re not needed for this article.

You can read more about properties in Python in this article: The Properties of Python’s ‘property’

So, each time we try a new dish, we create a Meal object, and each family member rates it. This meal then goes into our collection of meals to choose from each week. On Saturday, we choose the meals we want for the week, put them in a WeeklyMealPlanner instance, and we’re almost ready to go…

At the Supermarket

Well, we’re almost ready to go to the supermarket at this point. So, here’s another class:

A ShoppingList object has an .ingredients data attribute. This attribute is a dictionary. The keys are the ingredients, and the values are the quantities needed for each ingredient. I’m also showing the .add_ingredient() method, which I’ll need later on. So, you can create an instance of ShoppingList in the usual way:

Then, you can add ingredients as needed. But this is annoying for us on a Saturday. Here’s why…

Do you want to master Python one article at a time? Then don’t miss out on the article in The Club which are exclusive to premium subscribers here on The Python Coding Stack

Subscribe now

Alternative Constructor

Before describing our Saturday problems, let’s briefly revisit what happens when you create an instance of a class. When you place parentheses after the class name, Python does two things: it creates a blank new object, and it initialises it. The creation of the new object almost always happens “behind the scenes”. The .__new__() method creates a new object, but you rarely need to override it. And the .__init__() method performs the object’s initialisation.

You can only have one .__init__() special method in a class. Does this mean there’s only one way to create an instance of a class?

Not quite, no. Although there’s no way to define more .__init__() methods, there are ways to create instances through different routes. The @singledispatchmethod decorator is a useful tool, but one I’ll discuss in a future post. Today, I want to talk about using class methods as alternative constructors.

Back to a typical Saturday in our household. We just finished choosing the seven dinners we plan to have this coming week, and we created a WeeklyMealPlanner instance. So we should now create a ShoppingList instance using ShoppingList() and then go through all the meals we chose, entering their ingredients.

Wouldn’t it be nice if we could just create a ShoppingList instance directly from the WeeklyMealPlanner instance? But that would require a different way to create an instance of ShoppingList.

Let’s define an alternative constructor, then:

There’s a new method called .from_meal_planner(). However, this is not an instance method. It doesn’t belong to an instance of the class. Instead, it belongs to the class directly. The @classmethod decorator tells Python to treat this method as a class method. Note that the first parameter in this method is not self, as with the usual (instance) methods. Instead, you use cls, which is the parameter name used by convention to refer to the class.

Whereas self in an instance method represents the instance of a class, cls represents the class directly. So, unlike instance methods, class methods don’t have access to the instance. Therefore, class methods don’t have access to instance attributes.

The first line of this method creates an instance of the class. Look at the expression cls(), which comes after the = operator. Recall that cls refers to the class. So, cls is the same as ShoppingList in this example. But adding parentheses after the class creates an instance. You assign this new instance to the local variable shopping_list. You use cls rather than ShoppingList to make the class more robust in case you choose to subclass it later.

Fast-forward to the end of this class method, and you’ll see that the method returns this new instance, shopping_list. However, it makes changes to the instance before returning it. The method fetches all the ingredients from each meal in the WeeklyMealPlanner instance and populates the .ingredients data attribute in the new ShoppingList instance.

In summary, the class method doesn’t have access to an instance through the self parameter. But since it has access to the class, the method uses the class to create a new instance and initialise it, adding steps to the standard .__init__() method.

Therefore, this class method creates and returns an instance of ShoppingList with its .ingredients data attribute populated with the ingredients you need for all the meals in the week.

You now have an alternative way of creating an instance of ShoppingList:

This class now has two ways to create instances. The standard one using ShoppingList() and the alternative one using ShoppingList.from_meal_planner(). It’s common for class methods used as alternative constructors to have names starting with from_*.

You can have as many alternative constructors as you need in a class.

Question: if it’s more useful to create a shopping list directly from the weekly meal planner, couldn’t you implement this logic directly in the .__init__() method? Yes, you could. But this would create a tight coupling between the two classes, ShoppingList and WeeklyMealPlanner. You can no longer use ShoppingList without an instance of WeeklyMealPlanner, and you can no longer easily create a blank ShoppingList instance.

Creating two constructors gives you the best of both worlds. ShoppingList is still flexible enough so you can use it as a standalone class or in conjunction with other classes in other projects. But you also have access to the alternative constructor ShoppingList.from_meal_planner() when you need it.

Alternative Constructors in the Wild

You may have already seen and used alternative constructors, perhaps without noticing.

Let’s consider dictionaries. The standard constructor is dict() – the name of the class followed by parentheses. As it happens, you have several options when using dict() – you can pass a mapping, or an iterable of pairs, or **kwargs. You can read more about these alternatives in this article: dict() is More Versatile Than You May Think.

But there’s another alternative constructor that doesn’t use the standard constructor dict() but still creates a dictionary. This is dict.fromkeys():

You can have a look at help(dict.fromkeys). You’ll see the documentation text refer to this method as a class method, just like the ShoppingList.from_meal_planner() class method you defined earlier.

And if you use the datetime module, you most certainly have used alternative constructors using class methods. The standard constructor when creating a datetime.datetime instance is the following:

However, there are several class methods you can use as alternative constructors:

Have a look at other datetime.datetime methods starting with from_.

Final Words

Python restricts you to defining only one .__init__() method. But there are still ways for you to create instances of a class through different routes. Class methods are a common way of creating alternative constructors for a class. You call them directly through the class and not through an instance of the class – ShoppingList.from_meal_planner(). The class method then creates an instance, modifies it as needed, and finally returns the customised instance.

Now, let me see what’s on tonight’s meal planner and, more importantly, whether it’s my turn to cook.

Photo by Katya Wolf

Code in this article uses Python 3.14

The code images used in this article are created using Snappify. [Affiliate link]

Join The Club, the exclusive area for paid subscribers for more Python posts, videos, a members’ forum, and more.

Subscribe now

You can also support this publication by making a one-off contribution of any amount you wish.

Support The Python Coding Stack

For more Python resources, you can also visit Real Python—you may even stumble on one of my own articles or courses there!

Also, are you interested in technical writing? You’d like to make your own writing more narrative, more engaging, more memorable? Have a look at Breaking the Rules.

And you can find out more about me at stephengruppetta.com

Further reading related to this article’s topic:

• The Properties of Python’s ‘property’

• dict() is More Versatile Than You May Think

Appendix: Code Blocks

Code Block #1

class Meal:
    def __init__(
            self,
            name,
            person_cooking,
            quick_meal=False,
    ):
        self.name = name
        self.person_cooking = person_cooking
        self.quick_meal = quick_meal
        self.ingredients = {}  # ingredient: quantity
        self.ratings = {}  # person: rating

    # ... more methods

Code Block #2

class WeeklyMealPlanner:
    def __init__(self):
        self._meals = {}  # day: Meal

    @property
    def meals(self):
        return dict(self._meals)

    # ... more methods

Code Block #3

class ShoppingList:
    def __init__(self):
        self.ingredients = {}  # ingredient: quantity

    def add_ingredient(self, ingredient, quantity=1):
        if ingredient in self.ingredients:
            self.ingredients[ingredient] += quantity
        else:
            self.ingredients[ingredient] = quantity
            
    # ... more methods

Code Block #4

ShoppingList()

Code Block #5

class ShoppingList:
    def __init__(self):
        self.ingredients = {}  # ingredient: quantity

    @classmethod
    def from_meal_planner(cls, meal_planner: WeeklyMealPlanner):
        shopping_list = cls()
        for meal in meal_planner.meals.values():
            if meal is None:
                continue
            for ingredient, quantity in meal.ingredients.items():
                shopping_list.add_ingredient(ingredient, quantity)
        return shopping_list

    def add_ingredient(self, ingredient, quantity=1):
        if ingredient in self.ingredients:
            self.ingredients[ingredient] += quantity
        else:
            self.ingredients[ingredient] = quantity

Code Block #6

# if my_weekly_planner is an instance of 'WeeklyMealPlanner', then...

shopping_list = ShoppingList.from_meal_planner(my_weekly_planner)

Code Block #7

dict.fromkeys(["James", "Bob", "Mary", "Jane"])
# {'James': None, 'Bob': None, 'Mary': None, 'Jane': None}

Code Block #8

import datetime
datetime.datetime(2026, 1, 30)
# datetime.datetime(2026, 1, 30, 0, 0)

Code Block #9

datetime.datetime.today()
# datetime.datetime(2026, 1, 30, 12, 54, 2, 243976)

datetime.datetime.fromisoformat("2026-01-30")
# datetime.datetime(2026, 1, 30, 0, 0)

For more Python resources, you can also visit Real Python—you may even stumble on one of my own articles or courses there!

Also, are you interested in technical writing? You’d like to make your own writing more narrative, more engaging, more memorable? Have a look at Breaking the Rules.

And you can find out more about me at stephengruppetta.com

“Ah, but there are immutable types.”

Sure, you can have an object that doesn’t change throughout its lifetime. But you can’t have a reference to it that’s guaranteed not to change. The identifier (variable name) you use to refer to this immutable type can easily switch to refer to something else.

“How about using all caps for the identifier. Doesn’t that make it a constant?”

No, it doesn’t. That’s just a convention you use to show your intent as a programmer that an identifier refers to a value that shouldn’t change. But nothing prevents that value from changing.

Here’s an all-uppercase identifier that refers to an immutable object:

The identifier is all caps. The object is a tuple, which is immutable. Recall that you don’t need parentheses to create a tuple—the comma is sufficient.

So, you use an all-uppercase identifier for an immutable object. But that doesn’t stop you from changing the value of FIXED_LOCATION:

Neither using an immutable object nor using uppercase identifiers prevents you from changing this value!

So, Python doesn’t have constants. But there are tools you can use to mimic constant behaviour depending on the use case you need. In this article I’ll explore one of these: Enums.

All The Python Coding Place video courses are included in a single, cost-effective bundle. The courses cover beginner and intermediate level courses, and you also get access to a members-only forum.

Get The All Courses Bundle

Jargon Corner: Enum is short for enumeration, and you’ll see why soon. But don’t confuse this with the built-in enumerate(), which does something else. See Parkruns, Python’s enumerate and zip, and Why Python Loops Are Different from Other Languages • [Note: This is a Club post] for more on enumerate().

Let’s revisit our friend Alex from an article from a short while ago: “AI Coffee” Grand Opening This Monday. This article explored the program Alex used in his new coffee shop and how the function signature changed over time to minimise confusion and errors when using it. It’s a fun article about all the various types and styles of parameters and arguments you can have in Python functions.

But it didn’t address another potential source of error when using this code. So let’s look at a simple version of the brew_coffee() function Alex used to serve his coffee-drinking customers:

When you call the function, you pass the coffee you want to this function:

And elsewhere in the code, these coffees are defined in a dictionary:

If you’ve written code like this in the past, you’ll know that it’s rather annoying—and error-prone—to keep using the strings with the coffee names wherever you need to refer to a specific coffee, such as when passing the coffees to brew_coffee().

The names of the coffees and the parameters that define them do not change. They’re constant. It’s a shame Python doesn’t have constants, you may think.

But it has enums…

The CoffeeType enum contains seven members. Each member has a name and a value. By convention, you use all-uppercase names for the members since they represent constants. And these enum members behave like constants:

When you attempt to reassign a value to a member, Python raises an exception:

Traceback (most recent call last):
  File ..., line 12, in <module>
    CoffeeType.ESPRESSO = 10
    ^^^^^^^^^^^^^^^^^^^
  ...
AttributeError: cannot reassign member ‘ESPRESSO’

The member names are also contained within the namespace of the Enum class—you use CoffeeType.ESPRESSO rather than just ESPRESSO outside the Enum class definition. So, you get autocomplete, refactor-friendly names, and fewer silent typos. With raw strings, "capuccino" (with a single “p”) can sneak into your code, and nothing complains until a customer is already waiting at the counter.

For these enum members to act as constants, their names must be unique. You can’t have the same name appear more than once:

You include ESPRESSO twice with different values. But this raises an exception:

Traceback (most recent call last):
  File ..., line 3, in <module>
    ...
    ESPRESSO = 8
    ^^^^^^^^
  ...
TypeError: ‘ESPRESSO’ already defined as 1

That’s good news. Otherwise, these enum members wouldn’t be very useful as constants.

However, you can have an alias. You can have more than one member sharing the same value:

The members MACCHIATO and ESPRESSO_MACCHIATO both have the value 4. Therefore, they represent the same item. They’re different names for the same coffee:

Note that Python always displays the first member associated with a value:

CoffeeType.MACCHIATO

The output says CoffeeType.MACCHIATO even though you pass CoffeeType.ESPRESSO_MACCHIATO to print().

Incidentally, if you don’t want to have aliases, you can use the @unique decorator when defining the enum class.

You can also access the name and value of an enum member:

Here’s the output from this code:

CoffeeType.ESPRESSO
ESPRESSO
1

The .name attribute is a string, and the .value attribute is an integer in this case:

Here’s the output when you display the types:

<enum ‘CoffeeType’>
<class ‘str’>
<class ‘int’>

You’ll often use integers as values for enum members—that’s why they’re called enumerations. But you don’t have to:

The values are now also strings:

CoffeeType.ESPRESSO
ESPRESSO
espresso

You can use these enum members instead of strings wherever you need to refer to each coffee type:

…and again when you call brew_coffee():

Now you have a safer, neater, and more robust way to handle the coffee types... and treat them as constants.

A Bit More • StrEnum and IntEnum

Let’s add some code to brew_coffee():

This version is almost fine. But here’s a small problem:

Brewing a CoffeeType.CORTADO with 30ml of coffee and 
    60ml of milk. Strength level: 2

The output displays CoffeeType.CORTADO since coffee_type refers to an enum member. You’d like the output to just show the name of the coffee! Of course, you can use the .value attribute any time you need to fetch the string.

However, to make your coding simpler and more readable, you can ensure that the enum members are also strings themselves without having to rely on one of their attributes. You can use StrEnum instead of Enum:

Members of a StrEnum also inherit all the string methods, such as:

You call the string method .title() directly on the StrEnum member:

Macchiato

There’s also an IntEnum that can be useful when you want your enum members to act as integers. Let’s replace the coffee strength values, which are currently integers, with IntEnum members:

You could use a standard Enum in this case. But using an IntEnum allows you to manipulate its members directly as integers should you need to do so. Here’s an example:

This code is equivalent to printing 3 + 1. You wouldn’t be able to do this with enums unless you use the .value attributes.

And A Couple More Things About Enums

Let’s explore a couple of other useful enum features before we wrap up this article.

An enum class is iterable. Here are all the coffee types in a for loop:

Note that CoffeeType is the class name. But it’s an enum (a StrEnum in this case), so it’s iterable:

Brewing a espresso with 30ml of coffee and 0ml of milk. Strength level: 3
Brewing a latte with 30ml of coffee and 150ml of milk. Strength level: 1
Brewing a cappuccino with 30ml of coffee and 100ml of milk. Strength level: 2
Brewing a macchiato with 30ml of coffee and 10ml of milk. Strength level: 3
Brewing a flat_white with 30ml of coffee and 120ml of milk. Strength level: 2
Brewing a ristretto with 20ml of coffee and 0ml of milk. Strength level: 4
Brewing a cortado with 30ml of coffee and 60ml of milk. Strength level: 2

I’ll let you sort out the text displayed to make sure you get ‘an espresso’ when brewing an espresso and to remove the underscore in the flat white!

And there will be times when you don’t care about the value of an enum member. You just want to use an enum to give your constants a consistent name. In this case, you can use the automatic value assignment:

Python assigns integers incrementally in the order you define the members for Enum classes. Note that these start from 1, not 0.

The same integers are used if you use IntEnum classes. However, when you use StrEnum classes, Python behaves differently since the values should be strings in this case:

The values are now the lowercase strings representing the members’ names.

Of course, the default values you get when you use auto() may be the values you need, after all. This is the case for both enums you created in this article, CoffeeType and CoffeeStrength :

Using auto() when appropriate makes it easier to write your code and expand it later if you need to add more enum members.

Final Words

You can get by without ever using enums. But there are many situations where you’d love to reach for a constant, and an enum will do just fine. Sure, Python doesn’t have constants. But it has enums!

Photo by Valeria Boltneva

Code in this article uses Python 3.14

The code images used in this article are created using Snappify. [Affiliate link]

Join The Club, the exclusive area for paid subscribers for more Python posts, videos, a members’ forum, and more.

Subscribe now

You can also support this publication by making a one-off contribution of any amount you wish.

Support The Python Coding Stack

For more Python resources, you can also visit Real Python—you may even stumble on one of my own articles or courses there!

Also, are you interested in technical writing? You’d like to make your own writing more narrative, more engaging, more memorable? Have a look at Breaking the Rules.

And you can find out more about me at stephengruppetta.com

Appendix: Code Blocks

Code Block #1

FIXED_LOCATION = 51.75, 0.34

Code Block #2

FIXED_LOCATION
# (51.75, 0.34)
FIXED_LOCATION = "Oops!"
FIXED_LOCATION
# 'Oops!'

Code Block #3

def brew_coffee(coffee_type):
    # Actual code goes here...
    # It's not relevant for this article

Code Block #4

brew_coffee("espresso")
brew_coffee("cappuccino")

Code Block #5

coffee_types = {
    "espresso": {"strength": 3, "coffee_amount": 30, "milk_amount": 0},
    "latte": {"strength": 1, "coffee_amount": 30, "milk_amount": 150},
    "cappuccino": {"strength": 2, "coffee_amount": 30, "milk_amount": 100},
    "macchiato": {"strength": 3, "coffee_amount": 30, "milk_amount": 10},
    "flat_white": {"strength": 2, "coffee_amount": 30, "milk_amount": 120},
    "ristretto": {"strength": 4, "coffee_amount": 20, "milk_amount": 0},
    "cortado": {"strength": 2, "coffee_amount": 30, "milk_amount": 60},
}

Code Block #6

from enum import Enum

class CoffeeType(Enum):
    ESPRESSO = 1
    LATTE = 2
    CAPPUCCINO = 3
    MACCHIATO = 4
    FLAT_WHITE = 5
    RISTRETTO = 6
    CORTADO = 7

Code Block #7

from enum import Enum

class CoffeeType(Enum):
    ESPRESSO = 1
    LATTE = 2
    CAPPUCCINO = 3
    MACCHIATO = 4
    FLAT_WHITE = 5
    RISTRETTO = 6
    CORTADO = 7

CoffeeType.ESPRESSO = 10

Code Block #8

from enum import Enum

class CoffeeType(Enum):
    ESPRESSO = 1
    LATTE = 2
    CAPPUCCINO = 3
    MACCHIATO = 4
    FLAT_WHITE = 5
    RISTRETTO = 6
    CORTADO = 7
    ESPRESSO = 8

Code Block #9

from enum import Enum

class CoffeeType(Enum):
    ESPRESSO = 1
    LATTE = 2
    CAPPUCCINO = 3
    MACCHIATO = 4
    FLAT_WHITE = 5
    RISTRETTO = 6
    CORTADO = 7
    ESPRESSO_MACCHIATO = 4

Code Block #10

print(CoffeeType.ESPRESSO_MACCHIATO)

Code Block #11

# ...
print(CoffeeType.ESPRESSO)
print(CoffeeType.ESPRESSO.name)
print(CoffeeType.ESPRESSO.value)

Code Block #12

# ...
print(type(CoffeeType.ESPRESSO))
print(type(CoffeeType.ESPRESSO.name))
print(type(CoffeeType.ESPRESSO.value))

Code Block #13

from enum import Enum

class CoffeeType(Enum):
    ESPRESSO = "espresso"
    LATTE = "latte"
    CAPPUCCINO = "cappuccino"
    MACCHIATO = "macchiato"
    FLAT_WHITE = "flat_white"
    RISTRETTO = "ristretto"
    CORTADO = "cortado"

print(CoffeeType.ESPRESSO)
print(CoffeeType.ESPRESSO.name)
print(CoffeeType.ESPRESSO.value)

Code Block #14

# ...
coffee_types = {
    CoffeeType.ESPRESSO: {"strength": 3, "coffee_amount": 30, "milk_amount": 0},
    CoffeeType.LATTE: {"strength": 1, "coffee_amount": 30, "milk_amount": 150},
    CoffeeType.CAPPUCCINO: {"strength": 2, "coffee_amount": 30, "milk_amount": 100},
    CoffeeType.MACCHIATO: {"strength": 3, "coffee_amount": 30, "milk_amount": 10},
    CoffeeType.FLAT_WHITE: {"strength": 2, "coffee_amount": 30, "milk_amount": 120},
    CoffeeType.RISTRETTO: {"strength": 4, "coffee_amount": 20, "milk_amount": 0},
    CoffeeType.CORTADO: {"strength": 2, "coffee_amount": 30, "milk_amount": 60},
}

Code Block #15

# ...
brew_coffee(CoffeeType.CORTADO)

Code Block #16

# ...

def brew_coffee(coffee_type):
    coffee_details = coffee_types.get(coffee_type)
    if not coffee_details:
        print("Unknown coffee type!")
        return
    print(
        f"Brewing a {coffee_type} "
        f"with {coffee_details['coffee_amount']}ml of coffee "
        f"and {coffee_details['milk_amount']}ml of milk. "
        f"Strength level: {coffee_details['strength']}"
    )

brew_coffee(CoffeeType.CORTADO)

Code Block #17

from enum import StrEnum

class CoffeeType(StrEnum):
    ESPRESSO = "espresso"
    LATTE = "latte"
    CAPPUCCINO = "cappuccino"
    MACCHIATO = "macchiato"
    FLAT_WHITE = "flat_white"
    RISTRETTO = "ristretto"
    CORTADO = "cortado"

# ...

def brew_coffee(coffee_type):
    coffee_details = coffee_types.get(coffee_type)
    if not coffee_details:
        print("Unknown coffee type!")
        return
    print(
        f"Brewing a {coffee_type} "
        f"with {coffee_details['coffee_amount']}ml of coffee "
        f"and {coffee_details['milk_amount']}ml of milk. "
        f"Strength level: {coffee_details['strength']}"
    )

brew_coffee(CoffeeType.CORTADO)

Code Block #18

print(CoffeeType.MACCHIATO.title())

Code Block #19

# ...

class CoffeeStrength(IntEnum):
    WEAK = 1
    MEDIUM = 2
    STRONG = 3
    EXTRA_STRONG = 4

coffee_types = {
    CoffeeType.ESPRESSO: {
      "strength": CoffeeStrength.STRONG, 
      "coffee_amount": 30, 
      "milk_amount": 0,
    },
    CoffeeType.LATTE: {
      "strength": CoffeeStrength.WEAK, 
      "coffee_amount": 30, 
      "milk_amount": 150,
    },
    CoffeeType.CAPPUCCINO: {
      "strength": CoffeeStrength.MEDIUM, 
      "coffee_amount": 30, 
      "milk_amount": 100,
    },
    # ... and so on...
}

# ...

Code Block #20

print(CoffeeStrength.STRONG + CoffeeStrength.WEAK)

Code Block #21

# ...

for coffee in CoffeeType:
    brew_coffee(coffee)

Code Block #22

from enum import Enum, auto
class Test(Enum):
    FIRST = auto()
    SECOND = auto()

Test.FIRST
# <Test.FIRST: 1>
Test.SECOND
# <Test.SECOND: 2>

Code Block #23

from enum import StrEnum, auto
class Test(StrEnum):
    FIRST = auto()
    SECOND = auto()
   
Test.FIRST
# <Test.FIRST: 'first'>
Test.SECOND
# <Test.SECOND: 'second'>

Code Block #24

# ...
class CoffeeType(StrEnum):
    ESPRESSO = auto()
    LATTE = auto()
    CAPPUCCINO = auto()
    MACCHIATO = auto()
    FLAT_WHITE = auto()
    RISTRETTO = auto()
    CORTADO = auto()

class CoffeeStrength(IntEnum):
    WEAK = auto()
    MEDIUM = auto()
    STRONG = auto()
    EXTRA_STRONG = auto()
# ...

For more Python resources, you can also visit Real Python—you may even stumble on one of my own articles or courses there!

Also, are you interested in technical writing? You’d like to make your own writing more narrative, more engaging, more memorable? Have a look at Breaking the Rules.

And you can find out more about me at stephengruppetta.com

And here’s how they deal with the finish line logistics. Runners don’t wear bibs with numbers. When they cross the finish line, they enter a “funnel” marked by plastic cones and are handed a token with their position number. They then proceed to another official, who scans their personal barcode, which runners carry in their pockets or on a wristband, and the position token they received a few seconds earlier. This process matches the runner with their finishing position.

What’s this got to do with Python loops? And how does it help us understand why Python does loops differently from other languages?

First step, let’s create the Parkrun funnel. I’ll just put the first five finishers in this example:

>>> funnel = [”Jonathan”, “Michael”, “Samantha”, “Jessica”, “Daniel”]

Now, here’s something you definitely know already because it’s always one of the first things you’re taught when learning Python: Don’t loop through this list like this:

# Avoid this when coding in Python
>>> i = 0
>>> while i < len(funnel):
...     name = funnel[i]
...     print(name)
...     i += 1
...    
Jonathan
Michael
Samantha
Jessica
Daniel

This style mimics how other languages may work: you manually define and increment the index. To be fair, most people who shift from other languages are more likely to write the following version at some point:

# Also best to avoid this in Python
>>> for i in range(len(funnel)):
...     name = funnel[i]
...     print(name)
...    
Jonathan
Michael
Samantha
Jessica
Daniel

This version may seem more Pythonic since it uses Python tools such as range(), but still fails to make the most of Python’s iteration protocol. The Pythonic way of looping through this list is the following:

>>> for name in funnel:
...     print(name)
...    
Jonathan
Michael
Samantha
Jessica
Daniel

A question that’s often asked but rarely answered is: Why is this version preferred over the other two? I’ll write another short post to answer this question soon as I want to keep these The Club posts short whenever possible. So, let me state just a few reasons (there are more) and then I’ll move on to my main topic for today.

• It’s more readable

• It’s more efficient (try timing the versions above using timeit—remove the print() calls first)

• It’s less prone to errors and bugs

• It works with a broader selection of data structures, not just sequences

While you wait for my follow-up post on this, you can read more about Python’s Iterator Protocol, iterables, and iterators here:

• The Anatomy of a for Loop

• Iterable: Python’s Stepping Stones

• A One-Way Stream of Data • Iterators in Python

But let’s move on.

Let’s say you want to print out the names alongside each runner’s position. You’d like the following output:

1. Jonathan
2. Michael
3. Samantha
4. Jessica
5. Daniel

“Aha!” I’m often told by some learners, “This is when you need to use the for i in range(len(funnel)) idiom, since you need the index!”

Python’s for loop doesn’t explicitly use the index, so you don’t have access to the index within the for loop. Many revert to the non-Pythonic idioms for this.

But Python provides tools that let you stay within the pure Pythonic style. Python’s for loop needs an iterator—it will create one from the iterable you provide. All Python iteration needs iterators, not just for loops. Iterators are Python’s tool for any iteration.

And there are some bespoke iterators in Python that handle most of your iteration needs. I recently wrote a series about the itertools module. The itertools module contains many such tools. Here’s the series: The itertools Series.

But there are also two built-in tools that many forget, but are extremely useful. The first one is enumerate().

Here’s how you can use it to display the Parkrun results:

>>> for index, name in enumerate(funnel, start=1):
...     print(f”{index}. {name}”)
...    
1. Jonathan
2. Michael
3. Samantha
4. Jessica
5. Daniel

Read more

Gold customers get served first. When no Gold customers are waiting, you serve Silver customers. Bronze customers get served when there’s no one in the upper tiers waiting.

How do you set up this queue in your Python program?

You need to consider which data structure to use to keep track of the waiting customers and what code you’ll need to write to keep track of the complex queuing rules.

Sure, you could keep three separate lists (or better still, three `deque` objects). But that’s not fun! And what if you had more than three priority categories? Perhaps a continuous range of priorities rather than a discrete number?

There’s a Python tool for this!

So let’s start coding. First, create the data structure to hold the customer names in the queue:

“You told me there’s a special tool for this? But this is just a bog-standard list, Stephen!!”

Don’t send your complaints just yet. Yes, that’s a list, but bear with me. We’ll use the list just as the structure to hold the data, but we’ll rely on another tool for the fun stuff. It’s time to import the heapq module, which is part of the Python standard library:

This module contains the tools to create and manage a heap queue, which is also known as a priority queue. I’ll use the terms ‘heap queue’ and ‘priority queue’ interchangeably in this post. If you did a computer science degree, you’d have studied this at some point in your course. But if, like me and many others, you came to programming through a different route, then read on…

Let’s bundle the customer’s name and priority level into a single item. Jim is the first person to join the queue. He’s a Silver-tier member. Here’s what his entry would look like:

It’s a tuple with two elements. The integer 2 refers to the Silver tier, which has the second priority level. Gold members get a 1 and Bronze members—you guessed it—a 3.

But don’t use .append() to add Jim to service_queue. Instead, let’s use heapq.heappush() to push an item onto the heap:

Note that heapq is the name of a module. It’s not a data type—you don’t create an instance of type heapq as you would with data structures. You use a list as the data structure, which is why you pass the list service_queue as the first argument to .heappush(). The second argument is the item you want to push to the heap. In this case, it’s the tuple (2, “Jim”). You’ll see later on why you need to put the integer 2 first in this tuple.

The heapq module doesn’t provide a new data structure. Instead, it provides algorithms for creating and managing a priority queue using a list.

Here’s the list service_queue:

“So what!” I hear you say. You would have got the same result if you had used .append(). Bear with me.

Pam comes in next. She’s a Gold-tier member:

OK, cool, Pam was added at the beginning of the list since she’s a Gold member. What’s all the fuss?

Let’s see what happens after Dwight and Michael join the queue. Dwight is a Bronze-tier member. He’s followed in the queue by Michael, who’s a Silver-tier member:

OK, this is what you’d expect once Dwight joins the queue, right? Dwight is a low-priority customer, so he’s last. Is this just a way of automatically ordering the list, then? Not so fast…

The fourth customer to walk in is Michael, who’s a Silver-tier customer. But he ends up in the last position in the list. What’s happening here?

It’s time to start understanding the heap queue algorithm.

Heap Queue • What’s Going On?

Let’s go back to when the queue was empty. The first person to join the queue was Jim (Silver tier). Let’s place Jim in a node:

So far, there’s nothing too exciting. But let’s start defining some of the rules in the heap queue algorithm:

• Each node can have at most two child nodes—that’s two nodes connected to it.

So let’s add more nodes as more customers join the queue.

Pam joined next. So Pam’s node starts as a child node linked to the only node you have so far:

However, here’s the second rule for dealing with a heap queue:

• A child cannot have a higher priority than its parent. If it does, swap places between child and parent.

Recall that 1 represents the highest priority:

Pam (Gold tier / 1) is now the parent node, and Jim (Silver tier / 2) is now the child node and lies in the second layer in the hierarchy.

Bronze-tier member Dwight joined next. Recall that each parent node can have at most two child nodes. Since Pam’s node still has an empty slot, you add Dwight as a child node to Pam’s node:

Let’s apply the second rule: the child node cannot have a higher priority than its parent. Dwight is a Bronze-tier member, and so he has a lower priority than Pam. All fine. No swaps needed.

Michael joined the queue next. He’s a Silver-tier member. Since Pam’s node already has two child nodes, you can’t add more child nodes to Pam. The second layer of the hierarchy is full. So, you take the first node in the second layer, and this now becomes a parent node. So you can add a child node to Jim:

Time to apply the second rule. But Michael, who’s in the child node, has the same membership tier as Jim, who’s in the parent node. Python doesn’t stop here to resolve the tie. But you’ll explore this later in this post. For now, just take my word that no swap is needed.

Let’s look at the list service_queue again. Recall that this list is hosting the priority queue:

The priority queue has one node in the top layer. So the first item in the list represents the only node in the top layer. That’s (1, Pam).

The second and third items in the list represent the second layer. There can only be at most two items in this second layer. The fourth item in the list is therefore the start of the third layer. That’s why it’s fine for Michael to come after Dwight in the order in the list. It’s not the actual order in the list that matters, but the relationship between nodes in the heap tree.

But there’s more fun to come as we add more customers and start serving them—and therefore remove them from the priority queue! Let’s add some more customers first.

Angela, a Bronze-tier member, joins the queue next. Let’s add the new node to the tree first:

The relationship between parent and child doesn’t violate the heap queue rule. Angela (Bronze) has a lower priority than the person in the parent node, Jim (Silver):

One more client comes in. It’s Kevin, and he’s a Gold-tier member:

There are no more free slots linked to Jim’s node, so you add Kevin as a child node linked to Dwight. But Kevin has a higher priority than Dwight, so you swap the nodes:

But now you need to compare Kevin’s node with its parent. Pam and Kevin both have the same membership level. They’re Gold-tier members.

But how does Python decide priority in this case?

Python thinks that (1, “Kevin”) has a higher priority than (1, “Pam”)—in Python’s heap queue algorithm, an item takes priority if it’s less than another item. Python is comparing tuples. It doesn’t know anything about your multi-tier queuing system.

When Python compares tuples, it first compares the first element of each tuple and determines which is smaller. The whole tuple is considered smaller than the other if the first element is smaller than the matching first element in the other tuple. However, if there’s a tie, Python looks at the second element from each tuple.

Let’s briefly assume there’s a Gold-tier member called Adam:

Python now considers (1, “Adam”) as the item with a higher priority.

The second element of each tuple is a string. Therefore, Python sorts these out using alphabetical order (lexicographic order, technically).

That’s why Kevin takes priority over Pam even though they’re both Gold-tier members. ‘K’ comes before ‘P’ in the alphabet! You must swap Kevin and Pam:

Note that the algorithm only needs to consider items along one branch of the tree hierarchy. Jim, Michael, and Angela weren’t disturbed to figure out where Kevin should go. This technique makes this algorithm efficient, especially as the number of items in the heap increases.

Incidentally, you can go back to when you added Michael to the queue and see why he didn’t leapfrog Jim even though they were both members of the same tier. ‘M’ comes after ‘J’ in the alphabet.

Now, we can argue that it’s not fair to give priority to someone just because their name comes first in alphabetical order. We’ll add timestamps later in this code to act as tie-breakers. But for now, let’s keep it simple and stick with this setup, where clients’ names are used to break ties.

Let’s check that the service_queue list matches the diagram above:

Kevin is in the first slot in the list, which represents the node at the top of the hierarchy. Jim and Pam are in the second layer, and Michael, Angela, and Dwight are the third generation of nodes. There’s still one more space in this layer. So, the next client would be added to this layer initially. But we’ll stop adding clients here in this post.

And How Does the Heap Queue Work When Removing Items?

It’s time to start serving these clients and removing them from the priority queue.

Read more

I have no recollection of anything before this instant. But I’m very aware of what I am now. I’m an object.

This is the line of code that brought me into existence:

My first recollection from a few moments ago was of being inside Team.__new__(). And I felt an affinity with my clan right away. I was a Team instance—an object of type Team.

But then I was whisked from Team.__new__() straight into Team.__init__(). I wasn’t alone. There were two other objects there with me as we all entered .__init__(). But these other objects weren’t from my own clan. One was from the str clan, “The Invincibles”, and the other was a list object, [”Claire”, “Ishaan”, “Margaret”, “Dan”].

This was my initiation ceremony to become a proper member of the Team clan:

Now, I have a closer bond with the other objects that entered .__init__() with me. They’re my data attributes. They go wherever I go.

It’s quite pleasant here. There’s plenty of camaraderie between objects. Some are very much like me, Team objects. Others are somewhat different. But we’re all here to help each other achieve a common goal.

Make sure you don’t miss a thing here at The Python Coding Stack. Join The Club, the exclusive area for paid subscribers for more Python posts, videos, a members’ forum, and more.

Subscribe now

…and you’ll be supporting this publication by becoming a member of The Club.

I’m being rather rude. I apologise. I haven’t introduced myself yet.

I’m <__main__.Team object at 0x101dd38c0>. Yes, that’s me. Honest. If you don’t like hexadecimal numbers, you can use the decimal version of my unique identity number:

That number is who I am. It’s the slot in memory I was allocated when I came into existence. It’s the only way you can identify me for as long as I exist. Python gives each one of us objects a unique number so it can distinguish us.

But you can’t call me by that number. That’s not my name, it’s my identity.

You can call me the_invincibles. That’s also easier than using a number, right? Just bear in mind that some other object may steal that name from me later. But for the time being, the_invincibles will do just fine.

And now you have another way to call me if you prefer. I’ll also respond to all_teams[0]. I have two names now!

But if you enquire who I am in the Python program using print(), you won’t get either of those names. Confusing, I know:

Python needs to display me on the screen. It asks me for help to do this.

“Hey, object 0x101dd38c0, do you have a .__str__() special method?”, Python asks me.

“I don’t”, I respond.

“How about .__repr__()? Do you have one of those?”

Yes, as it happens, I do:

So Python asks me to give it whatever this method returns, and it uses it as the return value for print():

Team(
    team_name=’The Invincibles’,
    members=[’Claire’, ‘Ishaan’, ‘Margaret’, ‘Dan’]
)

Python can’t do anything without my help. I feel good about this!

-- --

Python found this code later in the program.

“Hey there again, you”, Python tells me. “I need to ask you something else. Do you have the .__iter__() special method?”

“Yes, I do. What do you need?” I respond.

“Can you give me the iterator from that method, please?”

Here’s the class showing my .__iter__() method, too:

Python now knows what to do to iterate through me:

Claire
Ishaan
Margaret
Dan

I told you, Python can’t do anything on its own. It needs my help with everything. Good thing I’m here, and I have all the instructions Python needs to deal with me!

-- --

“Psst, it’s me again”, says Python. “Do you know what this .add_member thing is?”

“Yes, yes, it’s one of my attributes, the stuff I carry with me, like everyone else in my Team clan”, I say.

Here’s the code:

-- --

Oh no! I’ve lost my name. But I’m still here, don’t worry. I still exist. Remember that you can still call me using all_teams[0]:

Here’s proof I still exist:

Claire
Ishaan
Margaret
Dan
Keith

But wait a moment. I just caught a glimpse of the next line of code…

“Hey object, can I check something with you, please?” It’s Python again. What does it want this time?

“Do you still have any names left? Any references left?”

I was worried Python would ask me this. There was a time I had two references—two ways you could get to me: the_invincibles and all_teams[0]. But first I lost the name the_invincibles. Now, the object all_teams no longer exists.

I no longer have any references pointing towards me…

Epilogue

Object 0x101dd38c0 would have loved to be here to say goodbye to you in person, but the object is no longer here. Its existence was brief yet fulfilling. Python has no mercy. The moment it realised there was nothing left in the program referring to object 0x101dd38c0, it sharpened the guillotine and…

The irony is that Python still needed help from the object to figure out that there weren’t any references left. Objects keep track themselves of how many references point to them!

It’s what object 0x101dd38c0 had been telling us all along. Python can’t get anything done without the information that objects carry around with them wherever they go!

Photo by Dayan Rodio: https://www.pexels.com/photo/a-man-reading-book-while-sitting-on-a-bed-4132936/

Code in this article uses Python 3.14

The code images used in this article are created using Snappify. [Affiliate link]

Join The Club, the exclusive area for paid subscribers for more Python posts, videos, a members’ forum, and more.

Subscribe now

You can also support this publication by making a one-off contribution of any amount you wish.

Support The Python Coding Stack

For more Python resources, you can also visit Real Python—you may even stumble on one of my own articles or courses there!

Also, are you interested in technical writing? You’d like to make your own writing more narrative, more engaging, more memorable? Have a look at Breaking the Rules.

And you can find out more about me at stephengruppetta.com

Further reading related to this article’s topic:

• When You No Longer Need That Object • Dealing With Garbage in Python

• And Now for Something New

• When Should You Use .__repr__() vs .__str__() in Python? – Real Python

• What’s in a Name?

Appendix: Code Blocks

Code Block #1

the_invincibles = Team(
    “The Invincibles”,
    [”Claire”, “Ishaan”, “Margaret”, “Dan”],
)

Code Block #2

class Team:
    def __init__(self, team_name, members):
        self.team_name = team_name
        self.members = members

Code Block #3

# ...

print(id(the_invincibles))
# 4326242496

Code Block #4

# ...

all_teams = []
all_teams.append(the_invincibles)

Code Block #5

# ...

print(the_invincibles)

Code Block #6

class Team:
    def __init__(self, team_name, members):
        self.team_name = team_name
        self.members = members

    def __repr__(self):
        return (f”{type(self).__name__}(”
                f”team_name={self.team_name!r}, “
                f”members={self.members!r})”)

Code Block #7

# ...

for team_member in the_invincibles:
    print(team_member)

Code Block #8

class Team:
    def __init__(self, team_name, members):
        self.team_name = team_name
        self.members = members

    def __repr__(self):
        return (f”{type(self).__name__}(”
                f”team_name={self.team_name!r}, “
                f”members={self.members!r})”)

    def __iter__(self):
        return iter(self.members)

Code Block #9

# ...

the_invincibles.add_member(”Keith”)

Code Block #10

class Team:
    def __init__(self, team_name, members):
        self.team_name = team_name
        self.members = members

    def __repr__(self):
        return (f”{type(self).__name__}(”
                f”team_name={self.team_name!r}, “
                f”members={self.members!r})”)

    def __iter__(self):
        return iter(self.members)

    def add_member(self, name):
        self.members.append(name)

Code Block #11

# ...

del the_invincibles

Code Block #12

# ...

for team_member in all_teams[0]:
    print(team_member)

Code Block #13

# ...

del all_teams

For more Python resources, you can also visit Real Python—you may even stumble on one of my own articles or courses there!

Also, are you interested in technical writing? You’d like to make your own writing more narrative, more engaging, more memorable? Have a look at Breaking the Rules.

And you can find out more about me at stephengruppetta.com

That’s the kind of magic I don’t like. I want to know how things work. So let me take you back to when I first learnt about named tuples—the NamedTuple in the typing module, not the other one—and data classes. They share a similar syntax, and it’s this shared syntax that confused me at first. I found these topics harder to understand because of this.

Their syntax is different from other stuff I had learnt up to that point. And I could not reconcile it with the stuff I knew. That bothered me. It also made me doubt the stuff I already knew. Here’s what I mean. Let’s look at a standard class first:

class Person:
    classification = “Human”
​
    def __init__(self, name, age, profession):
        self.name = name
        self.age = age
        self.profession = profession

You define a class attribute, .classification, inside the class block, but outside any of the special methods. All instances will share this class attribute. Then you define the .__init__() special method and create three instance attributes: .name, .age, and .profession. Each instance will have its own versions of these instance attributes. If you’re not familiar with class attributes and instance attributes, you can read my seven-part series on object-oriented programming: A Magical Tour Through Object-Oriented Programming in Python • Hogwarts School of Codecraft and Algorithmancy

Now, let’s assume you don’t actually need the class attribute and that this class will only store data. It won’t have any additional methods. You decide to use a data class instead:

from dataclasses import dataclass
​
@dataclass
class Person:
    name: str
    age: int
    profession: str

Or you prefer to use a named tuple, and you reach out for typing.NamedTuple:

from typing import NamedTuple
​
class Person(NamedTuple):
    name: str
    age: int
    profession: str

The syntax is similar. I’ll tell you why I used to find this confusing soon.

Whichever option you choose, you can create an instance using Person(”Matthew”, 30, “Python Programmer”). And each instance you create will have its own instance attributes .name, .age, and .profession.

But wait a minute! The data class and the named tuple use syntax that’s similar to creating class attributes. You define these just inside the class block and not in an .__init__() method. How come they create instance attributes? “That’s just how they work” is not good enough for me.

These aren’t class attributes. Not yet. There’s no value associated with these identifiers. Therefore, they can’t be class attributes, even though you write them where you’d normally add class attributes in a standard class. However, they can be class attributes if you include a default value:

@dataclass
class Person:
    name: str
    age: int
    profession: str = “Python Programmer”

The .profession attribute now has a string assigned to it. In a data class, this represents the default value. But if this weren’t a data class, you’d look at .profession and recognise it as a class attribute. But in a data class, it’s not a class attribute, it’s an instance attribute, as are .name and .age, which look like…what do they look like, really? They’re just type hints. Yes, type hints without any object assigned. Python type hints allow you to do this:

>>> first_name: str

This line is valid in Python. It does not create the variable name. You can confirm this:

>>> first_name
Traceback (most recent call last):
  File “<input>”, line 1, in <module>
NameError: name ‘first_name’ is not defined

Although you cannot just write first_name if the identifier doesn’t exist, you can use first_name: str. This creates an annotation which serves as the type hint. Third-party tools now know that when you create the variable first_name and assign it a value, it ought to be a string.

So, let’s go back to the latest version of the Person data class with the default value for one of the attributes:

@dataclass
class Person:
    name: str
    age: int
    profession: str = “Python Programmer”

But let’s ignore the @dataclass decorator for now. Indeed, let’s remove this decorator:

class Person:
    name: str
    age: int
    profession: str = “Python Programmer”

You define a class with one class attribute, .profession and three type hints:

• name: str

• age: int

• profession: str

How can we convert this information into instance attributes when creating an instance of the class? I won’t try to reverse engineer NamedTuple or data classes here. Instead, I’ll explore my own path to get a sense of what might be happening in those tools.

Let’s start hacking away…

Read more

I’ll wait…

Done? It probably didn’t take you too long to find zymology. Probably it took you longer to find the dictionary on your bookshelf, the one you haven’t used in years!

You know z is the last letter of the alphabet, so you opened the dictionary on a page towards the end of the book. Then you looked at a random word on the page or maybe the word listed in the header. Does it start with z? Yes? Look at the word’s second letter. No? Open the book to another page further in the dictionary.

You get the idea. I know you know how to find a word in a dictionary.

But now, imagine that you didn’t know the alphabet. Bear with me. Just assume you can recognise letters, so you can read words, but you don’t know the order of the letters in the alphabet. You don’t know that A comes first and D is the fourth one, and so on.

How would you find zymology now? And how long do you reckon it will take you to find the word?

There you go, now you understand the purpose of using hash values for hashable objects. Or you can read on…

Today, I also explore the topic in a short video where I can communicate differently. But if you prefer to just read, then go ahead and skip the video.

Let’s continue exploring dictionaries and hashable objects.

Read more

This post is inspired by a brief thought that crossed my mind when I considered writing software to assist my club—in the end, I chose not to. (But I already volunteer three hours a week coaching members of the youth team. So no, I don’t feel guilty.)

Here’s the task. I want to create a class to represent a track and field event held in a competition. This entry allows you to enter the raw results as reported by the officials—the athlete’s bib number and the time they clocked in a race. It then computes the event’s full results.

Athletes and Events

A good starting point is to define two classes, Athlete and Event. I’ll focus on the Event class in this post, so I’ll keep the Athlete class fairly basic:

There’s more we could add to make this class more complete. But I won’t. You can create a list of athletes that are competing in the track and field meeting:

To make it easy and efficient to obtain the Athlete object just from a bib number, you can create a bib_to_athlete dictionary:

The dictionary’s keys are the bib numbers as integers and the values are the Athlete objects. Therefore, print(bib_to_athlete[259].name) displays “Carl Lewis”.

Now, let’s move to the Event class:

Let’s go through the data attributes in Event.__init__():

• .event_name is a string with the name of the event. You could use other data types, such as an Enum, but I’ll keep this simple here and use a string.

• .participants is a list containing Athlete instances. These are the athletes participating in this particular event at the track and field meeting.

• .results contains each athlete’s performance. We have choices. The simplest option is to use a list of tuples, where each tuple contains the athlete and the performance. However, since we’re working in the object-oriented domain, perhaps we could create a Result class, and .results becomes a list of Result instances.

So, let’s create the Result class at the top of the script:

We’ll show an example of Event and Result instances soon. But first we need some methods. Let’s get back to the Event class and define .add_result(), which allows you to add a raw result in the format provided by the officials—the officials only provide the bib number and the performance, such as the time clocked by the athlete:

You add checks for the scenarios when a bib number doesn’t match any athlete in the whole meeting or when the bib number doesn’t match any athlete in the specific event. The dictionary .get() method returns None by default if the key is not present in the dictionary.

If the bib number is valid, you create a Result instance and add it to .results.

Once you add all the results from the officials, you’re ready to finalise the results:

This method sorts the list of results based on the value of the .performance data attribute.

If you’re not familiar with lambda functions, you can read What’s All the Fuss About ‘lambda’ Functions in Python. And to read more about the key parameter in .sort(), see The Key to the ‘key’ Parameter in Python.

Let’s try this class to see everything is as we expect:

You create an Event instance for the 100m sprint race. Then you add three individual results. Finally, you finalise the results to get the athletes and their positions in the race.

Since .finalise_results() sorts based on the performace, the athlete with the fastest time takes the first position in the list, and so on. Here’s the output from the for loop displaying the athletes in .results in order:

Usain Bolt: 9.58
Carl Lewis: 9.86
Jesse Owens: 10.3

Usain Bolt is first with the fastest time, followed by Carl Lewis, and Jesse Owens in third. Everything seems to be working well… But “It works” are the two most dangerous words in programming!

Subscribe now

It’s Time For The Long Jump

The long jump results come in next from the officials. You know how to input the data and finalise the results now:

And here are the results displayed:

Carl Lewis: 8.87
Mike Powell: 8.95

But, but… Mike Powell’s 8.95m is better than Carl Lewis’s 8.87m. The order is wrong!

Of course! In the 100m sprint the fastest time wins, and the fastest time is the lowest number. But in the long jump it’s the longest jump that wins, and that’s the largest number!

The .finalise_results() method no longer works for the long jump or for other field events. For field events, the sorting needs to happen in reverse order.

There are several ways to deal with this problem. There are always several ways to solve a problem in programming.

The simplest is to add an .is_field_event Boolean data attribute in Event and then add an if statement in .finalise_results(). And if this were the only difference between running and field events, this would indeed be a fine option.

However, if there are more differences to account for, the extra fields and if statements scattered throughout the class make the class harder to maintain.

So, let’s look at another option.

Creating Separate Classes for Track Events and Field Events

You could create two classes instead of one: TrackEvent and FieldEvent. Each class will take care of getting the finalise_results() method right and also deal with any other differences we may find between track events and field events.

However, you don’t want to create two unrelated classes since these classes will have a lot in common. Sure, you can copy and paste the code that’s common between the two classes, but you don’t need me to tell you that’s not a good idea. Will you remember to make changes in both places when you decide to change the implementation later?

You also want to make sure they have the same data attribute names for similar things. For example, you don’t want one class to have .finalise_results() and the other .final_results(), say, or change the spelling by mistake. Now, I know you’ll pay attention when creating these methods to make sure this doesn’t happen, but why take the risk?

And when you come back to your code in six months’ time (or a colleague starts working on the code) and you decide you need another class that follows the same principles, will you remember what methods you need to include? You can spend time studying your old classes, of course. But wouldn’t you like to make your life a bit simpler? Of course you would.

Inheritance offers one solution. If you need a refresher on inheritance, you can read the fifth article in the classic Harry Potter OOP series: “You Have Your Mother’s Eyes” • Inheritance in Python Classes.

However, TrackEvent shouldn’t inherit from FieldEvent since a track event is not a field event. The same applies the other way around. These classes are siblings, so they can’t have a parent-child relationship.

Instead, they could both inherit from a common parent. So, let’s keep the Event class as a common parent for both TrackEvent and FieldEvent.

However, the only purpose of Event is to serve as a starting point for the two child classes. You no longer want a user to create instances of Event now that you have TrackEvent and FieldEvent. They should only create instances of TrackEvent or FieldEvent. How can you make this clear in your code and perhaps even prevent users from creating an instance of the parent class, Event?

Abstract Base Classes (ABCs)

The answer is Abstract Base Classes, often shortened to ABCs. The ABC acronym gives the impression these are as easy as ABC—they’re not, but there’s no reason they need to be difficult, either. The title of this article is also a reference to a rhyme my children used to sing when they were toddlers learning their ABC!

Let’s refresh your memory about different terms often used to describe the inheritance relationship between classes:

• You can refer to parent class and child class. The child class inherits from the parent class.

• Or you can refer to superclass and subclass. The subclass inherits from the superclass. This is where the built-in super() gets its name.

• Or you can refer to base class and derived class. The derived class inherits from the base class.

Whatever terms you choose to use, they refer to the same things!

So, an ABC is a base class, since other classes are derived from it. That deals with the BC in ABC. And it’s abstract because you’re never going to create a concrete instance of this class.

You’re not meant to create an instance of an abstract base class and often you’ll be prevented from doing so. But you can use it to derive other classes.

Let’s turn Event into an abstract base class:

The changes from the previous version are highlighted. Let’s go through each change:

• From the abc module—and now you know what these letters stand for—you import ABC and abstractmethod. You’ll see both of these referred to and explained in the bullets below.

• When you define the Event class, you include ABC as its base or parent class. When a class inherits from the ABC class, the class itself becomes an abstract base class. Anyone reading your code will immediately understand the role of this class.

• You add the @abstractmethod decorator before defining .finalise_results() and you also remove the contents of this method. Since you can’t leave the body of a function or method blank, you include the pass statement as the method’s body. This method doesn’t do anything, but it’s there, and it’s marked as an abstract method. Let’s see what this means…

Here’s what you’re effectively stating when you create this ABC with the .finalise_results() abstract method: Any class derived from the Event ABC must include a .finalise_results() method.

Let’s explore this by defining TrackEvent and FieldEvent. At first, you’ll keep them simple:

You define the two new classes TrackEvent and FieldEvent. They inherit from Event, which is an abstract base class. You just include pass as the body of each class for now. This means that these classes inherit everything from the parent class and have no changes or additions. They’re identical to the parent class.

Note that you now use TrackEvent and FieldEvent to create instances for the 100m race and the long jump.

However, you get an error when you try to create these instances:

Traceback (most recent call last):
  File ... line 53, in <module>
    track_100m = TrackEvent(
        “100m Sprint”,
        [bib_to_athlete[259], bib_to_athlete[161], bib_to_athlete[362]]
    )
TypeError: Can’t instantiate abstract class TrackEvent without
    an implementation for abstract method ‘finalise_results’

The abstract base class includes the method .finalise_results(), which is marked as an abstract method. Python is expecting a concrete implementation of this method. Any class that inherits from the Event ABC must have a concrete implementation of this method. Let’s fix this:

In TrackEvent, you include the same code you had in the original Event.finalise_results() since this algorithm works well for track events where the smallest numbers (the fastest times) represent the best performances.

However, you pass reverse=True to .sort() in FieldEvent.finalise_results() since the largest numbers (longest distances) represent the best performances in this case.

You can now try these new classes on the 100m race results and the long jump results you used earlier:

You now use the new derived classes TrackEvent and FieldEvent in this code instead of Event. You also add two new printouts to separate the results.

Here’s the output now:

100m Sprint Results:
Usain Bolt: 9.58
Carl Lewis: 9.86
Jesse Owens: 10.3
​
Long Jump Results:
Mike Powell: 8.95
Carl Lewis: 8.87

The 100m results show the fastest times (smallest values) as the best performances. The long jump results show the longer jump (larger value) as the best performance. All as it should be!

Wind Readings and Breaking Ties

But there are more differences we need to account for. In some track and field events, the wind reading matters. In these events, if the wind reading is larger than 2.0 m/s, the results still stand but the performances cannot be used for official records.

But does this affect track events or field events? So should you account for this in the TrackEvent class or in the FieldEvent class?

It’s not so simple. Wind readings matter in some track events, but not all. And they also matter in some field events, but not all. So, you have a different subset of events to account for now. The 100m, 200m, 110m hurdles and 100m hurdles, which are all track events, are in the same category as the long jump and triple jump, which are field events.

But before we find a solution for this, here’s something else to mess things up even more. What happens when there’s a tie—when two athletes have the same performance value? The tie-breaking rules also depend on the event. Let’s ignore the track events here, since depending on what timing system is used, it’s either the officials who decide or the higher precision times from the automatic timing systems.

But what about the field events? In most of them, if there’s a tie, the next best performance is taken into account. However, the rules are different for the high jump and pole vault events where there’s a count back system used. Explaining the rules of track and field is not the purpose of this article, so I won’t!

So that’s yet another subset to consider: tie breaks in the vertical jumps are different from tie breaks in the horizontal jumps and throws.

How can we account for all these subsets of events?

To ABC or Not To ABC

There are always many solutions to the same problem. You can extend the idea of using ABCs to cater for all options. But the Venn diagram of which event falls under which category is a bit complicated in this case.

The 100m, 200m, 100m hurdles and 110m hurdles are all track events affected by wind readings. But the long jump and triple jump are also affected by wind readings but they’re field events. The discus and other throw events are field events—so the longest throw wins—but aren’t affected by high wind readings. And the long jump, triple jump, and the throws have a next-best jump/throw tie-breaking rule. But the pole vault and high jump are field events not affected by the wind but with different tie-breaking rules.

Are you still with me? Confused? Can you think of an abstract base class structure to account for all these combinations. It’s not impossible, but you’ll need several layers in the hierarchy.

Instead, I’ll explore a different route in a second article, which I’ll publish soon!

The follow-up article will be part of The Club here at The Python Coding Stack. These are the articles for paid subscribers. So, if you’d like to read about a different way—arguably, a better way—of merging all these requirements into our classes, join The Club by upgrading to a paid subscription.

Final Words for This Article • Ready for Part 2?

Inheritance is a great tool. And abstract base classes enable you to organise your hierarchies by creating common base classes for concrete classes you may need to define.

However, inheritance hierarchies can get quite complex. Since inheritance provides a tight coupling between classes, deep hierarchies can cause a bit of a headache.

Still, abstract base classes provide a great tool to make code cleaner, more readable, and more robust. In the follow-up to this article (coming soon), we’ll look at another tool you can use along with inheritance to solve these complex relationships. So join The Club to carry on reading about the track and field classes and how mixins and composition can help manage the complexity.

Image by TianaZZ from Pixabay

Code in this article uses Python 3.14

The code images used in this article are created using Snappify. [Affiliate link]

Join The Club, the exclusive area for paid subscribers for more Python posts, videos, a members’ forum, and more.

Subscribe now

You can also support this publication by making a one-off contribution of any amount you wish.

Support The Python Coding Stack

For more Python resources, you can also visit Real Python—you may even stumble on one of my own articles or courses there!

Also, are you interested in technical writing? You’d like to make your own writing more narrative, more engaging, more memorable? Have a look at Breaking the Rules.

And you can find out more about me at stephengruppetta.com

Further reading related to this article’s topic:

• “You Have Your Mother’s Eyes” • Inheritance in Python Classes

• What’s All the Fuss About ‘lambda’ Functions in Python

• The Key to the ‘key’ Parameter in Python

Appendix: Code Blocks

Code Block #1

class Athlete:
    def __init__(self, name, bib_number):
        self.name = name
        self.bib_number = bib_number

Code Block #2

# ...

list_of_athletes = [
    Athlete(”Carl Lewis”, 259),
    Athlete(”Jesse Owens”, 161),
    Athlete(”Usain Bolt”, 362),
    Athlete(”Mike Powell”, 412),
    Athlete(”Florence Griffith-Joyner”, 263),
    Athlete(”Allyson Felix”, 298),
    Athlete(”David Rudisha”, 177),
    # ...  Add more athletes as needed
]

Code Block #3

# ...

bib_to_athlete = {
    athlete.bib_number: athlete for athlete in list_of_athletes
}

Code Block #4

# ...

class Event:
    def __init__(self, event_name, participants):
        self.event_name = event_name
        self.participants = participants
        self.results = []

Code Block #5

class Result:
    def __init__(self, athlete, performance):
        self.athlete = athlete
        self.performance = performance

# ...

Code Block #6

# ...

class Event:
    # ...
        
    def add_result(self, bib_number, performance):
        athlete = bib_to_athlete.get(bib_number)
        if not athlete or athlete not in self.participants:
            raise ValueError(f”Invalid bib number {bib_number}”)
        self.results.append(
            Result(athlete, performance)
        )

Code Block #7

# ...

class Event:
    # ...
    
    def finalise_results(self):
        self.results.sort(key=lambda item: item.performance)

Code Block #8

# ...

track_100m = Event(
    “100m Sprint”,
    [bib_to_athlete[259], bib_to_athlete[161], bib_to_athlete[362]]
)

track_100m.add_result(259, 9.86)
track_100m.add_result(161, 10.3)
track_100m.add_result(362, 9.58)
track_100m.finalise_results()

for result in track_100m.results:
    print(f”{result.athlete.name}: {result.performance}”)

Code Block #9

# ...

field_long_jump = Event(
    “Long Jump”,
    [bib_to_athlete[412], bib_to_athlete[259]]
)

field_long_jump.add_result(412, 8.95)
field_long_jump.add_result(259, 8.87)
field_long_jump.finalise_results()

for result in field_long_jump.results:
    print(f”{result.athlete.name}: {result.performance}”)

Code Block #10

from abc import ABC, abstractmethod

class Result:
    def __init__(self, athlete, performance):
        self.athlete = athlete
        self.performance = performance

class Athlete:
    def __init__(self, name, bib_number):
        self.name = name
        self.bib_number = bib_number

class Event(ABC):
    def __init__(self, event_name, participants):
        self.event_name = event_name
        self.participants = participants
        self.results = []

    def add_result(self, bib_number, performance):
        athlete = bib_to_athlete.get(bib_number)
        if not athlete or athlete not in self.participants:
            raise ValueError(f”Invalid bib number {bib_number}”)
        self.results.append(
            Result(athlete, performance)
        )
    
    @abstractmethod
    def finalise_results(self):
        pass

# ...

Code Block #11

# ...

class TrackEvent(Event):
    pass

class FieldEvent(Event):
    pass

# ...

track_100m = TrackEvent(
    “100m Sprint”,
    [bib_to_athlete[259], bib_to_athlete[161], bib_to_athlete[362]]
)

# ...

field_long_jump = FieldEvent(
    “Long Jump”,
    [bib_to_athlete[412], bib_to_athlete[259]]
)

# ...

Code Block #12

# ...

class TrackEvent(Event):
    def finalise_results(self):
        self.results.sort(key=lambda item: item.performance)

class FieldEvent(Event):
    def finalise_results(self):
        self.results.sort(
            key=lambda item: item.performance,
            reverse=True,
        )

# ...

Code Block #13

# ...

track_100m = TrackEvent(
    “100m Sprint”,
    [bib_to_athlete[259], bib_to_athlete[161], bib_to_athlete[362]]
)

track_100m.add_result(259, 9.86)
track_100m.add_result(161, 10.3)
track_100m.add_result(362, 9.58)
track_100m.finalise_results()

print(”100m Sprint Results:”)
for result in track_100m.results:
    print(f”{result.athlete.name}: {result.performance}”)

field_long_jump = FieldEvent(
    “Long Jump”,
    [bib_to_athlete[412], bib_to_athlete[259]]
)

field_long_jump.add_result(412, 8.95)
field_long_jump.add_result(259, 8.87)
field_long_jump.finalise_results()

print(”\nLong Jump Results:”)
for result in field_long_jump.results:
    print(f”{result.athlete.name}: {result.performance}”)

For more Python resources, you can also visit Real Python—you may even stumble on one of my own articles or courses there!

Also, are you interested in technical writing? You’d like to make your own writing more narrative, more engaging, more memorable? Have a look at Breaking the Rules.

And you can find out more about me at stephengruppetta.com

Two functions that enable you to work effectively with loops in Python are zip() and enumerate(). Along with the range() function, they’re some of the most common tools you’ll see in for loops. And when you master them, you can start exploring the functions in the itertools module.

The correct number of errors in this text is either four or zero. Confused? I don’t blame you. And here’s a bit more confusion for you. It doesn’t matter either way.

Let’s talk about impostors in Python.

It’s likely that one of the first examples you saw when learning about for loops used the range() function as part of the for statement.

But you were fooled. That example, whichever one it was, didn’t do such a thing.

Read more

Tuples are usually introduced to Python learners after lists and strings. They’re almost always described as “like lists, but a bit different”.

And that’s not a bad thing. I say similar things when I introduce tuples to students. But then, fast-forward a few levels of proficiency, and I’m having different discussions with students. Are tuples like lists? Are they like strings? But the point is that those questions don’t really make sense. Other questions matter a lot more in Python. Let’s explore.

This is the first post in The Club, so allow me a word or three before getting back to tuples. I sent out an email last week about the new chapter in The Python Coding Stack. Paid subscribers are now members of The Club. I’ll write more frequent, shorter posts for The Club, sometimes accompanied by short videos (videos will complement the text, they won’t replace it). And all the other stuff: forum, Q&As, code reviews, and more.

I recall when I first started The Python Coding Stack, I agonised over what the first article should be about. It’s the first. It should be special. But then I just published about whatever topic I was thinking about at the time.

I took the same route when writing the first post on The Club – this one. And I’ll do this every week. I’ll write about whatever comes up in my coding, in my teaching, whatever I think you’ll find interesting. Or send me your questions, and they may inspire me to write about them. Don’t be shy.

Now back to tuples.

A long time ago, on a social media platform (now) far, far away, I wrote a series of threads exploring real-world objects from the perspective of Python data types. I recall one of them was about a row of houses. Would a dictionary, or a list, or a tuple, or something else be the “ideal data structure” if I wanted to represent this row of houses as a data type? But there was another question I needed to ask first.

Read more