Learning Python with Advent of Code Walkthroughs

Dazbo's Advent of Code solutions, written in Python

The Python Journey - Classes and Objects

Useful Links

Python ClassesDataclasses DocumentationUnderstanding DataclassesDecoratorInheritanceEnum

Here I’ll go into the basics of working with classes and objects in Python. This is not an exhaustive treatment, but should be enough to give you the basics, and should be enough to make my AoC solutions easier to follow.

Page Contents

What is a Class? What is an Object?

Think of a class as a blueprint. It is the blueprint of a thing, where that thing has:

So a class is kind of an abstract concept. But we can create an instance of the class; think of it as building something according to the blueprint. The instance is called an object.

Time for an analogy:

Attributes

The Ford Mustang class has some attributes, e.g.

Attributes are just variables. But they are variables that scoped to the class or object. The attributes above would typically be defined as class attributes, because any instance of this class will have these same attributes.

My Ford Mustang has some additional attributes, e.g.

These are called instance attributes or object attributes, because they are unique to my Mustang.

Methods

A Mustang can do some things…

All of these would be implemented as methods. Methods are just functions; but they are functions that are scoped to the object (or class).

Object-Oriented Programming (OOP)

In simplistic terms, this is simply a way of programming where we primarily use classes and objects to represent things, and we interact with classes and objects using the methods they expose.

In OOP, there are some standard concepts:

Defining a Class

Here we use the simple example of a Dog class:

class Dog():
    """ A Dog class """
    
    def __init__(self, name: str) -> None:
        """ How we create an instance of Dog. """s
        self._name = name   # note how this is intended to be a private instance attribute
        
    # Use the @property decorator to provide a public interface to a method, that resembles an attribute.
    # E.g. we can just reference my_dog.name, rather than my_dog.name().
    @property
    def name(self):
        """ The dog's name """
        return self._name
    
    def bark(self):
        return "Woof!"
    
    def __repr__(self) -> str:
        """ Unambiguously identify an instance. """
        return f"Dog(name={self._name})"
    
    def __str__(self) -> str:
        """ Friendly humand-readable representation of the instance """
        return f"Dog {self._name}"

Some notes:

def __repr__(self) -> str:
    return f"{self.__class__.__name__}(name={self._name})"

To use our Dog class:

dog_a = Dog("Fido") # Create a new dog
dog_b = Dog("Henry") # Create another dog

print(dog_a)    # Print using __str__
print(repr(dog_a))  # Print using __repr__
print(f"dog_a is named {dog_a.name}")  # Get the name using the property
print(dog_a.bark())  # Test the bark() method. Note that we don't pass "self". It is implicit.

print(f"dog_b is named {dog_b.name}")
dog_a.bark()
print(dog_a.bark())

The output looks like this:

Dog Fido
Dog(name=Fido)
dog_a is named Fido
Woof!
dog_b is named Henry
Woof!

Instance vs Class

Attributes

Instance attributes belong to a specific instance of a class, i.e. a specific object. Whereas class attributes belong to the class; this value is common across all instances of the class.

Instance attributes are prefixed with self. They should generally be initialised in the __init__() method. If instance attributes will be set in a different method, then consider first initialising them to None in the __init__() method.

Class attributes are defined outside of any method, and do not include a self prefix.

Here’s a couple of scenarios where we might want to use a class attribute:

class MyClass():
    id = 0
    brand = "Foo"
    
    def __init__(self) -> None:
        self.id = MyClass.id
        MyClass.id += 1
        
my_instance_1 = MyClass()
print(f"ID: {my_instance_1.id}, brand: {MyClass.brand}")
my_instance_2 = MyClass()
print(f"ID: {my_instance_2.id}, brand: {MyClass.brand}")

Here’s the output:

ID: 0, brand: Foo
ID: 1, brand: Foo

Methods

Similarly, it is possible for methods to instance, class methods, or even static methods.

Method Type How to Define How to Use Example Use Case
Instance def some_method(self, parms...) From within the class using self.some_method(parms); from outside the class using my_instance.some_method(parms) Methods that need access to instance attributes.
Class def some_method(cls, parms...) and decorate with @classmethod From within or outside the class using MyClass.some_method(parms) Methods that need access only to class attributes. E.g. to implement a factory method.
Static def some_method(parms...) and decorate with @staticmethod From within or outside the class using MyClass.some_method(parms) Methods that have no need to access or modify either class or instance attributes, but are otherwise logically linked to the class. This means that we could actually implement this method outside of the class; but it makes sense to method definition within the class.

