nx1.info | Object-Oriented Design in Python

These are notes from the book Practical Object-Oriented Design in Ruby that I have adapted into Python. | (link) | (More books r-5.org) This book is extremely good at explaining why to do things a certain way as opposed to simply how (which is what I found 99% of object OOP content on the internet seemed to be). The book is written for Ruby however the principles hold for any OO language.

Table of Contents (click to jump)

1. Object-Oriented Design 2. Designing Classes with a Single Responsibility - Deciding What Belongs in a Class - Grouping Methods into Classes - Organizing Code to Allow for Easy Changes - Creating Classes That Have a Single Responsibility - An Example Application: Bicycles and Gears - Why Single Responsibility Matters - Determining If a Class Has a Single Responsibility - Determining When to Make Design Decisions - Writing Code That Embraces Change - Depend on Behavior, Not Data - Enforce Single Responsibility Everywhere - Finally, the Real Wheel - Summary 3. Managing Dependencies - Understanding Dependencies - Recognizing Dependencies - Coupling Between Objects (CBO) - Other Dependencies - Writing Loosely Coupled Code - Inject Dependencies - Isolate Dependencies - Remove Argument-Order Dependencies - Managing Dependency Direction - Reversing Dependencies - Choosing Dependency Direction - Summary 4. Creating Flexible Interfaces - Understanding Interfaces - Defining Interfaces - Public Interfaces - Private Interfaces - Responsibilities, Dependencies, and Interfaces - Finding the Public Interface - An Example Application: Bicycle Touring Company - Constructing an Intention - Using Sequence Diagrams - Asking for “What” Instead of Telling “How” - Seeking Context Independence - Trusting Other Objects - Using Messages to Discover Objects - Creating a Message-Based Application - Writing Code That Puts Its Best (Inter)Face Forward - Create Explicit Interfaces - Honor the Public Interfaces of Others - Exercise Caution When Depending on Private Interfaces - Minimize Context - The Law of Demeter - Defining Demeter - Consequences of Violations - Avoiding Violations - Listening to Demeter - Summary 5. Reducing Costs with Duck Typing - Understanding Duck Typing - Overlooking the Duck - Compounding the Problem - Finding the Duck - Consequences of Duck Typing - Writing Code That Relies on Ducks - Recognizing Hidden Ducks - Placing Trust in Your Ducks - Documenting Duck Types - Sharing Code Between Ducks - Choosing Your Ducks Wisely - Conquering a Fear of Duck Typing - Subverting Duck Types with Static Typing - Static versus Dynamic Typing - Embracing Dynamic Typing - Summary 6. Acquiring Behavior Through Inheritance - Understanding Classical Inheritance - Recognizing Where to Use Inheritance - Starting with a Concrete Class - Embedding Multiple Types - Finding the Embedded Types - Choosing Inheritance - Drawing Inheritance Relationships - Misapplying Inheritance - Finding the Abstraction - Creating an Abstract Superclass - Promoting Abstract Behavior - Separating Abstract from Concrete - Using the Template Method Pattern - Implementing Every Template Method - Managing Coupling Between Superclasses and Subclasses - Understanding Coupling - Decoupling Subclasses Using Hook Messages - Summary 7. Sharing Role Behavior with Modules - Understanding Roles - Finding Roles - Organizing Responsibilities - Removing Unnecessary Dependencies - Writing the Concrete Code - Extracting the Abstraction - Looking Up Methods - Inheriting Role Behavior - Writing Inheritable Code - Recognize the Antipatterns - Insist on the Abstraction - Honor the Contract 8. Testing - Testing Private Methods - Ignoring Private Methods During Tests - Removing Private Methods from the Class Under Test - Choosing to Test a Private Method - Testing Outgoing Messages - Ignoring Query Messages - Proving Command Messages - Testing Duck Types - Testing Roles - Using Role Tests to Validate Doubles - Testing Inherited Code - Specifying the Inherited Interface - Specifying Subclass Responsibilities - Testing Unique Behavior - Summary

Chapter 1: Object-oriented design (OOD)

While procedural programming follows a fixed sequence of steps, OOD models the world as interacting objects with independent behaviors. This enables emergent behavior without explicitly coding every scenario. OOD requires shifting perspective from procedures to message-passing between objects. Software exists to fulfill a purpose, and efficient, enjoyable programming aligns with cost-effective development. Object-oriented design (OOD) addresses both technical and moral challenges by making code flexible and maintainable. While a perfectly static application wouldn't require design, real-world software inevitably changes. Changing requirements introduce challenges akin to friction and gravity, making adaptability crucial. Well-designed applications are easy to modify and extend, while rigid ones become costly and frustrating to maintain. Change is difficult because object-oriented applications consist of interconnected parts that depend on each other. Dependencies make objects resistant to modification, causing small changes to ripple unpredictably through the system. Poorly managed dependencies lead to inflexible, hard-to-test, and duplicated code. While bad design in small applications may be manageable, as they grow, they become fragile and difficult to maintain. Good design minimizes dependencies, making code easier to change, reuse, and test. Design is the arrangement of code within an application, and it varies between programmers like an art form. Good design balances immediate functionality with future adaptability, as the cost of change will eventually surpass initial development costs. Practical design does not try to predict specific future requirements but instead keeps options open. Its main purpose is to make future design possible and reduce the cost of change. Design is both an art and a science. While every programmer arranges code differently, good design follows established principles that reduce the cost of change and keep future options open. The SOLID principles, DRY, and the Law of Demeter emerged from experience, but their effectiveness was later confirmed through empirical research. Early studies measured object-oriented design metrics in small applications, and later studies—such as those analyzing NASA software—validated that well-designed code correlates with higher quality and lower costs. Ultimately, good design isn't just opinion; it has measurable benefits. The Gang of Four (GoF) formalized common solutions to recurring design problems, making software more modular, reusable, and understandable. Patterns provide a shared language for developers, improving communication and collaboration. However, misuse—applying patterns to the wrong problems—can lead to overly complex code. While this book does not focus on patterns, it aims to equip readers with the foundational knowledge needed to understand and apply them effectively. While object-oriented design (OOD) principles and patterns provide a strong foundation, applying them effectively remains a challenge. Design is not just about knowing the right principles—it requires skill, experience, and judgment. The analogy to woodworking highlights that having good tools doesn’t guarantee good results; mastery comes from practice. Well-designed software, like well-crafted furniture, depends on the expertise of the creator. ways design fails: Lack of Design: Beginners can write working applications without understanding design principles, but these applications become difficult to modify over time. Early ease leads to long-term frustration as changes break everything. Overdesign: Intermediate programmers, excited by their newfound knowledge, overapply principles and patterns, creating rigid, overly complex systems. Instead of allowing for flexibility, their designs become barriers to change. Disconnected Design: When design is separated from programming, often in rigid top-down approaches, it fails to evolve with real-world needs. Without iterative feedback, initial misunderstandings become baked into the system, leading to impractical implementations. The key takeaway is that good design is iterative and must evolve alongside development. Agile methodologies align well with this approach, ensuring that design remains adaptable and responsive to real-world changes. Good software design isn't about writing the most code or following arbitrary metrics—it’s about ``minimizing the long-term cost of change'' while delivering features in a reasonable timeframe.

Chapter 2: Designing Classes with a Single Responsibility

Common Questions in Class Design: - How many classes should there be? - What behavior should they implement? - How much should one class know about others? - How much should a class expose of itself to the outside world? Simplicity is Key: - In the early stages, the goal is to keep things simple. - The application should work but also be easy to change later. - Immediate functionality can be achieved through brute force, but ease of change is more challenging and requires thoughtful design. - Easy changeability is what separates good programming from functional programming. It involves skill, experience, and a bit of creativity. Creating Easy-to-Change Applications: - Making an application easy to change requires knowledge of design principles that promote flexibility and maintainability. - By understanding and applying them, one can structure classes to be both functional now and flexible in the future. Deciding What Belongs in a Class: When designing an object-oriented application, one is faced with the challenge of deciding what should belong in each class. While the implementation of the application might be clear, the organizational structure is what often proves difficult. The focus on grouping methods into classes and making these decisions in a way that allows for future flexibility. Grouping Methods into Classes: - The classes defined will shape how you and others perceive and interact with the code. They set the boundaries for how functionality is structured, and they can potentially constrain future development. - Perfect organization isn’t expected at the start. Design is a balance between the current needs and the potential future changes. - Preserving flexibility is more critical than achieving a perfect structure at the outset. Good design allows for easy changesin the future, even when initial choices are inevitably wrong. Organizing Code for Easy Changes: The goal is to create code that is easy to change when needed. Easy to change means: - No unexpected side effects from changes - Small changes lead to proportionally small code modifications - Code is reusable in new contexts - The easiest way to change code is to add new code that is also easy to change The mnemonic TRUE (Transparent, Reasonable, Usable, Exemplary): Transparent: The consequences of any change should be clear both in the code that is changing and in the code that relies on it. Reasonable: The cost of any change should be proportional to the benefit it provides. Avoid over-engineering or making changes that are costly without significant advantages. Usable: Existing code should be adaptable and usable in unexpected or new contexts without requiring significant rewrites. Exemplary: The code should encourage future developers to maintain these qualities, making it easy to modify in the future.

