Forem: Noble-47

Leveraging The Power Of Iteration Using Python Data Model

Noble-47 — Sun, 23 Feb 2025 22:32:59 +0000

Iteration is a core part of many built-in objects in Python such as list and tuple objects. Just as with many other python features, the Python data model gives us a way to create iterable objects that work well with Python's idiomatic features giving our objects the powers needed to accomplish iterative tasks.

This article is a follow up of my previous Python Data Model article - Special Methods. In this article, I assume that you are already familiar with a few daunder/special methods including those for string representation and comparisons. If you are unfamiliar with any of these checkout my previous post that covers what you need to continue with this article.

To make iterable objects, we need a good understanding of how Python implements iteration and what is required to make our own iterable objects. To explain iteration, we will be creating a coordinate geometry point object which is a bit mathematical as was mentioned in the previous post. Along with making our objects iterable, we will also give our objects other cool functionalities that are common to it. We will begin by creating a coordinate geometry point class.

The Point Object

For our Point object, we really just want to create a simple object that works well with the x and y coordinate system (the Cartesian plane) having some functions that are common to a coordinate point. We will begin our class definition by defining the daunder init method and paramters needed.

class Point:
    def __init__(self, coordinates): 
        """
         coordinates : a list or tuple of two numbers,the first
                       specifies the x-axis value,the second
                       specifies the y-axis value
        """
        self.coordinates = tuple(coordinates)

    def __repr__(self):
        return f"Point([{','.join(str(v) for v in self.coordinates)}])"

Our simple Point class requires only a single argument to be initialized, the coordinates argument which is expected to be a sequence that can be turned into a tuple object, this simply means that the coordinates can be a list or any iterable that returns two numbers. The use of coordinates as an iterable that returns numbers is mainly because it allows us to easily extend our class. If in the future we decide to simulate a n-coordinate system that has more than two axes, a Point class definition that specifies x and y as arguments for a 2-dimensional coordinate system point object would be quite difficult to extend especially if n is a bigger number relative to 2. However, in this article, most of our methods would comfortably work on a 2-dimensional coordinate system than any other. Why? simple is better than complex.

A quick noticeable problem with the way the Point class is defined is that the x and y axis values of an instance would have to be accessed from self.coordinates which is not ideal. The problem with letting users access the coordinates property of an instance is the fact that the user could knowingly or unknowingly assign it to another value which could break the code or cause unexpected behaviors. Let us consider a few cases

>>> p = Point((1,2)) # we pass in a tuple as coordinate (1,2)
>>> x,y = p.coordinates # tuple unpacking to access x and y values
>>> print(f'{x}, {y}') 
# return : 1, 2
>>> p.coordinates = None # reassign coordinates
>>> x,y = p.coordinates
# return : Traceback (most recent call last): 
  File "<stdin>", line 1, in <module> 
TypeError: cannot unpack non-iterable NoneType object

Because in our implementation, we do not want users of our class instance to reassign the coordinates property of an instance of our class, we will have to implement a way that gives read-only access to the values contained in the coordinates property and we will also have to declare coordinates as a private variable. Let's begin with the last, making coordinates a private variable.

class Point:
    def __init__(self, coordinates):
        self._coordinates = tuple(coordinates)

    def __repr__(self):
        return f"Point([{','.join(str(v) for v in self._coordinates}])"

Not much of a change right? In our bid to make the coordinates property private, we only used a new variable with the same name except for the underscore in front. Python does not make a variable private, this is just an accepted way among Python programmers to tell others that 'this variable is not to be accessed directly and any error that results by you accessing this variable is completely on you'. For more about this, you can check out GeeksForGeeks article also check out the official python docs. Now that we have made coordinates 'Private', we will now turn our attention to accessing the values in _coordinates without exposing our 'private' variable. One way we can do this is to make our Point instance an iterable object that returns the next value in _coordinates starting from index 0 every time it is looped over like in a for loop.

The first step we will take to make our object iterable is to have a good understanding of what Python considers iterable. To do that, we will consult our favorite doctor, the Python docs (documentation), and here's what it says