Decorating Methods

Private (implementation) attributes can be named using the prefix _, to discourage direct modification. However, this is convention only. We could then provide get and set methods to access this private attribute. However, this is not considered Pythonic. Remember: Python ≠ Java!!

The alternative is to use the @property decorator. This decorator makes a method accessible as if it were a property. This property helps ensure that only the public implementation is used. For example, where we may want to apply some validation or business logic when assigning a value to a property.

In this example, we make the _age attribute accessible using a @property method called age. We simply reference age as if it were an attribute, not a method.

class MyClass:
    
    def __init__(self, name: str, age: int):
        self._name = name
        self._age = age
        
    def __repr__(self):
        return f"{self._name}: {self._age}"
        
    @property
    def age(self):
        return self._age
    
if __name__ == "__main__":
    bob = MyClass("Bob", 20)
    
    print(bob)
    bob.age = 21
    print(bob)

Printing and Representing

Short Version

Example

class Point2D:

    def __init__(self, x, y) -> None:
        self._x = x
        self._y = y
        
    def __repr__(self) -> str:
        return "Point2D(x={}, y={})".format(self._x, self._y)

Or we can do this:

def __repr__(self) -> str:
    return f"{self.__class__.__name__}(x={self._x}, y={self._y})"

Comparing Objects and Hashing

E.g. here I’ll create a Point class, which represents a point in two-dimensional space. A Point is created from an (x,y) coordinate pair:

from __future__ import annotations

class Point():
    """ Point class, which stores x and y """
        
    def __init__(self, x:int, y:int) -> None:
        self._x = x
        self._y = y
        
    @property
    def x(self):
        return self._x
    
    @property
    def y(self):
        return self._y

    def __hash__(self) -> int:
        return hash((self.x, self.y))
    
    def __eq__(self, o: Point) -> bool:
        return self.x == o.x and self.y == o.y
        
    def __repr__(self) -> str:
        return self.__str__()
    
    def __str__(self) -> str:
        return f"({self._x}, {self._y})"
    
# Now let's test our Point class...
point_a = (5, 10)
print(point_a)
point_b = (6, 5)
print(point_b)
point_c = (5, 10)
print(point_c)

print(f"point_a == point_b? {point_a == point_b}")
print(f"point_a == point_c? {point_a == point_c}")

points = set()
points.add(point_a)

if point_b in points:
    print("point_b already in points")
    
if point_c in points:
    print("point_c already in points")

Output:

point_a == point_b? False
point_a == point_c? True
point_c already in points

Note the import of annotations from __future__. This allows us to reference a type that has not yet been defined. E.g. where we reference a Point argument in method definitions in the Point class. Without this import, trying to run the code above results in this:

Traceback (most recent call last):
  File "f:\Users\Darren\localdev\Python\Advent-of-Code\src\snippets\scratch.py", line 3, in <module>
    class Point():
  File "f:\Users\Darren\localdev\Python\Advent-of-Code\src\snippets\scratch.py", line 21, in Point
    def __eq__(self, o: Point) -> bool:
NameError: name 'Point' is not defined

Inheritance

Overview

Recall that inheritance is an OO concept that allows a class to inherit properties and behaviour from a parent class. Inheritance is used to create an is-a relationship between classes.

Using our simple analogy again:

The class we inherit from is called a parent class. The class that inherits from this parent class is known as any of: child class, subclass or descendent.

In Python, the syntax for inheriting is:

class MyChildClass(MyParentClass):
    # code

Some general notes on inheritance:

Here’s a simple inheritance example:

class Foo:
    def __init__(self) -> None:
        print("Initialising a Foo")
    
    def do_foo(self):
        print(f"{self.__class__.__name__}: I know how to foo")
    
    def __repr__(self):
        return f"I am a {self.__class__.__name__}"
    
class Bar(Foo):
    def __init__(self) -> None:
        super().__init__()
        print("Initialising a Bar")
        
    def do_bar(self):
        print(f"{self.__class__.__name__}: I know how to bar")
    
    def __repr__(self):
        return f"I am a {self.__class__.__name__}"

print("Let's create a Foo...")
foo = Foo()
print(foo)
foo.do_foo()
# foo.do_bar() - We can't do this!

print("\nLet's create a Bar...")
bar = Bar()
print(bar)
bar.do_bar()
bar.do_foo() # Inherited from parent class!

Here’s the output:

Let's create a Foo...
Initialising a Foo
I am a Foo
Foo: I know how to foo