Creating Classes That Have a Single Responsibility

On a bicycle, the gear ratio is:

gear_ratio = N_chainring / N_cog

Nouns like "bicycle" and "gear" are candidates for classes, but while "bicycle" lacks specific behavior, "gear" involves data and behavior (chainrings, cogs, and ratios), making it suitable for a class.

class Gear:
    def __init__(self, chainring, cog):
        self.chainring = chainring
        self.cog = cog

    def ratio(self):
        return self.chainring / float(self.cog)

print(Gear(52, 11).ratio()) # 4.72727272727273
print(Gear(30, 27).ratio()) # 1.11111111111111

Your cyclist friend requests an enhancement to the Gear calculator. She has two bikes with the same gearing but different wheel sizes, and wants to account for the impact of wheel size on the calculation. Larger wheels cover more distance with each rotation compared to smaller ones. To address this, you need to calculate "gear inches" which combines both the gear ratio and wheel size using the formula: \( \mathrm{gear \ inches} = D_{\mathrm{wheel}} \times \mathrm{gear \ ratio} \) Where: \( D_{\mathrm{wheel}} = D_{\mathrm{rim}} + 2 D_{\mathrm{tire}} \) This allows cyclists to compare bikes with different wheel sizes based on their gearing and wheel size together. We can change the gear class to add this behavior:

class Gear:
    def __init__(self, chainring, cog, rim, tire):
        self.chainring = chainring
        self.cog = cog
        self.rim = rim
        self.tire = tire

    def ratio(self):
        return self.chainring / float(self.cog)

    def gear_inches(self):
        return self.ratio() * (self.rim + (2*self.tire))

print(Gear(52, 11, 26, 1.5).gear_inches()) # 137.1
print(Gear(30, 27, 24, 1.25).gear_inches()) # 125.2