iterable:
An object capable of returning its members one at a time. Examples of iterables include all sequence types (such as list, str, and tuple) and some non-sequence types like dict, file objects, and objects of any classes you define with an iter() method or with a getitem() method that implements Sequence semantics. -- (python doc)

For our object to be considered an iterable object, it must implement the dunder iter method and an optional dunder getitem method. The __iter__ method is expected to return an iterator object as stated in the Python documentation. Since it is required that our __iter__ method has to return an iterator object, we will also have to know what that is.

iterator
An object representing a stream of data. Repeated calls to the iterator's next() method (or passing it to the built-in function next()) return successive items in the stream. When no more data are available a StopIteration exception is raised instead. At this point, the iterator object is exhausted and any further calls to its next() method just raise StopIteration again. Iterators are required to have an iter() method that returns the iterator object itself so every iterator is also iterable and may be used in most places where other iterables are accepted. One notable exception is code which attempts multiple iteration passes. A container object (such as a list) produces a fresh new iterator each time you pass it to the iter() function or use it in a for loop.

I know this is a bit of a lengthy text but let me break it down for you. An iterator object represents a stream of data and must have two methods : iter and next. The next method is responsible for returning successive (the next) items in the stream or raising a StopIteration if the stream is exhausted. while the iter method should return the same iterable object (self).

Notice the difference between the iterator object and the iterable object in Python. The iterable objects implement an optional `getitem` _method and the __iter__ method that returns an iterator object. While the iterator object implements a __next__ method to be consumed by the next built-in function and an __iter__ method to return the iterator object. We can say that iterators are iterable but iterable objects are not iterators

class Point:
    def __init__(self, coordinates):
        self._coordinates = tuple(coordinates)

    def __repr__(self):
    return f"Point([{','.join(str(v) for v in self._coordinates}])"

    def __iter__(self):
        return PointIterator(self._coordinates)

class PointIterator:
    def __init__(self, coordinates):
        self.coordinates = coordinates
        self.count = 0

    def __next__(self):
        if self.count >= len(self.coordinates):
            raise StopIteration
        value = self.coordinates[self.count]
        self.count += 1
        return value

    def __iter__(self):
        return self

Our class PointIterator satisfies the requirement to serve as an iterator and just by creating and returning an instance of PointIterator in the class Point __iter__() method, we have successfully made our Point objects iterable. Let's have a quick walkthrough of our PointIterator class definition. As with most other class definitions, our iterator class has a __init__ method that takes in a single coordinate argument and then initializes the coordinates and count properties of our iterator class. The coordinates would be the coordinates of our Point object. For our use case, coordinates would be a tuple object. The count property is used as a reference to what value in self.coordinates our __next__ method is to return. The __next__ method is where most of the heavy lifting is done. It first checks if the integer variable self.count has exceeded or is equal to the length (len) of the coordinates tuple. We use the ≥ comparison because Python indexing starts from zero, so a tuple of two objects would have a length of 2 but a last index of 1. As stated in the Python docs, we raise a Stopiteration when self.count has reached or exceeded len( self.coordinates). If it hasn't, we just want to return the element at the index corresponding to the value of self.count and then increment count by 1. The __iter__ method simply returns self, the same iterator object on which the built-in method iter is called on. We can check what new capabilities our Point instance now has

# creating a 3 dimensional coordinate system point
>>> p = Point((1,2,3))

>>> print(p)
# return : Point([1,2,3])

# call the iter function on p
>>> it = iter(p)
>>> it 
# return : <__main__.PointIterator object at 0x7...> the repr of 'it'

# call next on it
>>> next(it)
# return : 1 the first number in coordinates

>>> next(it)
# return : 2

>>> next(it)
# return : 3

>>> next(it)
# return : Traceback (most recent call last): 
  File "<stdin>", line 1, in <module> 
  File "test.py", line 22, in __next__ 
    raise StopIteration 
StopIteration
# A StopIteration is raised as expected

"""Our object can also work well with for loops"""
>>> for coord in p:
...    print(coord)
# returns : 
1 
2 
3

We have now successfully made our Point instance iterable but there are other ways to achieve this with way less lines of code. I'll show you two ways to quickly make our objects iterable without having to create our own iterator object.

Falling On The Tuple Iterator Object