Let's create a Bar...
Initialising a Foo
Initialising a Bar
I am a Bar
Bar: I know how to bar
Bar: I know how to foo

Abstract Base Class (ABC)

We use ABC where we want to provide some methods and/or attributes in a parent class, but it should not be possible to instantiate the parent class. I.e. the parent class is an abstract concept. And we would use this where we want to enforce that certain methods are implemented in a concrete implementation.

For example:


from abc import ABC, abstractmethod
import math

class Shape(ABC):
    def __init__(self):
        super().__init__()

    @abstractmethod
    def calc_area(self):
        pass

    def __str__():
        return "Shape"

class Circle(Shape):
    def __init__(self, radius):
        self._radius = radius

    def calc_area(self):
        return math.pi * self._radius**2
    
    def __str__(self):
        return f"Circle of radius {self._radius}"
    
    def __repr__(self):
        return f"Cicle(radius={self._radius})"

class Square(Shape):
    def __init__(self, side):
        self._length = side
        self._height = side

    def calc_area(self):
        return self._length * self._height

try:
    shape = Shape()
except TypeError as e:
    print(e)

circle = Circle(10)
print(circle.calc_area())

square = Square(10)
print(square.calc_area())

Output:

Can't instantiate abstract class Shape without an implementation for abstract method 'calc_area'
314.1592653589793
100

Multiple Inheritance

Python supports inheriting from multiple base classes. But be careful if base classes have common methods or properties. The method that gets chained from the subclass depends on a thing called Method Resolution Order (MRO).

Example:

class Class_A():
    def __init__(self):
        self._prop_a = "prop a"
        self._common_prop = "from a"
    
    def __str__(self):
        return f"{self._prop_a=}, {self._common_prop=}"

class Class_B():
    def __init__(self):
        self._prop_b = "prop b"
        self._common_prop = "from b"

    def __str__(self):
        return f"{self._prop_b=}, {self._common_prop=}"

class Class_C(Class_A, Class_B):
    pass

class Class_D(Class_B, Class_A):
    pass

my_c = Class_C()
print(my_c)

my_d = Class_D()
print(my_d)

# View MRO
print(Class_D.__mro__)

Output:

self._prop_a='prop a', self._common_prop='from a'
self._prop_b='prop b', self._common_prop='from b'
(<class '__main__.Class_D'>, <class '__main__.Class_B'>, <class '__main__.Class_A'>, <class 'object'>)

Interfaces

Interfaces are a mechanism for defining a “contract” that should be implemented by a class. I.e. the methods that a class must implement.

In most OO languages it is not possible to subclass more than one base class, but it is possible to implement more than one interface. Python is a little different. It offers two approaches to providing interface-like capability:

ABC

As described previously, we can extend ABC and define abstract methods that must be implemented in the subclass.

Best practice: Define one or more classes that extend ABC, providing one or more abstract methods that we want to treat as an interface.

Duck Typing

“If it looks like a duck and quacks like a duck, it’s a duck.”

If the subclass provides the required methods, it is treated as implementing the interface. However, this is not strict enforcement.

Protocols

Python also has the concept of protocols. A protocol is a set of operations or methods that a type must support, in order to implement that protocol. All that is required to support a protocol is for the class to implement the necessary operations. This uses duck typing against a documented set of methods.

For example, take a look at Collection Protocols.

The Object Class

Object is the ultimate base class for all classes in Python. Any class defined without an explicit base class, will extend object.

Magic Methods

These are a set of methods associated with any object, which can be overridden. The take the form __method__(). For example, we can see the magic methods for the object class by during dir(object):

['__class__',
 '__delattr__',
 '__dir__',
 '__doc__',
 '__eq__',			# ==
 '__format__',
 '__ge__',			# >=
 '__getattribute__',      # runs whenever a variable is retrieved
 '__gt__',			# >
 '__hash__',
 '__init__',
 '__init_subclass__',
 '__le__',			# <=
 '__lt__',			# <
 '__ne__',			# !=
 '__new__',
 '__reduce__',
 '__reduce_ex__',
 '__repr__',			# unambiguous representation
 '__setattr__',           # Runs whenever an attribute is set
 '__sizeof__',
 '__str__',			# str representation
 '__subclasshook__']

For example, we can implement equality like this:

def __eq__(self, other):
  if isinstance(other, ThisClass):
    return (self.prop == other.prop ... )
  
  return NotImplemented

Factory Pattern

The factory pattern is a creation design pattern that provides an interface for creating objects in a way that abstracts the instantiation logic. It is particularly well-suited to scenarios where we want to implement objects with different initial properties, but otherwise have identical behaviour.