Writing Code That Embraces Change: 1. Depend on Behavior, Not Data - Encapsulate behavior in methods instead of directly accessing data. DRY (Don't Repeat Yourself) to ensure each behavior exists in only one place. - This makes changes easier since modifying a single method updates behavior everywhere it's used. - Behavior exists in methods and is triggered by messages. - Single-responsibility classes ensure each piece of behavior has one authoritative location. 2. Hide Instance Variables - Instead of referring directly to instance variables, wrap them in accessor methods. - In Python this is usually done using the @property decorator. and private attributes proceeeded by an underscore.

class Gear:
def __init__(self, chainring, cog, adjustment_factor=1):
    self._chainring = chainring
    self._cog = cog
    self._adjustment_factor = adjustment_factor

@property
def cog(self):
    return self._cog * self._adjustment_factor  # Now cog is dynamic

def ratio(self):
        return self._chainring / float(self.cog)  # Uses encapsulated property

This may seem pointless, however, implementing this method changes cog from data (which is referenced all over) to behavior (which is defined once). If the _cog instance variable is referred to ten times and it suddenly needs to be adjusted, the code will need many changes. However, if _cog is wrapped in a method, you can change what cog means by implementing your own version of the method. Dealing with data as if it’s an object that understands messages introduces two new issues: 1. Visibility: Wrapping the _cog instance variable in a public cog method exposes this variable to the other objects in your application; any other object can now send cog to a Gear. It would have been just as easy to create a private wrapping method, although in python there is no explicit private methods, they are often indicated by proceeding underscores _ . Although thinking about this this is not really an issue in python since attributes in classes can be freely accessed by externally. 2. Because it’s possible to wrap every instance variable in a method and to therefore treat any variable as if it’s just another object, the distinction between data and a regular object begins to disappear. While it’s sometimes expedient to think of parts of your application as behavior-less data, most things are better thought of as plain old objects. Regardless of how far your thoughts move in this direction, you should hide data from yourself. Doing so protects the code from being affected by unexpected changes. Data very often has behavior that you don’t yet know about. Send messages to access variables, even if you think of them as data.

Hide Data Structures

This principle applies directly to Python, and the equivalent approach would involve encapsulation and creating structured objects instead of relying on nested data structures. Bad Approach: Exposing a Raw Data Structure

class ObscuringReferences:
    def __init__(self, data):
        self.data = data  # Stores a 2D array

    def diameters(self):
        # Hardcoded knowledge of the structure (BAD)
        return [cell[0] + (cell[1] * 2) for cell in self.data]
    
# Example usage 
data = [[622, 20], [622, 23], [559, 30], [559, 40]]
obscure = ObscuringReferences(data)
print(obscure.diameters())  # [662, 668, 619, 639]

Why is this bad? - `diameters()` directly references the structure of `data`. If `data` changes, this method (and others) will break. - If other methods also depend on `cell[0]` and `cell[1]`, this structure is duplicated across the class. - Hard-to-maintain: If `data` changes (e.g., from lists to dictionaries), you have to update every reference. Good Approach: Encapsulate the Data in Objects Instead of exposing raw arrays, we encapsulate the structure in a `Wheel` class, similar to the Ruby `Struct`.

from collections import namedtuple

class RevealingReferences:
    Wheel = namedtuple('Wheel', ['rim', 'tire'])  # Struct-like object

    def __init__(self, data):
        self.wheels = self._wheelify(data)  # Convert raw data to structured objects

    def _wheelify(self, data):
        """Convert list of lists into list of Wheel objects"""
        return [self.Wheel(rim, tire) for rim, tire in data]

    def diameters(self):
        """Compute diameters using structured data"""
        return [wheel.rim + (wheel.tire * 2) for wheel in self.wheels]

# Example usage:
data = [[622, 20], [622, 23], [559, 30], [559, 40]]
revealed = RevealingReferences(data)
print(revealed.diameters())  # [662, 668, 619, 639]

Why is this better? - `diameters()` no longer cares about the internal structure of the data. - `cell[0]` --> `wheel.rim`, making the code more readable and less error-prone. - `_wheelify()` isolates the transformation logic. If the input format changes, you only modify this one method. Even Better: Use a Proper Class Instead of `namedtuple` If `Wheel` needs more behavior, we can use a class instead of `namedtuple`:

class Wheel:
    def __init__(self, rim, tire):
        self.rim = rim
        self.tire = tire

    def diameter(self):
        return self.rim + (self.tire * 2)

class RevealingReferences:
    def __init__(self, data):
        self.wheels = self._wheelify(data)

    def _wheelify(self, data):
        return [Wheel(rim, tire) for rim, tire in data]

    def diameters(self):
        return [wheel.diameter() for wheel in self.wheels]

# Example usage:
data = [[622, 20], [622, 23], [559, 30], [559, 40]]
revealed = RevealingReferences(data)
print(revealed.diameters())  # [662, 668, 619, 639]

Benefits of using a full class: - The logic of `diameter()` belongs inside `Wheel`, making `RevealingReferences` even simpler. - If `Wheel` later needs more behavior (e.g., weight calculations), it can be added without modifying `RevealingReferences`. Takeaways: - Don't expose raw data structures. Convert them into meaningful objects. - Encapsulate transformation logic. Use a method like `_wheelify()` to isolate messy data. - Use namedtuples or classes to replace nested data structures. - Make behavior belong to the object. The `diameter()` method should be in `Wheel`, not in `RevealingReferences`.

Enforce Single Responsibility Everywhere

Designing classes with a single responsibility improves maintainability, but the same principle applies beyond class design—it should be used throughout your code. Extract Extra Responsibilities from Methods: Just like classes, methods should also have a single responsibility. This makes them easier to modify and reuse. You can apply the same design techniques—ask what the method does and try to summarize its responsibility in one sentence. Consider the `diameters` method in a `RevealingReferences` class:

def diameters(self):
    return [wheel.rim + (wheel.tire * 2) for wheel in self.wheels]

This method has two responsibilities: 1. iterating over `self.wheels` 2. calculating the diameter of each wheel. To simplify the code, separate these responsibilities into distinct methods. The refactored version moves the diameter calculation to its own method:

def diameters(self): 
    return [self.diameter(wheel) for wheel in self.wheels] 

def diameter(self, wheel):
    return wheel.rim + (wheel.tire * 2)

Would you ever need to calculate the diameter of just one wheel? You already do! This refactoring isn’t overengineering it simply makes the code cleaner and easier to use elsewhere.

Identifying Hidden Responsibilities

Separating iteration from the action performed on each element is an easy-to-spot case of multiple responsibilities. However, sometimes the issue is more subtle. Take the `gear_inches` method from a `Gear` class:

def gear_inches(self):
    return self.ratio * (self.rim + (self.tire * 2))

Does `gear_inches` belong in `Gear`? It might seem reasonable at first, but something about it feels wrong it’s messy and unclear. The real issue is that it does more than one thing. Hidden inside `gear_inches` is the calculation for wheel diameter. Extracting that logic into a separate method makes the class's responsibilities clearer:

def gear_inches(self):
    return self.ratio * self.diameter()

def diameter(self):
    return self.rim + (self.tire * 2)

Now, `gear_inches` simply retrieves the diameter instead of computing it. The logic remains unchanged, but the structure is far better. Even when you aren’t sure about the final design, these refactorings help. Good practices don’t require knowing the end goal—they help reveal it. The benefits of single-responsibility methods include: - Making hidden design flaws obvious – Refactoring methods to have a single responsibility clarifies what a class actually does. Even if you don’t move methods into different classes right away, making their purpose explicit helps future design decisions. - Reducing the need for comments – Comments often become outdated, as they aren’t executable. If a method requires a comment to explain what part of it does, extract that part into a separate method instead. The method name now conveys the meaning. - Encouraging reuse – Small methods naturally lead to reusable code. Other developers (or your future self) will reuse methods instead of duplicating logic, reinforcing good coding habits. - Making code easier to refactor – When design changes arise, small methods are easier to move between classes, reducing the effort needed to restructure code. While each individual refactoring may seem small, their combined impact results in cleaner, more maintainable code.

Finally, the Real Wheel

While you're refining the design of the Gear class, a new request comes in. You show your calculator to your cyclist friend again, and she tells you that while it’s nice, she’d also like a way to calculate "bicycle wheel circumference." Her bike computer needs this information to properly calculate speed. This is exactly the kind of feature request that informs your next design decision. \(\mathrm{circumference} = Dπ\). embedded Wheel class already calculates diameter, adding a method to compute circumference is straightforward. However, this request also reveals that your application now has a clear need for a standalone Wheel class, independent of Gear. It’s time to separate Wheel into its own class. Because you've already isolated wheel-related behavior within the Gear class, extracting it is painless. You just need to convert the existing Wheel logic into a separate class and add the new circumference method:

import math

class Gear:
    def __init__(self, chainring, cog, wheel=None):
        self.chainring = chainring
        self.cog = cog
        self.wheel = wheel

    def ratio(self):
        return self.chainring / float(self.cog)

    def gear_inches(self):
        return self.ratio() * self.wheel.diameter()

class Wheel:
    def __init__(self, rim, tire):
        self.rim = rim
        self.tire = tire

    def diameter(self):
        return self.rim + (self.tire * 2)

    def circumference(self):
        return self.diameter() * math.pi

# Example usage:
wheel = Wheel(26, 1.5)
print(wheel.circumference())  
# -> 91.106186954104

print(Gear(52, 11, wheel).gear_inches())  
# -> 137.090909090909

print(Gear(52, 11).ratio())  
# -> 4.72727272727273

Both classes now have a single responsibility. While the design isn’t perfect,
it achieves an important goal: it is good enough. Summary

The foundation of changeable and maintainable object-oriented software lies in
classes with a single responsibility. Classes that focus on one thing remain
isolated from the rest of the application, making them easy to change without
unintended consequences and easy to reuse without duplication.

Chapter 3: Managing Dependencies

Collaborating Objects and Managing Dependencies

Object-oriented programming languages model real-world problems naturally.
Objects represent qualities of a real-world system, and their interactions
provide solutions. These interactions are unavoidable no single object can know
everything, so it must communicate with others.  

If you could observe the internal workings of a complex application, the flow
of messages between objects might seem overwhelming. However, stepping back to
see the bigger picture reveals a pattern:
    - every [message] originates from an [object] to trigger some [behavior].

The [behavior] itself is distributed among different [objects].
For any given [action] an [object]:
    - either knows how to do it itself
    - inherits the behavior
    - knows another object that can do it.  

The previous chapter focused on the first case: ensuring that a class
implements its own behavior. The second case inheriting behavior will be
covered in Chapter 6. This chapter focuses on the third: accessing behavior
implemented in other objects.

Because well-designed objects follow the single responsibility principle,
they must collaborate to perform complex tasks. This collaboration is both
powerful and risky. For an object to work with another, it must have some
knowledge of it. This creates **dependencies**, which, if not carefully
managed, can make your application fragile and difficult to maintain.

Understanding Dependencies

An object depends on another object if changes in one force modifications in
the other:
class Gear:
    def __init__(self, chainring, cog, rim, tire):
        self.chainring = chainring
        self.cog = cog
        self.rim = rim
        self.tire = tire

    def gear_inches(self):
        return self.ratio() * Wheel(self.rim, self.tire).diameter()

    def ratio(self):
        return self.chainring / float(self.cog)


class Wheel:
    def __init__(self, rim, tire):
        self.rim = rim
        self.tire = tire

    def diameter(self):
        return self.rim + (self.tire * 2)


print(Gear(52, 11, 26, 1.5).gear_inches())

Gear has dependencies on Wheel.
If Wheel changes, Gear may need to change as well.

Here are four dependencies that make Gear harder to maintain:

    1. Explicit instantiation:
    Gear() directly creates a Wheel() instance instead of accepting an existing
    one. If Wheel's initialization changes, Gear must also change.

    2. Hardcoded structure:
    Gear assumes that Wheel will always be initialized with rim and tire. If
    Wheel's arguments change, Gear will break.

    3. Direct method call:
    Gear calls Wheel().diameter() directly, assuming this method exists. If
    diameter() is renamed or removed, Gear must be updated.

    4. Implicit coupling:
    Gear knows too much about Wheel’s internal behavior, reducing flexibility
    and making modifications risky.


These dependencies are unnecessary and make Gear harder to change. A better
design would inject a Wheel instance into Gear rather than having Gear create
it internally.


Recognizing Dependencies in Python

A class has a dependency when it knows:

    1. The name of another class:
    Gear() explicitly references Wheel(), assuming it exists.

    2. The name of a method it intends to call on another object:
    Gear expects Wheel to have a diameter() method.

    3. The arguments required by another class's constructor:
    Gear assumes Wheel is initialized with rim and tire.

    4. The order of those arguments:
    Gear expects Wheel(rim, tire), meaning changes to this order could break it.

Each of these dependencies makes Gear tightly coupled to Wheel, increasing the
risk that changes to Wheel will force changes in Gear.

Why Is This a Problem?

    If Wheel changes, Gear must also change:
    If Wheel.__init__ changes, Gear's call to Wheel(self.rim, self.tire) will break.

    Reusability is reduced:
    Gear cannot easily work with a different wheel-like object
    because it assumes a specific Wheel class.

    Testing becomes harder:
    Gear cannot be tested in isolation since it always requires a Wheel instance.

The Design Challenge

A good design minimizes dependencies so that each class only knows what it
absolutely needs to function. The next step is refactoring to reduce coupling
and improve flexibility.

Coupling Between Objects (CBO)

These dependencies couple Gear to Wheel. In other words, each coupling 
creates a dependency. The more Gear knows about Wheel, the tighter the 
coupling. When two objects are tightly coupled, they effectively behave 
as a single unit.

hen objects are so tightly coupled that they act as one unit, it becomes 
impossible to reuse just one. Changes to one force changes to all, and unmanaged 
dependencies can turn minor tweaks into major undertakings.

Other dependency issues include:
  - Chained messages: When an object relies on a series of calls to reach a 
    behavior in a distant object, increasing the chance that any change 
    affects the entire chain.
  - Over-coupled tests: Tests written too tightly to the code may break 
    every time the code is refactored, even if the core behavior remains the 
    same.

Despite these challenges, you can avoid a tangled mess of dependencies by 
recognizing and managing them carefully. The design goal is to have each 
class know only what is necessary for its function.


Writing Loosely Coupled Code
Inject Dependencies
class Gear:
def __init__(self, chainring, cog, rim, tire):
        self.chainring = chainring
        self.cog = cog
        self.rim = rim
        self.tire = tire

    def gear_inches(self):
        return self.ratio() * Wheel(self.rim, self.tire).diameter()

    def ratio(self):
        return self.chainring / float(self.cog)

Gear explicitly calls Wheel(self.rim, self.tire)
If the name of the Wheel class changes, Gear's gear_inches method must also
change.

Although this dependency might seem minor (and can be fixed with a global find/
replace), it reveals a deeper problem. When Gear hard-codes a reference to Wheel,
it declares that it is only willing to calculate gear inches for instances of Wheel.
Gear refuses to collaborate with any other kind of object, even if that object
has a diameter.

If your application later includes objects such as disks or cylinders that have a
diameter, Gear won't be able to calculate their gear inches because it is stuck
to Wheel.

The code above forces an unjustified attachment to static types. Gear only needs
an object that responds to diameter; it doesn't care about the object's class.
This tight coupling reduces Gear's reusability and makes it more likely to break
if any dependency changes.

To decouple, refactor Gear so it is initialized with an object that responds to
diameter:
class Gear:
    def __init__(self, chainring, cog, wheel):
        self.chainring = chainring
        self.cog = cog
        self.wheel = wheel

    def gear_inches(self):
        return self.ratio() * self.wheel.diameter()

    def ratio(self):
        return self.chainring / float(self.cog)

Now, Gear does not care if the object is an instance of Wheel. It only needs an
object that implements a diameter method.

This technique is known as dependency injection. It reduces Gear's explicit
dependencies on the Wheel class and its constructor arguments, limiting Gear's
dependency to just the diameter method. Gear becomes smarter by knowing less.

Dependency injection relies on the idea that the responsibility for knowing a
class's name and the responsibility for sending a specific message may belong in
different objects. Just because Gear needs to call diameter does not mean it
should know about Wheel.

In summary, by injecting dependencies, you reduce coupling, increase reusability,
and make your code more flexible.

Isolate Dependencies

It's best to break all unnecessary dependencies, but while this is always 
technically possible, it may not be practically feasible. When working on an 
existing application, you might face severe constraints on how much you can change.
If perfection is out of reach, aim to improve the overall situation by leaving the 
code better than you found it.

If you cannot remove unnecessary dependencies, isolate them within your class. 
In "Designing Classes with a Single Responsibility," you isolated extra 
responsibilities so they would be easy to recognize and remove when the time was 
right. Here, isolate unnecessary dependencies so they are easy to spot and reduce 
when circumstances permit.

Think of every dependency as an alien bacterium trying to infect your class. 
Give your class a vigorous immune system; quarantine each dependency. Dependencies 
are foreign invaders that represent vulnerabilities, so they should be concise, 
explicit, and isolated.

Isolate Instance Creation
If you're so constrained that you cannot change the code to inject a Wheel into a 
Gear, isolate the creation of a new Wheel within the Gear class. The idea is to 
explicitly expose the dependency while reducing its reach in your class.

Example 1: Move the creation of a new Wheel from the gear_inches method to the 
initialization method. This cleans up gear_inches and publicly exposes the 
dependency in __init__. Note that this technique creates a new Wheel every time 
a new Gear is instantiated.
class Gear:
    def __init__(self, chainring, cog, rim, tire):
        self.chainring = chainring
        self.cog = cog
        self._wheel = Wheel(rim, tire)

    def gear_inches(self):
        return self.ratio() * self._wheel.diameter()

    def ratio(self):
        return self.chainring / float(self.cog)

Example 2: Isolate the creation of a new Wheel in its own wheel method. This 
method lazily creates a new Wheel using a caching technique. The new Wheel is 
created only when gear_inches calls the wheel method.
class Gear:
    def __init__(self, chainring, cog, rim, tire):
        self.chainring = chainring
        self.cog = cog
        self.rim = rim
        self.tire = tire
        self._wheel = None

    def gear_inches(self):
        return self.ratio() * self.wheel().diameter()

    def ratio(self):
        return self.chainring / float(self.cog)

    def wheel(self):
        if self._wheel is None:
            self._wheel = Wheel(self.rim, self.tire)
        return self._wheel

In both examples, Gear still takes rim and tire as initialization arguments and 
creates its own new instance of Wheel, meaning it is still tightly coupled to Wheel; 
it can calculate gear inches for no other kind of object.

However, these coding styles reduce the number of dependencies within gear_inches 
while publicly exposing Gear's dependency on Wheel. They reveal dependencies instead 
of concealing them, lowering the barriers to reuse and making the code easier to 
refactor when circumstances allow. This change makes the code more agile and better 
able to adapt to an unknown future.

The way you manage dependencies on external class names profoundly affects your 
application. If you are mindful of dependencies and develop a habit of routinely 
injecting them, your classes will naturally be loosely coupled. If you ignore this 
issue and let class references proliferate, your application will resemble a big 
woven mat rather than a set of independent objects. An application whose classes 
are sprinkled with entangled and obscure class name references is unwieldy and 
inflexible, while one whose class name dependencies are concise, explicit, and 
isolated can easily adapt to new requirements.

Isolate Vulnerable External Messages
Calls to external functions in a class (i.e. not self) should also be isolated.

This means that changes to that external function or class will mean that your
function code does not have to change, only the isolated function would have to
change.

In the `gear_inches()` method below, `ratio` is sent to `self`, but
`diameter` is sent to `wheel`:
def gear_inches(self):
    return self.ratio * self.wheel.diameter()

This is fine in simple cases, but imagine that calculating `gear_inches`
required more complex math:  
def gear_inches(self):
    # ... a few lines of complex calculations
    foo = some_intermediate_result * self.wheel.diameter()
    # ... more calculations

`wheel.diameter()` is deeply embedded in a complex method, increasing its
vulnerability to changes in wheel. 

`gear_inches()` now depends on `Gear` responding to `self.wheel` and on `Wheel`
responding to `diameter()`.

To make `gear_inches()` more resilient, isolate the dependency in its own
method:

def gear_inches(self):
    # ... a few lines of complex calculations
    foo = some_intermediate_result * self.diameter()
    # ... more calculations

def diameter(self):
    return self.wheel.diameter()

At first glance, this might seem unnecessary—why create `diameter()` when
there's only one reference to `wheel.diameter()`? However, this technique
proactively removes an external dependency, making the code easier to modify in
the future.

Before refactoring:
`gear_inches()` knew that `wheel` had a `diameter()`.

This creates a direct dependency between `Gear` and `Wheel`. If `Wheel` ever
changes the method name or its signature, `gear_inches` will break.

By isolating `wheel.diameter()` in a separate method, `gear_inches` now relies
only on a message to `self`. If `Wheel` changes, the only adjustment needed is
within the `diameter()` method.

This technique is especially useful when:
- A method depends on an external message that is likely to change.
- A class contains multiple scattered references to an external method.  
- You want to reduce the unintended side effects when modifying dependencies.  

Not every external call requires this treatment, but identifying the most
vulnerable dependencies and wrapping them in methods can significantly improve
maintainability.  

Remove Argument-Order Dependencies
Having fixed order arguments to function calls are vulnerable to changes.

This can be especially bad during early development when one is constantly
changing what exactly arguments will be passed to a function.

One way around this is by using keyword arguments, especially for classes
that are likely to change in the future, for example, a Model() class
that may have many parameters that are subject to change.

class Gear:
    def __init__(self, **kwargs):
        self.chainring = kwargs.get('chainring')
        self.cog       = kwargs.get('cog')
        self.wheel     = kwargs['wheel']


using `kwargs.get('name')` will return None if the key does not exist,
which is essentially equivalent to: `__init__(self, name=None)`
in contrast using kwargs['name'] will return a KeyError if the variable
does not exist, This can actually be useful for compulsary arguments.

Explicitly Define Defaults
You may however want the lack of an argument to not simply default to None.
If this is the case, the dictionary `get()` function can just be given an 
extra argument that corresponds to the default value.

class Gear:
    def __init__(self, **kwargs):
        self.chainring = kwargs.get('chainring', 40)
        self.cog       = kwargs.get('cog', 18)
        self.wheel     = kwargs.get('wheel')

# Usage examples:
gear1 = Gear(chainring=52, cog=11, wheel="WheelObject")
gear2 = Gear(wheel="WheelObject")  # Defaults used: chainring=40, cog=18

If the default arguments are more complicated than simple values or strings,
we can ask a `defaults()` function to go and get these, then overwrite them
with whatever the user has inputted.

class Gear:
    def __init__(self, **kwargs):
        args = {**self.defaults(), **kwargs}
        self.chainring = kwargs.get('chainring')
        self.cog       = kwargs.get('cog')
        self.wheel     = kwargs.get('wheel')

    def default(self):
        args = {'chainring' : 40,
                'cog'       : self.default_cog(),
                'wheel'     : self.default_wheel(),
        return args

    def default_cog(self): ...
    def default_wheel(self): ... 

The line:
args = {**self.defaults(), **kwargs}
unpacks the defaults first into a dictionary, then the kwargs from the user,
since there can only be one unique key in a dinctionary, any existing ones are
overwriten.

Isolate Multiparameter Initialization

When using external libraries, you may not be able to change the order of the
arguments.

A solution involves wrapping of the external dependency:

# External dependency we don't control:
class ExternalGear:
    def __init__(self, chainring, cog, wheel):
        self.chainring = chainring
        self.cog = cog
        self.wheel = wheel

    def gear_inches(self):
        return (self.chainring / float(self.cog)) * self.wheel.diameter()

class Wheel:
    def __init__(self, rim, tire):
        self.rim = rim
        self.tire = tire

    def diameter(self):
        return self.rim + (self.tire * 2)

# Our wrapper function isolates the fixed-order initialization.
# It accepts keyword arguments, so callers aren't dependent on the order.
def gear_wrapper(**kwargs):
    # The external ExternalGear requires fixed-order parameters,
    # so we extract them by name and pass them in the correct order.
    return ExternalGear(kwargs['chainring'], kwargs['cog'], kwargs['wheel'])

# Usage example:
g = gear_wrapper(chainring=52, cog=11, wheel=Wheel(26, 1.5))
print(g.gear_inches())

This isolates the dependency on argument order so that the rest of your code
can use a more flexible, self-documenting interface without worrying about the
fixed parameter order required by `ExternalGear`.

Managing Dependency Direction
Dependencies have a direction.

In our earlier examples:
`Gear` --> `Wheel`
But there is no reason the reverse cannot be true.
 
You can reverse the dependency direction so that the external dependency is
injected rather than hardcoded.

For example, instead of having `Gear` directly call `wheel.diameter()`, you
pass the diameter value into `Gear.gear_inches()`.

This shifts the dependency so that `Wheel` now relies on `Gear` rather than the
other way around.

Why?

Encapsulation:
The complex dependency on an external object's method is isolated in a single
wrapper method.

Flexibility:
If the external object's interface changes (e.g., `Wheel` changes how it
computes diameter), you only need to update the wrapper method.

Maintenance:
It minimizes the ripple effect of changes, making the code easier to modify and
less fragile over time.

Choosing Dependency Direction:
Generally, it is better for classes depend on abstractions rather than concrete
implementations. If a class is likely to change, it should be lower in the
dependency hierarchy, and other classes should depend on more stable, abstract
interfaces.

class Gear:
    def __init__(self, chainring, cog):
        self.chainring = chainring
        self.cog = cog

    def gear_inches(self, diameter):
        # Uses the provided diameter instead of calling wheel.diameter() directly.
        return self.ratio() * diameter

    def ratio(self):
        return self.chainring / float(self.cog)


class Wheel:
    def __init__(self, rim, tire, chainring, cog):
        self.rim = rim
        self.tire = tire
        # Create a Gear instance using provided chainring and cog.
        self.gear = Gear(chainring, cog)

    def diameter(self):
        # Compute wheel diameter: rim + (tire * 2)
        return self.rim + (self.tire * 2)

    def gear_inches(self):
        # Pass the calculated diameter to Gear's gear_inches method.
        return self.gear.gear_inches(self.diameter())

wheel_instance = Wheel(26, 1.5, 52, 11)
print(wheel_instance.gear_inches())


This Python example demonstrates how to reverse the dependency:  

- `Gear.gear_inches()` now receives the diameter from `Wheel` instead of
directly calling a method on `Wheel`.  

- This isolates the dependency on `Wheel.diameter()` to a single place in
`Wheel`, reducing the risk of widespread changes if `Wheel`'s implementation
changes.

Summary:
Dependency management is core to creating future-proof applications. Injecting
dependencies creates loosely coupled objects that can be reused in novel ways.
Isolating dependencies allows objects to quickly adapt to unexpected changes.
Depending on abstractions decreases the likelihood of facing these changes. The
key to managing dependencies is to control their direction. The road to
maintenance nirvana is paved with classes that depend on things that change
less often than they do

4. Creating Flexible Interfaces
An object oriented application may be made up of classes, but
it is defined by the messages.

Designed must be concerned with these messages, responsibilities
and dependencies.

Conversation between objects takes places using their `interfaces'

Creating flexible interfaces is important for applications to grow
and change.

Understanding Interfaces
Although in python there is no explicit public and private keywords
to define what can and cannot be accessed outside a class.
Properly thinking about what is revealed to other objects and what
isn't is of key importance.

the public interface comprimises of the exposed methods of a class.

Defining Interfaces

Imagine the following:

Resteraunt()
    Kitchen()
    Menu()     <-- Public interface for the Kitchen and menu
    Customer()

The Kitchen will have many internal processes relating how to make
a certain dish but these should all be private to the Kithcen().

Public Interface:
  - Reveal its primary responsibility
  - Are expected to be invoked by others
  - Will not change on a whim
  - Are safe for others to depend on
  - Are thoroughly documented in the tests

Private Interface:
    - Handle implementation details
    - Are not expected to be sent by other objects
    - Can change for any reason whatsoever
    - Are unsafe for others to depend on
    - May not even be referenced in the tests

Responsibilities, Dependencies, and Interfaces
Finding the Public Interface
An Example Application: Bicycle Touring Company
Constructing an Intention
Using Sequence Diagrams
Asking for “What” Instead of Telling “How”
Seeking Context Independence
Trusting Other Objects
Using Messages to Discover Objects
Creating a Message-Based Application
Writing Code That Puts Its Best (Inter)Face Forward
Create Explicit Interfaces
Honor the Public Interfaces of Others
Exercise Caution When Depending on Private Interfaces
Minimize Context
The Law of Demeter
Defining Demeter
Consequences of Violations
Avoiding Violations
Listening to Demeter
Summary




5. Reducing Costs with Duck Typing

Duck Types are public interfaced that are not tied to any specific class.

if an object quacks like a duck and walks like a duck, then its class is
immaterial, it’s a duck

Understanding Duck Typing

An object's type is less about its class and more about the behavior it
exhibits through its methods and properties. This means that if an object
implements the necessary methods, it can be used interchangeably with others,
regardless of its actual class. This is known as known as duck typing.

Focusing on an object’s behavior (its public interface) rather than its class
allows for flexible and adaptable designs. It’s important to document these
interfaces so that users of your code understand what methods an object is
expected to have.

Benefits: Increased flexibility, easier code reuse, and more dynamic
interactions between objects.

Cautions: Without explicit contracts (as provided by interfaces in statically
typed languages), designs can become chaotic if the expected behaviors aren’t
clearly defined and adhered to.

Overlooking the Duck
In the following example: Trip.prepare() sends the message .prepare_bicycles()
to the object contained in self.mechanic No reference is made to the Mechanic
class.
class Trip:
    def __init__(self, bicycles, customers, vehicle):
        self.bicycles = bicycles
        self.customers = customers
        self.vehicle = vehicle

    def prepare(self, mechanic):
        mechanic.prepare_bicycles(self.bicycles)

class Mechanic:
    def prepare_bicycles(self, bicycles):
        for bicycle in bicycles:
            self.prepare_bicycle(bicycle)

    def prepare_bicycle(self, bicycle):
        # Implementation for preparing a single bicycle.
        print(f"Preparing {bicycle}")


# Example usage:
trip = Trip(bicycles=["Bike1", "Bike2"], customers=[], vehicle=None)
mechanic = Mechanic()
trip.prepare(mechanic)

Using this code as it shown in the example requires that some external object
sends .prepare() to Trip along with a mechanic argument.

Even though the prepare() method has no explicit dependency on the Mechanic
class, it does depend on receiving an object that can respond to
prepare_bicycles(). This dependency is so fundamental that it’s easy to miss or
to discount, but nonetheless, it exists. Trip’s prepare method firmly believes
that its argument contains a preparer of bicycles.

Compounding the Problem
Imagine that requirements change. In addition to a mechanic, trip preparation
now involves a trip coordinator and a driver.

You Create TripCoordinator() and Driver().

You also change Trip.prepare() to invoke the correct behavior from each of its
arguments.
class Trip:
    def __init__(self, bicycles, customers, vehicle):
        self.bicycles = bicycles
        self.customers = customers
        self.vehicle = vehicle

    def prepare(self, preparers):
        for preparer in preparers:
            if isinstance(preparer, Mechanic):
                preparer.prepare_bicycles(self.bicycles)
            elif isinstance(preparer, TripCoordinator):
                preparer.buy_food(self.customers)
            elif isinstance(preparer, Driver):
                preparer.gas_up(self.vehicle)
                preparer.fill_water_tank(self.vehicle)

class Mechanic:
    def prepare_bicycles(self, bicycles):
        # Implementation for preparing bicycles.
        print("Mechanic: Preparing bicycles.")

class TripCoordinator:
    def buy_food(self, customers):
        # Implementation for buying food.
        print("TripCoordinator: Buying food for customers.")

class Driver:
    def gas_up(self, vehicle):
        # Implementation for gassing up.
        print("Driver: Gassing up vehicle.")

    def fill_water_tank(self, vehicle):
        # Implementation for filling water tank.
        print("Driver: Filling water tank.")

# Example usage:
bicycles = ["Bike1", "Bike2"]
customers = ["Alice", "Bob"]
vehicle = "Van"
trip = Trip(bicycles, customers, vehicle)
preparers = [Mechanic(), TripCoordinator(), Driver()]
trip.prepare(preparers)

Trip.prepare() now refers to three different classes by name and knows specific
methods implemented in each. Risks have dramatically gone up. Trip’s prepare
method might be forced to change because of a change elsewhere and it might
unexpectedly break as the result of a distant, unrelated change.

This code is the first step in a process that will paint you into a corner with
no way out.

Blinded by existing classes and neglecting overlooked messages results in this
dependent-laden code that is a natural outgrowth of a class-based perspective.

Initially, prepare() required a mechanic that knew how to prepare_bicycle().
After a change, prepare() now received arguments of other classes that do not
know how to prepare_bicycle(). As a result, you now go hunting for messages in
the new classes (TripCoordinator() and Drive()) for the behavior we want
buy_food() gas_up() and fill_water_tank()

The most obvious way to invoke this behavior is to send these very messages,
but now you’re stuck. Every one of your arguments is of a different class and
implements different methods; you must determine each argument’s class to know
which message to send. Adding a case statement that switches on class solves
the problem of sending the correct message to the correct object but causes an
explosion of dependencies.

Count the number of new dependencies in the prepare method.
- It relies on specific classes, no others will do.
- It relies on the explicit names of those classes.
- It knows the names of the messages that each class understands
- It knows the arguments that those messages require.

many distant changes will now have side effects on this code. To make matters
worse, this style of code propagates itself. When another new trip preparer
appears, you, or the next person down the programming line, will add a new when
branch to the case statement. Your application will accrue more and more
methods like this, where the method knows many class names and sends a specific
message based on class. The logical endpoint of this programming style is a
stiff and inflexible application, where it eventually becomes easier to rewrite
everything than to change anything.

Finding the Duck
Removing the dependencies requires the recognicion that Trip.prepare() serves a
single purpose.

The arguments passed prepare() wish to collaborate to accomplish a single goal.
Every argument is here for the same reason and that reason is unrelated to the
argument’s underlying class. Avoid getting sidetracked by your knowledge of
what each argument’s class already does

Think instead about what prepare() needs. Considered from prepare’s point of
view, the problem is straightforward. The prepare method wants to prepare the
trip. Its arguments arrive ready to collaborate in trip preparation. The design
would be simpler if prepare just trusted them to do so. Therefore, prepare
needs a Preparer(). You’ve pried yourself loose from existing classes and
invented a duck type. The next step is to ask what message the prepare method
can fruitfully send each Preparer. From this point of view, the answer is
obvious: prepare_trip.

Preparer() a this point is an abstraction, objects that implement
prepare_trip() are Preparers.
class Trip:
    def __init__(self, bicycles=None, customers=None, vehicle=None):
        self.bicycles = bicycles or []
        self.customers = customers or []
        self.vehicle = vehicle

    def prepare(self, preparers):
        for preparer in preparers:
            preparer.prepare_trip(self)


class Mechanic:
    def prepare_trip(self, trip):
        for bicycle in trip.bicycles:
            self.prepare_bicycle(bicycle)

    def prepare_bicycle(self, bicycle):
        print(f"Preparing bicycle {bicycle}")


class TripCoordinator:
    def prepare_trip(self, trip):
        self.buy_food(trip.customers)

    def buy_food(self, customers):
        print(f"Buying food for {len(customers)} customers")


class Driver:
    def prepare_trip(self, trip):
        vehicle = trip.vehicle
        self.gas_up(vehicle)
        self.fill_water_tank(vehicle)

    def gas_up(self, vehicle):
        print(f"Gassing up vehicle {vehicle}")

    def fill_water_tank(self, vehicle):
        print(f"Filling water tank for vehicle {vehicle}")


There is a temptation here to create a Prepare() class or interface (abstract
base class) and then have Driver() TripCoordinator() and mechnic all inherit
from it ensuring that the prepare_trip() method is implemented. But when you
step back, you realize this isn't needed. If prepare() gets an object that
doesn't implement prepare_trip, you will get an error that will tell you what
you need to know (that object does not have .prepapre_trip()).

Consequences of Duck Typing
Duck typing shifts your code from relying on concrete classes to depending on
behavior, which makes it easier to extend without modifying existing code.
Although concrete code is simpler to understand, it’s costly to change;
abstract, duck-typed code requires a deeper initial understanding but is far
more adaptable. This design approach embraces polymorphism—the idea that many
different objects can respond to the same message—allowing them to be used
interchangeably as long as they behave correctly. Ultimately, by focusing on
behavior rather than class, you gain flexibility, but you must ensure that all
objects reliably implement the expected methods.


Writing Code That Relies on Ducks
Recognizing Hidden Ducks
1. Case statements that switch on class
class Trip:
    def __init__(self, bicycles, customers, vehicle):
        self.bicycles = bicycles
        self.customers = customers
        self.vehicle = vehicle

    def prepare(self, preparers):
        for preparer in preparers:
            if isinstance(preparer, Mechanic):
                preparer.prepare_bicycles(self.bicycles)
            elif isinstance(preparer, TripCoordinator):
                preparer.buy_food(self.customers)
            elif isinstance(preparer, Driver):
                preparer.gas_up(self.vehicle)
                preparer.fill_water_tank(self.vehicle)

2. kind_of? and is_a?
if isinstance(preparer, Mechanic):
    preparer.prepare_bicycles(bicycle)
elif isinstance(preparer, TripCoordinator):
    preparer.buy_food(customers)
elif isinstance(preparer, Driver):
    preparer.gas_up(vehicle)
    preparer.fill_water_tank(vehicle)

3. responds_to?
if hasattr(preparer, 'prepare_bicycles'):
    preparer.prepare_bicycles(bicycle)
elif hasattr(preparer, 'buy_food'):
    preparer.buy_food(customers)
elif hasattr(preparer, 'gas_up'):
    preparer.gas_up(vehicle)
    preparer.fill_water_tank(vehicle)

Placing Trust in Your Ducks

Use of kind_of?, is_a?, responds_to?, and case statements that switch on your
classes indicate the presence of an unidentified duck.

In each case the code is effectively saying “I know who you are and because of
that I know what you do.”

This knowledge exposes a lack of trust in collaborating objects and acts as a
millstone around your object’s neck.

It introduces dependencies that make code difficult to change.

Just as in Demeter violations, this style of code is an indication that you are
missing an object, one whose public interface you have not yet discovered.

The fact that the missing object is a duck type instead of a concrete class
matters not at all; it’s the interface that matters, not the class of the
object that implements it.

Flexible applications are built on objects that operate on trust; it is your
job to make your objects trustworthy.

When you see these code patterns, concentrate on the offending code’s
expectations and use those expectations to find the duck type.

Once you have a duck type in mind, define its interface, implement that
interface where necessary, and then trust those implementers to behave
correctly


Documenting Duck Types
Because the Prepare() duck type is an abstraction, it doesn't appear
anywhere in the code, there is no class Prepare() anywhere.

This can make it difficult to see that it exists, therefore good documentation
in the form of tests should be used, more in Chapter 9.

Sharing Code Between Ducks
in our example the only thing Mechanic, Driver and TripCoordinator have in
common is prepare_trip() however, if there is more share code it becomes more
involved, more in Chapter 7.

Summary
Messages are at the center of object-oriented applications and they pass among
objects along public interfaces.

Duck typing detaches these public interfaces from specific classes, creating
virtual types that are defined by what they do instead of by who they are.

Duck typing reveals underlying abstractions that might otherwise be invisible.
Depending on these abstractions reduces risk and increases flexibility, making
your application cheaper to maintain and easier to change.

6. Acquiring Behavior Through Inheritance
Understanding Classical Inheritance
Inheritance is a mechanism for automatic message delegation.
It does this by creating a forwarding path for messages that are
not understood by a subclass to a superclass.

Classical inheritance just refers to inheritance through superclass and
subclasses. As opposed to other mechnisms such as prototypical inheritance in
javascript.

Recognizing Where to Use Inheritance
Scenario:
A company called FastFeet offers road bike trips, these bikes are maintained by
mechanics who take an asortment of spare parts on every trip.
Starting with a Concrete Class
class Bicycle:
    def __init__(self, size, tape_color):
        self.size = size
        self.tape_color = tape_color

    def spares(self):
        s = {'chain'     : '10-speed',
             'tire_size' : '23',
             'tape_color': self.tape_color}
        return s

bike = Bicycle(size='M', 'tape_color'='red')
print(bike.size)      # -> 'M'
print(bike.spares())  # -> {'chain': '10-speed', 'tire_size': '23', 'tape_color': 'red'}


Bicycle instances can respond to the spares, size, and tape_color messages and
a Mechanic can figure out what spare parts to take by asking each Bicycle for
its spares.

Imagine now that FastFeet begins to lead mountain bike trips.

Mountain bikes and road bikes are much alike but there are clear differences
between them. Mountain bikes are meant to be ridden on dirt paths instead of
paved roads. They have sturdy frames, fat tires, straight-bar handlebars (with
rubber hand grips instead of tape), and suspension. The bicycle in Figure 6.2
has front suspension only, but some mountain bikes also have rear, or “full”
suspension.

Your design task is to add support for mountain bikes to FastFeet’s
application. Much of the behavior that you need already exists; mountain bikes
are definitely bicycles. They have an overall bike size and a chain and tire
size. The only differences between road and mountain bikes are that road bikes
need handlebar tape and mountain bikes have suspension.

Embedding Multiple Types
When a preexisting concrete class contains most of the behavior you need, it’s
tempting to solve this problem by adding code to that class. 

class Bicycle:
    def __init__(self, **kwargs):
        self.style       = kwargs['style']
        self.size        = kwargs['size']
        self.tape_color  = kwargs['tape_color']
        self.front_shock = kwargs['front_shock']
        self.rear_shock  = kwargs['rear_shock']

    # This starts down a slippery slope.
    def spares(self):
        if self.style == 'road'
            s = {'chain'     : '10-speed',
                 'tire_size' : '23',
                 'tape_color': self.tape_color}
        else:
            s = {'chain'     : '10-speed',
                 'tire_size' : '2.1',
                 'tape_color': self.rear_shock}

        return s

bike1 = Bicycle(style='road',
                size='M',
                tape_color='red',
                front_shock=None,
                rear_shock=None)

bike2 = Bicycle(style='mountain',
                size='S',
                tape_color'='red',
                front_shock='Manitou',
                rear_shock='Fox')

The new front_shock and rear_shock variables hold mountain bike specific parts.
The new style variable determines which parts appear on the spares list.

This example illustrates an antipattern in object-oriented design. The
`Bicycle` class embeds multiple types by using a `style` attribute to determine
behavior in the `spares` method. This approach introduces several problems:

- If you add a new style you must change the if statement.

- If you write careless code where the last option is the default (as does the
  code above) an unexpected style will do something but perhaps not what you
  expect.

- The spares method started out containing embedded default strings, some of
  these strings are now duplicated on each side of the if statement.

- Bicycle has an implied public interface that includes spares, size, and all
  the individual parts.

- The size method still works, spares generally works, but the parts methods
  are now unreliable.

- It’s impossible to predict, for any specific instance of Bicycle, whether a
  specific part has been initialized.

- Objects holding onto an instance of Bicycle may, for example, be tempted to
  check style before sending it tape_color or rear_shock.

The code wasn’t great to begin with; this change did nothing to improve it. The
initial Bicycle class was imperfect but its imperfections were hidden,
encapsulated within the class.

These new flaws have broader consequences. Bicycle now has more than one
responsibility, contains things that might change for different reasons, and
cannot be reused as is. 

checking an attribute like `style' to determine behavior is the same as checking
an object's class.

In the first approach, we ask:
    "What is your style?" → Then behave accordingly.
In the second approach, Python asks:
    "What class are you?" → And behaves accordingly.

Finding the Embedded Types
The if statement in the spares method above switches on a variable named style,
but it would have been just as natural to call that variable type or category.
Variables with these kinds of names are your cue to notice the underlying
pattern. 

Type and category are words perilously similar...

The style variable effectively divides instances of Bicycle into two different
kinds of things. These two things share a great deal of behavior but differ
along the style dimension. 

Some of Bicycle’s behavior applies to all bicycles, some only to road bikes,
and some only to mountain bikes. This single class contains several different,
but related, types. This is the exact problem that inheritance solves; that of
highly related types that share common behavior but differ along some
dimension.
Choosing Inheritance
Objects receive messages.

The receiving object ultimately handles any message in one of two ways:
    1. It either responds directly
    2. or it passes the message on to some other object for a response.

Inheritance provides a way to define two objects as having a relationship
such that when the first receives a message that it does not understand, it
automatically forwards, or delegates, the message to the second. 

Misapplying Inheritance
In this example, we illustrate a problematic use of inheritance.

The Bicycle class was originally designed with road bike behavior in mind.
When MountainBike is subclassed from Bicycle, it inherits both the general
bicycle behavior and road-specific defaults, leading to mixed-up, inconsistent
behavior. For example, a MountainBike may report a tire size of "23" and have
a tape_color (meant for road bikes), even though these attributes don’t apply.

The problematic design forces us to modify the Bicycle class (a concrete class)
when creating a subclass that needs different behavior, which violates the 
Open-Closed Principle and makes the design rigid and error-prone.
class Bicycle:
    def __init__(self, size, tape_color=None, tire_size="23", chain="10-speed"):
        self.size = size
        self.tape_color = tape_color
        self.tire_size = tire_size
        self.chain = chain

    def spares(self):
        return {
            "tire_size": self.tire_size,
            "chain": self.chain,
            "tape_color": self.tape_color
        }

class MountainBike(Bicycle):
    def __init__(self, size, front_shock, rear_shock, **kwargs):
        self.front_shock = front_shock
        self.rear_shock = rear_shock
        super().__init__(size, **kwargs)

    def spares(self):
        base_spares = super().spares()
        base_spares.update({"rear_shock": self.rear_shock})
        return base_spares

# Example usage:
mountain_bike = MountainBike(
    size='S',
    front_shock='Manitou',
    rear_shock='Fox',
    tape_color=None
)

print(mountain_bike.size) # Expected: 'S'
print(mountain_bike.spares())
# {'tire_size': '23', 'chain': '10-speed', 'tape_color': None, 'rear_shock': 'Fox'}

This design shows how MountainBike, as a subclass of Bicycle, ends up with
behavior that mixes road bike defaults (like tire_size and tape_color) with
mountain bike parts (front_shock and rear_shock). Embedding these defaults in
Bicycle forces MountainBike to inherit unwanted behavior, which is a common
antipattern when a concrete class is used as a superclass. A better design
would separate the general bicycle behavior from the specifics of each bike
type, possibly through duck typing or by refactoring Bicycle into more
abstract components.

Finding the Abstraction
Initially Bicycle() was designed for road bikes. However, once MountainBike is
introduced, the name Bicycle becomes misleading, since it implies a general
type while actually representing only road bikes.

Inheritance works best when a subclass (like MountainBike) is a true
specialization of its superclass (a generic Bicycle). A MountainBike should
have all the features of a Bicycle, plus extra features. For inheritance to be
effective, your classes must reflect a true generalization–specialization
relationship and be implemented correctly.

Since the current Bicycle class mixes general bicycle behavior with
road-specific code, it’s better to separate them. Move the road bike–specific
code into a RoadBike subclass, leaving Bicycle as a true, generic abstraction
for all bicycles.

Creating an Abstract Superclass
What we want to do is create an abstract class Bicycle() that will contain the
common behavior.

Abstract classes are not meant to be instanced themselves, in Python, the abc
module allows you to explicitly defined abstract classes, however this is not
strictly needed, in many cases the programmer should be able to use their brain
to figure out what is abstract or not.

It almost never makes sense to create an abstract superclass with only one sub-
class. Even though its possible you anticipate having other kinds of bikes and
it is possible to imagine modeling it as two classes from the very beginning,
do not. Regardless of how strongly you anticipate having other kinds of bikes,
that day may never come. 

Even two bikes, it still may not be right to commit to inheritance, creating a
hierarchy has costs, and the best way to minimize this cost is to ensure you
have the abstract right. One is more likely to get the abstraction right once
once more behaviour is implemented as you can see what is shared between the
objects.

The following steps show a possible approach when refactoring: 
# Create the abstract class
class Bicycle:
    pass

# Rename the old Bicycle() to RoadBike() and inherit from Bicycle
class RoadBike(Bicycle):
    # unchanged

# Create the MountainBike which subclass of Bicycle
class MountainBike(Bicycle):
    # empty 

Promoting Abstract Behavior
.size and spares() are common to both bikes we can promote them to the
super-class. .size is simpler, so we do that first:
class Bicycle:
    def __init__(self, **kwargs):
        self.size = kwargs['size']

class RoadBike(Bicycle):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.tape_color = kwargs['tape_color']

class MountainBike(Bicycle):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.front_shock = kwargs['front_shock']
        self.rear_shock  = kwargs['rear_shock']

b1 = RoadBike(size='M', tape_color='red')
b2 = MountainBike(size='L', front_shock='Manitou', rear_shock='Fox')
print(b1.size, b2.size) # M L

An approach when refactoring classes is to first push everything down into the
concrete classes, i.e. atrributes and functions. Then only after proceed to
promote up the shared abstractions between the classes.

The reason for this is to try and avoid leaving remnants of concrete parts of
the code in the super class.

A more general way of looking at this is to ask the question of:
"What will happen if I'm wrong?"

In the case of failing to correctly identify and promote the abstraction, and
as a result, some of it is left behind in the subclass, then the problem will
be realized when another subclass requires that behaviour. You'll either have
to duplicate the code or promote that behaviour.

In the case of not pushing down the concrete behaviour, and leaving them in the
super-class, it now means that all the sub-classes will inherit it. this is a
problem as the subclasses now do not truely specializations of their
superclasses and the hierarchy becomes untrustworthy. The result is that new
code will embed knowlege of these quirks, such as checking classes of objects,
the consequences of not having concrete behaviour in the superclass are far
more severe.

Separating Abstract from Concrete
We now return to the .spares() function, which in the example in the book
ended up as a weird missmatch between the two classes.
In a nutshell,spares should give back:
    RoadBike:     chain, tire_size, tape_color
    MountainBike: chain, tire_size, front_shock, rear_shock

The rest of this chapter is quite confusing, so for now i'll just implement the
most straightforward solution I can think of...


class Bicycle:
    def __init__(self, size, chain=None, tire_size=None, **kwargs):
        self.size      = size
        self.chain     = chain
        self.tire_size = tire_size

    def spares(self):
        return {'chain'     : self.chain,
                'tire_size' : self.size}

class RoadBike(Bicycle):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.tape_color = kwargs['tape_color']

    def spares(self):
        s = super().spares()
        s['tape_color'] = self.tape_color
        return s

class MountainBike(Bicycle):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.front_shock = kwargs['front_shock']
        self.rear_shock  = kwargs['rear_shock']

    def spares(self):
        s = super().spares()
        s['front_shock'] = self.front_shock
        s['rear_shock']  = self.rear_shock
        return s

b1 = RoadBike(size='M', tape_color='red')
b2 = MountainBike(size='L', front_shock='Manitou', rear_shock='Fox')
print(b1.spares())
print(b2.spares())


Using the Template Method Pattern
The template method pattern is used to define a common initialization structure
in a superclass (Bicycle) while allowing subclasses (RoadBike and MountainBike)
to customize parts of the behavior.

The Bicycle class sets up defaults for attributes, and if a value isn’t
provided, it calls a template method to obtain the default. Subclasses can
override these template methods to supply their own default values.
class Bicycle:
    def __init__(self, size, chain=None, tire_size=None):
        self.size      = size
        self.chain     = chain or self.default_chain()
        self.tire_size = tire_size or self.default_tire_size()

    def default_chain(self):
        return "10-speed"

    def default_tire_size(self):
        """Template method to be overwritten by subclass."""
        raise NotImplementedError("Subclasses must implement default_tire_size()")


class RoadBike(Bicycle):
    def __init__(self, size, tape_color, chain=None, tire_size=None):
        super().__init__(size, chain, tire_size)
        self.tape_color = tape_color

    def default_tire_size(self):
        return "23"


class MountainBike(Bicycle):
    def __init__(self, size, front_shock, rear_shock, chain=None, tire_size=None):
        super().__init__(size, chain, tire_size)
        self.front_shock = front_shock
        self.rear_shock = rear_shock

    def default_tire_size(self):
        return "2.1"

road_bike = RoadBike(size="M", tape_color="red")
print("RoadBike tire size:", road_bike.tire_size)  # Output: '23'
print("RoadBike chain:", road_bike.chain)          # Output: '10-speed'

mountain_bike = MountainBike(size="S", front_shock="Manitou", rear_shock="Fox")
print("MountainBike tire size:", mountain_bike.tire_size)  # Output: '2.1'
print("MountainBike chain:", mountain_bike.chain)          # Output: '10-speed'

default_chain() is a common default for both bikes.
default_tire_size() is a template method, overwritten by the implementation in
the subclass.

NOTE: using the or syntax as is done above is less explicit than using:
tire_size if tire_size is not None else self.default_tire_size()
using the or syntax will treat empty strings, lists and 0s as null entries.
This can be useful, the syntax is clearer but it is imporatnt to be aware of
this. If the default tire size can be 0 for example, then don't use the or.

Another way of defining the defaults is as follows:
class Bicycle:
    def __init__(self, **kwargs):
        self._size = kwargs.get('size')
        # Use provided chain or get default; use provided tire_size or get default
        self._chain = kwargs.get('chain', self.default_chain)
        self._tire_size = kwargs.get('tire_size', self.default_tire_size)


Implementing Every Template Method
In the previous example, when using the template method pattern, the superclass
Bicycle() sends messages to get default values that subclasses must override. 

If a subclass forgets to implement default_tire_size, Python wont complain,
but it will cause an error later on. 

Bicycle() imposes a requirement on its subclasses that isn’t clear by just
reading the code. The original designer knew that every subclass needed to
define default_tire_size, but new programmers might overlook this requirement.

The abstract base class (abc) module in python lets you explicitly   
define template functions that will scream at you if you don't implement them.
from abc import ABC, abstractmethod

class Bicycle(ABC):
    # Same as before    
    @abstractmethod
    def default_tire_size(self):
        pass

class RecumbentBike(Bicycle):
    def default_chain(self):
        return "9-speed"

bike = RecumbentBike(size="S")
# TypeError: Can't instantiate abstract class RecumbentBike without
# an implementation for abstract method 'default_tire_size'


Managing Coupling Between Superclasses and Subclasses

The final piece of the puzzle is the implementation of .spares() There are a
few ways to do this, some resulting in more tightly coupled classes than
others. What follows are two different implementations:
Understanding Coupling
When using inheritance, one must be careful about how much each class knows
about the other. Simple solutions may lead to tightly coupled classes which may
cause problems later.

from abc import ABC, abstractmethod

class Bicycle(ABC):
    def __init__(self, **kwargs):
        self.size      = kwargs.get('size')
        self.chain     = kwargs.get('chain', self.default_chain())
        self.tire_size = kwargs.get('tire_size', self.default_tire_size())

    def default_chain(self):
        return '10-speed'

    @abstractmethod
    def default_tire_size(self):
        pass

    def spares(self):
        return {
            'tire_size': self.tire_size,
            'chain': self.chain
        }

class RoadBike(Bicycle):
    def __init__(self, **kwargs):
        self.tape_color = kwargs.get('tape_color')
        super().__init__(**kwargs)

    def spares(self):
        s = super().spares()
        s['tape_color'] = self.tape_color
        return s 

    def default_tire_size(self):
        return '23'

class MountainBike(Bicycle):
    def __init__(self, **kwargs):
        self.front_shock = kwargs.get('front_shock')
        self.rear_shock  = kwargs.get('rear_shock')
        super().__init__(**kwargs) 

    def spares(self):
        s = super().spares()
        s['front_shock'] = self.front_shock
        s['rear_shock']  = self.rear_shock
        return s 

    def default_tire_size(self):
        return '2.1'

rb = RoadBike(size='XL', tire_size=29, tape_color='red')
mb = MountainBike(size='L', chain='test', tire_size=24,
                  front_shock='bob', rear_shock='smith')
print(rb.spares())
print(mb.spares())
#{'tire_size': 29, 'chain': '10-speed', 'tape_color': 'red'}
#{'tire_size': 24, 'chain': 'test', 'front_shock': 'bob', 'rear_shock': 'smith'}


Everything works as expected, but the fact that the sub-classes in the above
example have to call super() in both the __init__() and also the spares() means
that a form of coupling has been created.

Any new programmer implementing a subclass of bicycle must remember to add this
to the functions or else things will not work as expected.
Decoupling Subclasses Using Hook Messages
There is a way to avoid having the subclasses needing to send super()
to the parent class.

This can be done via the use of a hook:

from abc import ABC, abstractmethod

class Bicycle(ABC):
    def __init__(self, **kwargs):
        self.size      = kwargs.get('size')
        self.chain     = kwargs.get('chain', self.default_chain())
        self.tire_size = kwargs.get('tire_size', self.default_tire_size())
        self.post_init(**kwargs)

    def post_init(self, **kwargs):
        pass # To be overwritten by subclass

    def default_chain(self):
        return '10-speed'

    @abstractmethod
    def default_tire_size(self):
        pass

    def spares(self):
        return {'tire_size': self.tire_size,
                'chain'    : self.chain,
                **self.local_spares}

class RoadBike(Bicycle):
    def post_init(self, **kwargs):
        self.tape_color = kwargs.get('tape_color')

    @property
    def local_spares(self):
        return {'tape_color': self.tape_color}

    def default_tire_size(self):
        return '23'

class MountainBike(Bicycle):
    def post_init(self, **kwargs):
        self.front_shock = kwargs.get('front_shock')
        self.rear_shock  = kwargs.get('rear_shock')
    
    @property
    def local_spares(self):
        return {'front_shock': self.front_shock,
                'rear_shock' : self.rear_shock}

    def default_tire_size(self):
        return '2.1'

rb = RoadBike(size='XL', tire_size=29, tape_color='red')
mb = MountainBike(size='L', chain='test', tire_size=24,
                  front_shock='bob', rear_shock='smith')
print(rb.spares())
print(mb.spares())


Adding post_init() to the parent __init__()
means that it is always called on constructing a bike.

Implementing this function in subclasses means that it is called
in the parent class, this means we do not need an __init__ in the subclasses.

A similar thing is done for spares() where we just add the local_spares to
the dictionary in the parent class and return it.

Summary
The best way to create an abstract superclass is by pushing code up from
concrete subclasses.

Identifying the correct abstraction is easiest if you have access to at least
three existing concrete classes. 

Abstract superclasses use the template method pattern to invite inheritors to supply
specializations, and use hook methods to allow these inheritors to contribute
these specializations without being forced to send super. 

Hook methods allow subclasses to contribute specializations without knowing the
abstract algorithm. 

They remove the need for subclasses to send super and therefore reduce the
coupling between layers of the hierarchy and increase its tolerance for change.

Well-designed inheritance hierarchies are easy to extend with new subclasses,
even for programmers who know very little about the application. 

This ease of extension is inheritance’s greatest strength. When your problem is
one of needing numerous specializations of a stable, common abstraction,
inheritance can be an extremely low-cost solution.

7. Sharing Role Behavior with Modules
Imagine there is a need for a recumbent mountain bikes. 

Creation of a recumbent mountain bike subclass requires combining the qualities
of two existing subclasses, something that inheritance cannot readily
accommodate. 

Understanding Roles
Some problems require sharing behavior among unrelated objects.

These objects can be thought of sharing a role.

Using a role creates dependencies among the objects involved and
these dependencies introduce risks that you must take into account when
deciding among design options.

This section unearths a hidden role and creates code to share its behavior
among all players, while at the same time minimizing the dependencies thereby
incurred.

Finding Roles
In chapter 5, we used a "preparer" as duck type.

Mechanic().prepare_trip()
Driver().prepare_trip()
TripCoordinator().prepare_trip()

# are all interchangable for
perparer.prepare_trip()

The existence of a Preparer role suggests that there is also a
Preparable role.






Organizing Responsibilities
Removing Unnecessary Dependencies
Writing the Concrete Code
Extracting the Abstraction
Looking Up Methods
Inheriting Role Behavior
Writing Inheritable Code
Recognize the Antipatterns
Insist on the Abstraction
Honor the Contract