We already know that objects like tuples and list are iterables, this means that they also have an iterator objects that handles iteration behind the scene. Let's take a peek

>>> it = iter(tuple([1,2,3]))
>>> it
# return : <tuple_iterator object at 0x...>
>>> next(it)
# return : 1

What this means for us is that we can make use of the tuple iterator for our objects since self.coordinates is a tuple. All we have to do is to modify the __iter_ method in our Point class

class Point:
    def __init__(self, coordinates):
        self._coordinates = tuple(coordinates)

    def __repr__(self):
        return f"Point([{','.join(str(v) for v in self._coordinates}])"

    def __iter__(self):
        return iter(self._coordinates)

Let's test it…

>>> p = Point((1,2,3))
>>> for coords in p:
...    print(p)
...
# return:
1 
2 
3

which is exactly the same as before but with way less code.

Using Generator Expression

This method is the most common, most simple, and also considered the most pythonic. Let's see how it is done

class Point:
    def __init__(self, coordinates):
        self._coordinates = tuple(coordinates)

    def __repr__(self):
        return f"Point([{','.join(str(v) for v in self._coordinates}])"
    def __iter__(self):
        points = (x for x in self._coordinates)
        return points

the expression

(x for x in self._coordinates)

returns a generator object that can be consumed by the iter method for iteration. A simple example

>>> p = Point((1,2,3))
>>> iter(p)
# return : <generator object Point.__iter__.<locals>.<genexpr> at 0x...>
>>> for coord in p:
...    print(coord)
...
# return :
1 
2 
3

This method is preferable because of the nature of generators, they save space by only computing the values when needed. It may not be so obvious for a 3-dimensional point but if we were dealing with a n-dimensional point where n could be a million, generator expression would be the right guy for the job. Just as a tip, because our object is now iterable, we can change our repr code to look better…

    ... 
    def __repr__(self):
        return f"Point([{','.join(str(v) for v in self}])"

This would work just fine because self which is an instance of our class is now iterable. One more thing to notice, we can shorten our iter() method code by returning the generator without creating the point variable...

return (x for x in self._coordinates)

But I find the first to be more readable. Now that we have made our object iterable, there's still a little more work to do.

First I'd like to address a little problem with our object. Making our object iterable did not make it subscriptable. In Python that means we cannot access the coordinates with its index

>>> p = Point((2,3))
>>> p[0]
# return : Traceback (most recent call last): 
  File "<stdin>", line 1, in <module> 
TypeError: 'Point' object is not subscriptable

To make our object subscriptable, we will have to give it a special method python calls in handling subscriptable objects - the getitem method