It is typically implemented using a classmethod that allows us to pass in a type, i.e. a specific type of object implementation.

Here I show a useful way to instantiate a class using factory method. In the example below, one factory method instantiates a Shape given a ShapeType (which is itself a subclass of Enum). Another factory method allows us to instantiate a Shape given a set of points.

from __future__ import annotations
from dataclasses import dataclass
from enum import Enum

class ShapeType(Enum):
    HLINE =       {(0, 0), (1, 0), (2, 0), (3, 0)}
    PLUS =        {(1, 0), (0, 1), (1, 1), (2, 1), (1, 2)}
    BACKWARDS_L = {(0, 0), (1, 0), (2, 0), (2, 1), (2, 2)}
    I =           {(0, 0), (0, 1), (0, 2), (0, 3)}
    SQUARE =      {(0, 0), (1, 0), (0, 1), (1, 1)}    

@dataclass(frozen=True)
class Point():
    """ Point with x,y coordinates and knows how to add a vector to create a new Point. """
    x: int
    y: int
    
    def __add__(self, other):
        """ Add other point/vector to this point, returning new point """
        return Point(self.x + other.x, self.y + other.y)     
    
    def __repr__(self) -> str:
        return f"P({self.x},{self.y})"

class Shape():
    """ Stores points that make up this shape. 
    Has a factory method to create Shape instances based on shape type. """
    
    def __init__(self, points: set[Point], at_rest=False) -> None:
        self.points: set[Point] = points   # the points that make up the shape
        self.at_rest = at_rest
    
    @classmethod
    def create_shape_by_type(cls, shape_type: str, origin: Point):
        """ Factory method to create an instance of our shape.
        The shape points are offset by the supplied origin. """
        return cls({(Point(*coords) + origin) for coords in ShapeType[shape_type].value})

    @classmethod
    def create_shape_from_points(cls, points: set[Point], at_rest=False):
        """ Factory method to create an instance of our shape.
        The shape points are offset by the supplied origin. """
        return cls(points, at_rest)
    
    def __str__(self):
        return f"Shape:({self.points})"

start = Point(0,0)
my_shape = Shape.create_shape_by_type(ShapeType.PLUS.name, start)
print(my_shape)

Another example:

class KeypadMapping():
    NUMERIC = "numeric"
    DIRECTION = "direction"
   
    POINTS_FOR_DIRECTIONS = { "^": Point(0, -1),
                              "v": Point(0, 1),
                              "<": Point(-1, 0),
                              ">": Point(1, 0) }
   
    DIRECTIONS_FOR_POINTS = {v: k for k, v in POINTS_FOR_DIRECTIONS.items()}


    NUMERIC_KEYPAD = [
         ["7", "8", "9"],
         ["4", "5", "6"],
         ["1", "2", "3"],
        [None, "0", "A"]]


    DIRECTION_KEYPAD = [
        [None, "^", "A"],
         ["<", "v", ">"]]
       
    def __init__(self, keypad: list[list[str]]):
        self._keypad = keypad
        self._width = len(keypad[0])
        self._height = len(keypad)


        self._point_to_button: dict[Point, str] = {} {P(0,0): '7', P(1,0): '8',... }
        self._button_to_point: dict[str, Point] = {} # {'7': P(0,0), '8': P(1,0), ..., }
        self._build_keypad_dict()
        self._paths_for_pair = self._compute_paths_for_pair()
        self._path_lengths_for_pair = {pair: len(paths[0]) for pair, paths in
                                         self._paths_for_pair.items()}
   
    @classmethod
    def from_type(cls, keypad_type: str):
        """ Factory method to create a KeypadMapping instance with predefined keypads. """
       
        match keypad_type:
            case KeypadMapping.NUMERIC: return cls(KeypadMapping.NUMERIC_KEYPAD)
            case KeypadMapping.DIRECTION: return cls(KeypadMapping.DIRECTION_KEYPAD)
            case _: raise ValueError(f"Unknown keypad type: {keypad_type}")
           
    def _build_keypad_dict(self):
        """ Build a dictionary of keypad points and their associated keys. """
               
        for r, row in enumerate(self._keypad):
            for c, key in enumerate(row):
                if key:
                    self._point_to_button[Point(c, r)] = key
                    self._button_to_point[key] = Point(c, r)

Alternatively we could have created subclasses for Direction and Numeric types. However, the factory pattern allows simpler dynamic selection of the type at runtime. Subclassing would be better if the subclasses have distinct behaviour. In this case, the only difference is one property.