class Point:
    def __init__(self, coordinates):
        self._coordinates = tuple(coordinates)

    def __repr__(self):
        return f"Point([{','.join(str(v) for v in self._coordinates}])"
    def __iter__(self):
        return iter(self._coordinates)

    def __getitem__(self, index):
        cls = type(self)
        if isinstance(index, int):
            return self._coordinates[index] 

        if isinstance(index,slice):
            return cls(self._cordinates[index])

        raise TypeError(f'{cls.__name__} indicies must be integers or slices, not {type(index).__name__})

Our major focus is the getitem method. It requires an index argument which should be an int or a slice object. If it is none of the mentioned object types, a TypeError should be raised. For checking the type of object index is, we use the isinstance function. Depending on if index is a slice object or an int, in line with how Python list and tuple behaves, we return a new instance of Point that contains only the values that fall into the slice or return a single value. type(self) is just a dynamic way of getting the class of self without hard coding or passing it as an argument to getitem. The error message is actually a simple modification of what a list would also raise. Let's test our object

>>> p = Point((2,3,4)) # A 3-dimensional coordinate point
>>> p[0] # using an int as index
# return : 2
>>> p[-1] # negative indexing
# return : 4
>>> p[:2] # using a slice as index
# return : Point([2,3]) 
>>> p['a'] # using a str for index, expecting a TypeError
# return : Traceback (most recent call last): 
  File "<stdin>", line 1, in <module> 
  File "test.py", line 18, in __getitem__ 
    raise TypeError(f"{cls.__name__} indices must be integers or slices, not {type(index).__name__}")    
TypeError: Point indices must be integers or slices, not str

With this, our object now has full support for slicing and indexing and also a nice formatted error message.

Another feature I would like our Point object to have is read only attributes or labels that will have values corresponding to a coordinate in Point. For example, we can give a 2 dimensional coordinates the label 'xy' where calling point.x returns the coordinate at index 0 and point.y returns the coordinate at index 1. This can be done by adding __getattr__ and __setattr__ methods to our object.

class Point:
    def __init__(self, coordinates, label=None):
        self._coordinates = tuple(coordinates)
        self._label = label
    def __repr__(self):
        return f"Point([{','.join(str(v) for v in self._coordinates}])"
    def __iter__(self):
        return iter(self._coordinates)

    def __getitem__(self, index):
        cls = type(self)
        if isinstance(index, int):
            return self._coordinates[index] 

        if isinstance(index,slice):
            return cls(self._cordinates[index])

        raise TypeError(f'{cls.__name__} indicies must be integers or slices, not {type(index).__name__}')
    def __getattr__(self, name): 
        cls = type(self) 
        msg = f"{cls.__name__} object has not attribute {name}"
        if self._label is None: 
            raise AttributeError(msg)
        if len(name) == 1: 
            l = self._label.find(name) 
            if 0 <= l < len(self._coordinates): 
                return self._coordinates[l] 
        raise AttributeError(msg) 

    def __setattr__(self, name, value): 
        cls = type(self) 
        if len(name) == 1: 
            if self._label is not None and name in self._label: 
                err = f"readonly attribute {name}" 
            elif name.islower(): 
                err = f"cannot set attribute 'a' to 'z' in {cls.__name__}" 
            else: 
                err = "" 
            if err: 
                raise AttributeError(err) 
        super().__setattr__(name, value)

The __getattr__ method serves as a fallback for Python whenever it cannot find an attribute of an object in the object or in any of the parent of the object. To implement our desired feature, our __init__ class is made to have an optional label argument. Our label parameter is set to be None by default meaning that this feature won't be accessible except the user passes in a label argument when creating the object. Before going into the technicalities, let's view the new behavior of our Point object

>>> p = Point((1,2,3), label = 'xyz')
>>> p
# return : Point([1,2,3])
>>> p.x # get the x-axis value
# return : 1
>>> p.y # get the y-axis value
# return : 2
>>> p.z # get the z-axis value
# return : 3
>>> p.x = 10 # assign x attribute of p to a different number
# return : Traceback (most recent call last): 
  File "<stdin>", line 1, in <module> 
  File "test.py", line 45, in __setattr__ 
    raise AttributeError(err) 
AttributeError: readonly attribute x
>>> p.j = 2 # setting a new single letter lower case attribute
# return : Traceback (most recent call last): 
  File "<stdin>", line 1, in <module> 
  File "test.py", line 45, in __setattr__ 
    raise AttributeError(err) 
AttributeError: cannot set attribute 'a' to 'z' in Point
>>> p.some_attribute = 'some_value' # no error
>>> p.some_attribute
# return : 'some_value'

By defining the __getattr__ and the __setattr__ we have given our class instance a whole new ability. As stated before, the __getattr__ method enables our class instance to return specific values based on what label is used but this method doesn't stop a user from modifying (rather creating) a new attribute with one of our label's name. we can comment out the __setattr__ block of code and try the following code

>>> p = Point((1,2,3), label = 'xyz')
>>> p.x
# return : 1
>>> p.x = 10
>>> p.x
# return : 10
>>> p[0] # p still has 1 as it's first value
# return : 1

Remember I did say that the __getattr__ is a fall back method whenever python can't find an attribute (like 'x' in this case). So whenever we call p.x since p by definition does not have an x attribute, __getattr__ is called. But now that we have assigned an attribute x to p with a value 10, calling p.x would return 10 but it won't affect the values in self._coordinates. To stop this behavior, we defined the __setattr__ which Python calls when it wants to assign a new attribute to our object.

By our definition, __setattr__ stops Python from assigning a new attribute whose name is in label or is a lowercase alphabet (because they are special alphabets to our object). If the name of the attribute isn't among the label or a lowercase alphabet, then we return the default behavior by calling super().__setattr__(name, value).

This is why some_attribute can be assigned to our object without raising an error.

Our Point object now has some cool functionalities but lacks a lot, for starters, we cannot add or subtract two instances of our Point instance, find the magnitude of an instance, represent a two-dimensional point as a complex number, and many more. There may be a way to work around these insufficiencies but we can use the special method to implement them and I will show you how we can achieve that in the next article.

It is important to state that our class definition makes a lot of assumptions without implementing a way to validate those assumptions. For instance, there's nothing stopping our user from passing in integers or a list to label instead of string. At the point of initialization, there would be no problem but when we try to get an attribute, our function tries to call find(x) on labels and if labels is not a string, an exception would be raised. We also didn't check if len(label) == len(coordinates) though it doesn't have much effect on our code.

For further study, I'd recommend the Python's official docs as the major reference. You can also check out Fluent Python by Luciano Ramalho. Another resource I came across was this tweet and the follow up tweet by Stephen Gruppetta from which I learnt a great deal about iteration.

I hoped you enjoyed this article and had fun make iterable objects.

Writing Pythonic Code With Python Data Model

Noble-47 — Mon, 17 Feb 2025 00:14:52 +0000

Special Methods

This apparent oddity is the tip of an iceberg that, when properly understood, is the key to everything we call Pythonic. The iceberg is called the Python data model, and it describes the API that you can use to make your own objects play well with the most idiomatic language features. - Luciano Ramalho (Fluent Python: clear, concise, and effective programming)

What's so special about the Python data model one may ask. Rather than giving a personal answer, why don't we do a little dive in and see what we can accomplish by understanding the data model. Data model simply speaks about how data is represented. In Python, data is represented by objects or to sound a bit technical, objects are Python's abstraction for data. The data model provides us with an API that allows our objects to play well with the 'under the hood' of Python programming.

In our little dive into Python data model, we are going to specifically focus on the special methods. Special methods are class functions with special names that are invoked by special syntax. Defining these special methods in our class definitions can give our class instances some really cool Python powers like iteration, operator overloading, working well with context managers (the 'with' keyword), proper string representation and formatting, and many more. To show you how you could implement these special functions into your classes, we will consider two examples of situations where using these special functions would make our codes clearer and more Pythonic.

The first example is a little bit outside-the-box solution I came up with for creating a simple game of Rock-Paper-Scissors in Python and the second is going to be a bit mathematical in nature but I'm going to walk you through each line of code

A Simple Game Of Rock Paper Scissors

Just in case you are not familiar with the Rock-Paper-Scissors game, it is originally a hand game usually played among two people that involves making signs of either Rock or paper or scissors. Knowing the whole history of the game doesn't really matter what is important is knowing how to determine the winner. In a conventional setting, a hand sign of rock would always win against scissors but will lose against paper, a hand sign of scissors would win against paper and lose to rock and obviously, paper would lose to scissors and win against rock. we can summarize this as shown below

For our Python emulation of this game, we will limit the number of players to just two, one player would be the computer and the other would be the user. Also, this is not a machine learning article or a write-up about computer vision, our users would still have to type in an option between rock, paper, and scissors on the terminal for our program to work.
Before we go into the actual coding, it's good that we take a step back and consider how we want our Python script to be. For my solution to this challenge, I will use the random module to enable the computer select a random option of either rock, paper, or scissors. To implement how our code evaluates the winner, I'm going to make the following assumptions:

I'm also going to take an OOP approach; our rock, paper, and scissors will be treated as objects and not string variables. Rather than creating three separate classes for each, I'll create only one that can represent any of them. This approach would also allow me to show you how special methods make life easier. Now to the fun aspect!

Class Definition

Naming our class RPS may sound a bit odd, but I found the name 'RPS' to be a good fit cause each letter comes from the initials, R for Rock, P for Paper, and S for Scissors. What's important to note here is that creating an instance of our class requires two arguments: pick and name. We already stated that the users of our script would have to type in their selected option on the terminal, instead of making our users type in 'Paper' (which could be so stressful for them) why don't we just allow our user to type in 'P' (or 'p') to select 'Paper', that's what the pick stands for. The name property is the actual name e.g 'Paper'. So now that we know what each parameters is for, we can now inspect our class by creating an instance

>>> p = RPS('P', 'Paper') # create an instance
>>> p.name
# return : Paper
>>> p.pick
# return : P
>>> print(p)
# return : <__main__.RPS object at 0x...>

Our class instance was created and has the right attributes but notice what we get when we try to print the contents of the variable holding our class instance. Before getting into the technical details of how our class instance returns the odd-looking string, let's update our class definition by adding a single special function and see the difference.

Now let's create an instance and try printing our class instance again

>>> p = RPS('P', 'Paper')
>>> print(p)
# return : RPS(P, Paper)

As we can see, by defining the 'repr' method we can achieve a better looking result. Let's make one more change to our class definition.

Now let's create an instance and test it again.

>>> p = RPS('P', 'Paper')
>>> p
# return : RPS(P, Paper)
>>> print(p)
# return : Paper
>>> str(p)
# return : 'Paper'
>>> repr(p)
# return : 'RPS(P, Paper)'

To know what's going on here, we need to know a little about the print function. The print function converts all non-keyword arguments(like our p variable) to string using the built-in Python class str. If calling str() on our variable fails, python falls back on the built-in repr function. When str is called on our object, it looks for a __str__ method, if it finds none, it fails and then searches for a __repr__ method. Both the __str__ and the __repr__ methods are special methods used for string representation of our object. The __repr__ method gives the official string representation of our object while the __str__ method gives a friendly string representation of our object. I usually say that the __repr__ method is like talking to another developer and it usually shows how to call our class and the __str__ is like talking to a user of our program (like the player in this case), you would usually just want to return a simple string like "Paper" to show the user what he picked.

Although I stated the __repr__ and __str__ as the two special functions in our class definition, there's actually a third special method, and yes it is the most common one, the __init__ function. It is used for initializing our class and called by the __new__ special method just before returning our class instance. Did I just mention another special method we haven't defined? yes, I did. It may also interest you to know that Python automatically adds some other special methods to our class. You can check them out by calling the built-in function dir on our class instance like this

>>> dir(p)
# returns : ['__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', 'name', 'pick']

Special functions or methods can be identified by the way they are named, they always begin with double underscores '' and end with double underscores '' Because of this special way of naming these methods, they are commonly called daunder methods (Double + UNDERscores = DUNDER). So if a method name begins with double underscores, it is most likely but not certainly a special method. Why not certainly? this is simply because Python does not stop us from defining our own methods using the dunder syntax. Alright back to our game script.

All that's left for us now is for us to let our script know how to determine a winner. As stated earlier, I will use comparison to evaluate a winner.

# comparison logic
Rock > Scissors
Scissors > Paper
Paper > Rock

To implement this solution, I will add a dictionary and use the daunder greater_than method. The dictionary key would be the initials of Rock, Paper and Scissors. The value of each key would be the only other element that the key can defeat.

Notice the new lines of code, first the options dictionary and then the __gt__ method definition. With these new lines of code, let's see what new functionality our code now has.

# create a rock instance
>>> r = RPS('R', 'Rock')

# create a paper instance
>>> p = RPS('P', 'Paper')

# create a scissors instance
>>> s = RPS('S', 'Scissors')

>>> print(r,p,s)
# return : Rock Paper Scissors

>>> p > r # paper wins against rock
# return : True

>>> r > s # rock wins against scissors
# return : True

>>> s > p # scissors wins against paper
# return : True

>>> p < s # paper lose to scissors
# return : True

>>> p < r # paper lose to rock
# return : False

>>> p < s < r# paper lose to scissors which lose to rock
# return : True

>>> p >= r paper wins or tie to rock
# return : Traceback (most recent call last): 
  File "<stdin>", line 1, in <module> 
TypeError: '>=' not supported between instances of 'RPS' and 'RPS'

Just by adding to __gt__ special method, our class instances have gained magical powers (daunder methods are sometimes called magic methods and we can see why). By implementing the daunder gt method, our class instance now relates well with the > and < symbols but not the ≥ and ≤ symbols. The reason is that < is just the negation of >. The special method for < is __lt__(self, x) which can just be the negation of calling __gt__(self,x).

For the ≥ symbol, its special method is the __ge__(self, x) and it must be defined for our object to work well with the ≥ sign. But in this program, we can do without it.

Another missing piece would be to check if two separate instances of Paper are equal.

>>> p1 = RPS("P", "Paper")
>>> p2 = RPS("P", "Paper")
>>> p3 = p1
>>> p1 == p2
# return : False

>>> p1 == p3
# return : True

>>> id(p1)
# return : 140197926465008

>>> id(p2)
# return : 140197925989440

>>> id(p3)
# return : 140197926465008

>>> id(p1) == id(p3)
# return : True

>>> id(p2) == id(p1)
# return False

The default operation of the equal comparison sign is to compare the id of the object. p1 and p2 are different class instances that happen to have the same attributes but their id differs and therefore are not equal. When we assign a variable to a class instance, we make that variable point to the address of the instance which is what we observe for p3 which has the same id as p1. We have the option of overriding how the equality comparison works on our object by defining and implementing our own __eq__(self, other) method. But for this script, I will compare two instances using their pick attribute. Now that we have defined our class and know how it works, we are now ready to see the full implementation of the Python script

Putting It All Together

Let me walk you through the code. We are already familiar with the RPS class definition. If you recall, our code is meant to allow the computer to select choices at random and that's what the random module is for. The random module makes available the choice function which allows the 'random' selection of an element from an iterable object e.g. a list in Python. The list in this case is the option_list. Because our class is made to work with uppercase letters for comparison, it is necessary that we always initialize our objects with uppercase for the pick attribute. This is why we first convert the user's input to upper case (line 34) with the .upper(). It is also possible that our user types in an unexpected character like 'Q' so we have to validate our user input by checking if the uppercase character is part of the valid options in option_list. The mapping dictionary allows us to quickly convert the user's input to a corresponding instance of RPS after being validated. The evaluate_winner function makes use of the comparison symbol to determine the winner. Because we want the code to run in a loop until a winner is found, we make use of a while loop and when a winner is found, the evaluate_winner function returns True which will then break the loop and exit the game.

Here is one of the various results of running the code

Our Python code runs as expected, although there could be a couple of improvements or new features to add. The most important thing is that we see how using special methods in our class definition gives our code a more Pythonic feel. Assuming we were to take a different approach such as using nested if statements, our evaluate_winner method would look something like this

def evaluate_winner(user_choice, comp_choice):
    # check if user choice is 'R'
    if user_choice == 'R':
        # check if comp_choice is 'R'
        if comp_choice == 'R':
            # it is a tie
            ...
        elif comp_choice == 'S':
            # user wins
            ...
        else:
          # computer wins
          ...
    if ... 
     # do the same for when user_choice is 'S' and then for
     # when user_choice is 'P'

A problem with this approach other than the lengthy code is that if we desire to add a new element, diamond which can beat both rock and scissors but not paper (for an unknown reason), our if statements would begin to look really awkward. Whereas in our OOP approach, all we have to do is to modify the options dict like so

options = {"R" : ["S"], "P" : ["R"], "S" : ["P"], "D" : ["R", "S"]}

and then we change the if statement in __gt__ to be

def __gt__(self,x):    
    if x.pick in self.options[self.pick]:
        return True
    else:
        return False

we can make the statement shorter

def __gt__(self, x):
   return True if x.pick in self.options[self.pick] else False

To conclude, here are some things you should note about using special methods:

You hardly (or never) call them directly yourself, let Python do the calling for you
When defining functions that use the dunder naming syntax, you should consider that Python could one day define such a function and give it a different meaning. This could break your code or make it behave in unexpected ways
You certainly don't have to implement every special method there is. Just a couple that you are really sure you need. Remember, simple is better than complex. If there's a simpler way you should use that instead

To learn more about the Python data model I recommend the official Python documentation.

I'll also recommend reading Fluent Python by Luciano Ramalho

This is the first part of the topic, in the next part, we are going to be dealing with operator overloading and making iterable objects

Hope you enjoyed this article!!!