Dataclass

Overview

This is a very cool decorator which helps us save some time and effort, by circumventing the need to write lots of repetetive boilerplate code, when we want to create a class that mostly serves the purpose of storing and exposing some data.

Cool things about a dataclass:

To make something a dataclass, simply add @dataclass before the class definition. You will also need to import dataclass.

Now I’ll recreate the above Point class, and call it in exactly the same way, but this time implement as a dataclass. Look how much shorter it is!!

from dataclasses import dataclass

@dataclass
class Point():
    """ Point class, which stores x and y """
    x: int
    y: int

# Now let's test our Point class...
point_a = (5, 10)
print(point_a)
point_b = (6, 5)
print(point_b)
point_c = (5, 10)
print(point_c)

print(f"point_a == point_b? {point_a == point_b}")
print(f"point_a == point_c? {point_a == point_c}")

points = set()
points.add(point_a)

if point_b in points:
    print("point_b already in points")
    
if point_c in points:
    print("point_c already in points")

Immutable (Frozen) Objects

Add frozen=True if you want the dataclass to be immutable. I.e.

@dataclass(frozen=True)
class Point2D():
    """ Our immutable point data class """

Note that with a frozen dataclass, you can’t modify any attributes after the __init__(). However, there is a standard workaround to allow you to use __post_init__():

@dataclass(frozen=True)
class Rectangle:
    width: int
    height: int
    area: int = field(init=False)

    def __post_init__(self):
        # bypass immutability and set the derived field
        object.__setattr__(self, "area", self.width * self.height)

Field Properties

Useful for not only setting defaults, but also for changing field behaviour. For example here, we want a field to be ignored in equality checks

from dataclasses import dataclass, field


@dataclass(frozen=True, eq=True)
class Amphipod():
    type: str
    moving: int = field(default=0, compare=False, hash=False)

We can even supply a default_factory, rather than default. Then pass a function that will set the initial value.

Post_Init Processing

The __post_init__() method runs AFTER the __init__() method for an object. A common use case is to initialise variables that are not supplied during object instantiation.

In this example, initial_posn has init=False, meaning it is not initialised (or expected) by the __init__() method. Instead, it is set programmatically in the __post_init__() method.

Also, we have defined two class variables.

@dataclass
class Robot:
    """ A robot that wanders the warehouse. It has a starting position and fixed velocity. """
   
    posn: Point # current position
    velocity: Point
   
    # Instance variable to store the initial position
    initial_posn: Point = field(init=False)
   
    # Class variables - for efficiency
    width: ClassVar[int] = 0
    height: ClassVar[int] = 0
   
    def __post_init__(self):
        """ Set initial_posn after initialization """
        self.initial_posn = self.posn
       
    def posn_at_t(self, t: int) -> Point:
        """ Return the position at time t """
        new_x = (self.initial_posn.x + t*self.velocity.x) % Robot.width
        new_y = (self.initial_posn.y + t*self.velocity.y) % Robot.height
        return Point(new_x, new_y)
   
    def move(self) -> Point:
        """ Increment the current position by the velocity vector """
        new_x = (self.posn.x + self.velocity.x) % Robot.width
        new_y = (self.posn.y + self.velocity.y) % Robot.height
        self.posn = Point(new_x, new_y)
        return self.posn

Versus NamedTuple

Similar to using dataclass, Python also has something called a NamedTuple. This allows us to define a an immutable class with only attributes. Thus, a NamedTuple is very similar to a frozen (immutable) dataclass. The dataclass is a lot more powerful and flexible than NamedTuple, but it incurs a performance hit. You should probably use dataclass in preference to NamedTuple, unless performance is paramount.

Point = NamedTuple("Point", [("x", Number), ("y", Number)])

def manhattan_distance(a_point: Point):
    return abs(a_point.x) + abs(a_point.y)

def manhattan_distance_from(self, other):
    diff = self - other
    return manhattan_distance(diff)

Point.__add__ = lambda self, other: Point(self.x + other.x, self.y + other.y)
Point.__sub__ = lambda self, other: Point(self.x - other.x, self.y - other.y)
Point.__mul__ = lambda self, scalar: Point(self.x * scalar, self.y * scalar)
Point.__rmul__ = lambda self, scalar: self * scalar # for when int comes first
Point.manhattan_distance = staticmethod(manhattan_distance)
Point.manhattan_distance_from = manhattan_distance_from
Point.__repr__ = lambda self: f"P({self.x},{self.y})"

Examples