Structural edits

Author: taggedzi

docs/structural_adapter.md

@@ -1,62 +1,77 @@
 # The Adapter Pattern (Structural)
 
-## Intent
+## Purpose
 
-The Adapter pattern is a design pattern that allows the interface of an existing class to be used as another interface without modifying the original class. It's often used when you want to use an existing class, but its interface isn't what you need. The Adapter makes the incompatible classes work together by wrapping its own methods and properties into a new format that is compatible with the client’s code.
+The Adapter pattern allows objects with incompatible interfaces to work together. It acts as a bridge between a class you already have and the interface you need. Instead of changing existing code, you create an adapter that translates one interface into another.
 
-## Problem It Solves
+## The Problem It Solves
 
-The problem this pattern addresses is when we have a class with an incompatible interface, but we want to use it as if it had a different interface. This can be due to various reasons like legacy systems, third-party libraries or simply because you're trying to follow the Single Responsibility Principle (SRP).
+Sometimes you want to use a class, but its methods don't match what your code expects. This often happens when working with legacy code, third-party libraries, or when following the Single Responsibility Principle (SRP) and keeping classes focused. Rather than modifying the original class (which might be risky or impossible), the Adapter pattern lets you create a wrapper that makes it compatible with your code.
 
 ## When to Use It
 
-This pattern is best used when:
+Use the Adapter pattern when:
 
-1. You want to use an existing class but its interface isn’t what you need.
-2. You have a working class, but it lacks some of the functionality that you require.
-3. The classes are incompatible and cannot work together as they do not share the same interface.
-4. You're trying to follow the Single Responsibility Principle (SRP).
+* You want to use an existing class, but its interface doesn’t match what you need.
+* You’re integrating with legacy code or third-party libraries.
+* You want to follow SRP by not changing the original class.
+* Classes with different interfaces need to work together.
 
 ## When NOT to Use It
 
-This pattern should be avoided when:
+Avoid the Adapter pattern if:
 
-1. If you have control over the original class, it would be better to modify that class directly.
-2. The classes are highly compatible and there's no need for an adapter.
-3. You're working with a legacy system where modifying the code is not feasible or desirable.
-4. When the Adapter introduces complexity into your design.
+* You control the original class and can safely change its interface.
+* The classes already work together without modification.
+* Adding an adapter would unnecessarily complicate your design.
 
 ## How It Works
 
-The Adapter wraps the original class in an interface that clients expect, and it translates between the client’s expectations and the original class's interface. This translation is done by implementing a set of methods that make sense for the client to use.
+The Adapter pattern works by wrapping the incompatible class in a new class that implements the desired interface. This wrapper (the adapter) translates method calls or data between the expected interface and the actual one.
 
 ## Real-World Analogy
 
-Imagine you have a foreign book which has words in your language but written in another language. The Adapter pattern provides an interface where this foreign book can be read, even though it's not understandable yet. It acts as a translator between the original (foreign) and desired (native) languages.
+Imagine you have a power plug from Europe, but you're in the U.S. The plug won't fit the outlet directly. An adapter converts the shape of the plug so you can use your device without modifying it. The same idea applies in software—adapters help mismatched parts work together without changing their internal workings.
 
 ## Simplified Example
 
-Here is a simplified example of how the Adapter pattern works:
+Here's a simple Python example:
 
 ```python
-class Target:  # The domain-specific interface that clients expect
+# The interface expected by the client
+class Target:
     def request(self):
         return "Target: The default behavior."
 
-class Adaptee:  # A class with an incompatible interface
+# An existing class with a different interface
+class Adaptee:
     def specific_request(self):
-        return ".eetpadA eht fo roivaheb laicepS"   # reversed string
+        return ".eetpadA eht fo roivaheb laicepS"  # reversed string
 
-class Adapter(Target):  # Adapts the Adaptee to the Target interface
+# Adapter converts the interface of Adaptee to match Target
+class Adapter(Target):
     def __init__(self, adaptee: Adaptee):
         self.adaptee = adaptee
 
     def request(self):
         return f"Adapter: (TRANSLATED) {self.adaptee.specific_request()[::-1]}"
 ```
 
-In this example, `Target` is the interface that we expect to use. However, `Adaptee` has a different interface and cannot be used directly. The `Adapter` class wraps `Adaptee` in such a way that it can be used as if it had the expected interface.
+### Usage
 
-## See Also
+```python
+adaptee = Adaptee()
+adapter = Adapter(adaptee)
+print(adapter.request())  # Output: Adapter: (TRANSLATED) Special behavior of the Adaptee.
+```
+
+In this example:
+
+* `Target` is the expected interface.
+* `Adaptee` has an incompatible method.
+* `Adapter` wraps `Adaptee` and translates its output to match what the client expects.
+
+## Learn More
 
-The corresponding Python file can be found [here](https://github.com/taggedzi/python-design-pattern-rag/blob/main/patterns/structural/adapter.py).
+You can find the complete implementation in Python here:
+[Adapter Pattern on GitHub](https://github.com/taggedzi/python-design-pattern-rag/blob/main/patterns/structural/adapter.py)

docs/structural_bridge.md

@@ -1,61 +1,84 @@
 # The Bridge Pattern (Structural)
 
-## Intent
+## Purpose
 
-The Bridge pattern is a design pattern designed to "decouple an abstraction from its implementation so that the two can vary independently". It's useful when you want to avoid permanent binding between abstraction and implementation, which means one shouldn't have to change the other.
+The Bridge pattern is used to separate an abstraction from its implementation, so that both can evolve independently. It helps reduce tight coupling between code that defines what something does (abstraction) and code that defines how it does it (implementation).
 
-## Problem It Solves
+## The Problem It Solves
 
-Imagine you are designing a software system where there are different ways of rendering shapes (e.g., as lines or pixels). The problem is that this could lead to tight coupling if every shape has its own renderer, making it hard to add new shapes without modifying existing ones. This pattern helps to decouple the abstraction from the implementation so they can vary independently.
+Imagine you’re building shapes (like circles and squares) that can be rendered in different ways (like using pixels or lines). Without the Bridge pattern, you'd need a separate class for every combination—`PixelCircle`, `LineCircle`, `PixelSquare`, and so on. This quickly becomes unmanageable as the number of shapes and renderers grows. The Bridge pattern solves this by allowing shapes and renderers to be combined flexibly at runtime.
 
 ## When to Use It
 
-The Bridge Pattern should be used when you want to abstract and separate the implementation details from the high-level interface or abstraction, which makes them independent of each other.
+Use the Bridge pattern when:
+
+* You want to avoid creating a large number of subclasses to support combinations of features.
+* You want to be able to change the implementation details without touching the abstraction.
+* You need flexibility in assigning different behaviors (implementations) to high-level logic (abstractions).
 
 ## When NOT to Use It
 
-You shouldn't use the Bridge pattern if the "abstraction" and "implementation" are too tightly coupled. The key idea is that they should be able to vary independently, so a change in one should not require a change in the other.
+Avoid this pattern if:
+
+* The abstraction and implementation are already tightly bound and unlikely to change.
+* Introducing the pattern would add unnecessary complexity to a simple design.
 
 ## How It Works
 
-The Bridge Pattern involves an Abstraction (Shape) which has a reference to its Implementor (Renderer). This allows for different implementations of Renderer and Shape can use any implementation at runtime.
+The Bridge pattern breaks a class into two parts:
+
+1. **Abstraction** – The high-level control or logic (e.g., a shape like `Circle`).
+2. **Implementor** – The low-level implementation (e.g., how the shape is rendered).
+
+The abstraction holds a reference to the implementor. This means you can swap out implementations without modifying the abstraction.
 
 ## Real-World Analogy
 
-You could think of the Bridge pattern as a road bridge that connects two different types of roads (abstractions) with varying degrees of difficulty to navigate (implementations). The bridge itself is designed in such a way that it allows both types of vehicles to pass through, without having to change either type.
+Think of a remote control (abstraction) that can operate different types of TVs (implementation). The remote sends commands, but the way the TV responds depends on the model. You can change the TV or the remote without having to redesign the other.
 
 ## Simplified Example
 
-Here's a simplified example:
+Here’s a simple Python implementation:
 
 ```python
-class Shape:  # Abstraction
-    def __init__(self, renderer):
-        self.renderer = renderer  # Implementor
+# Implementor
+class Renderer:
+    def what_to_render(self):
+        raise NotImplementedError
 
-    def draw(self):
-        pass
+class VectorRenderer(Renderer):
+    def what_to_render(self):
+        return "lines"
+
+class RasterRenderer(Renderer):
+    def what_to_render(self):
+        return "pixels"
+
+# Abstraction
+class Shape:
+    def __init__(self, name, renderer: Renderer):
+        self.name = name
+        self.renderer = renderer
 
-class Circle(Shape):  # Refined abstraction
     def draw(self):
         return f"Drawing {self.name} as {self.renderer.what_to_render()}"
 
-class Renderer:  # Implementor
-    @staticmethod
-    def what_to_render():
-        pass
-
-class VectorRenderer(Renderer):  # Concrete implementor
-    @staticmethod
-    def what_to_render():
-        return "lines"
+# Usage
+circle = Shape("Circle", VectorRenderer())
+print(circle.draw())  # Drawing Circle as lines
 
-class RasterRenderer(Renderer):  # Another concrete implementor
-    @staticmethod
-    def what_to_render():
-        return "pixels"
+square = Shape("Square", RasterRenderer())
+print(square.draw())  # Drawing Square as pixels
 ```
 
-## See Also
+In this example:
+
+* `Shape` is the abstraction.
+* `Renderer` is the implementation interface.
+* `VectorRenderer` and `RasterRenderer` are concrete implementations.
+* The `Shape` can work with any renderer.
+
+## Learn More
 
-The corresponding Python file can be found [here](https://github.com/taggedzi/python-design-pattern-rag/blob/main/patterns/structural/bridge.py).
+You can find the full implementation in Python here:
+[Bridge Pattern on GitHub](https://github.com/taggedzi/python-design-pattern-rag/blob/main/patterns/structural/bridge.py)

docs/structural_composite.md

@@ -1,53 +1,94 @@
 # The Composite Pattern (Structural)
 
-## Intent
+## Purpose
 
-The Composite pattern is used to organize and structure complex tree structures made up of objects where each object can be treated individually or collectively. It provides a way to compose objects into tree structures and then work with these structures as if they were individual objects.
+The Composite pattern is used to treat individual objects and groups of objects in a uniform way. It allows you to build tree-like structures (like folders, menus, or graphical elements) where each part of the tree can be treated the same—whether it's a single item or a group of items.
 
-## Problem It Solves
+## The Problem It Solves
 
-This design pattern addresses the problem of treating individual objects and compositions uniformly, which simplifies code management and organization. It allows clients to treat complex trees structured as well-defined data structures (individual objects) in a uniform manner.
+In many applications, you may need to work with structures made of both simple and complex elements. Without the Composite pattern, you’d have to write separate logic to handle individual items and groups, leading to repetitive code. This pattern unifies them under a common interface, simplifying how they’re managed and manipulated.
 
 ## When to Use It
 
-The Composite pattern is ideal when you want to create complex tree structures where each node can be treated individually or collectively, making it suitable for use cases such as file systems, HTML documents, and database queries.
+Use the Composite pattern when:
+
+* You need to represent part-whole hierarchies (e.g., file systems, document outlines).
+* You want to treat individual objects and groups of objects uniformly.
+* You need to support recursive structures, such as trees or nested containers.
 
 ## When NOT to Use It
 
-It's not a good idea to overuse the Composite pattern because it might make code more complicated than necessary. If your application doesn’t require complex tree structures or hierarchies, using simpler patterns like classes could be sufficient.
+Avoid this pattern if:
+
+* Your structure is flat and doesn’t benefit from a hierarchy.
+* Adding abstraction through a component interface makes your code unnecessarily complex.
+* Simpler class designs can get the job done more clearly.
 
 ## How It Works
 
-The Composite pattern involves three main components: Component (abstract base class), Leaf (concrete component with no children) and Composite (concrete component with sub-components). The Component interface declares common operations for both simple and complex objects of a composition. A client uses these classes to work with the compositions in a uniform manner.
+The pattern involves three core parts:
+
+1. **Component** – The base interface or abstract class that defines common operations.
+2. **Leaf** – Represents the individual objects with no children.
+3. **Composite** – Represents complex objects that can have child components (both leaves and other composites).
+
+The key is that both `Leaf` and `Composite` implement the same interface, allowing client code to interact with them the same way.
 
 ## Real-World Analogy
 
-Imagine you have a family tree, where each person can be an individual leaf (you), or they could be part of a larger group (your siblings). If your family grows, it's not uncommon for new members to join the group - just like how a composite object can contain other composites or leaves.
+Imagine a company org chart. An individual employee is a leaf, while a department head (composite) manages a group of employees and possibly other departments. Whether you're interacting with an individual or a department, you treat them the same when asking for a task report.
 
 ## Simplified Example
 
-Here is a simplified example:
+Here’s a basic example in Python:
 
 ```python
-class Component:  # Abstract base class
-    def operation(self) -> str: pass
+from typing import List
 
-class Leaf(Component):  # Concrete component with no children
-    def __init__(self, name: str) -> None: self.name = name
-    def operation(self) -> str: return f"Leaf({self.name})"
+class Component:
+    def operation(self) -> str:
+        pass
 
-class Composite(Component):  # Concrete component with sub-components
-    def __init__(self, name: str) -> None:
+class Leaf(Component):
+    def __init__(self, name: str):
+        self.name = name
+
+    def operation(self) -> str:
+        return f"Leaf({self.name})"
+
+class Composite(Component):
+    def __init__(self, name: str):
         self.name = name
         self._children: List[Component] = []
-    
-    def add(self, component: Component) -> None: self._children.append(component)
-    def remove(self, component: Component) -> None: self._children.remove(component)
-    def operation(self) -> str: 
+
+    def add(self, component: Component) -> None:
+        self._children.append(component)
+
+    def remove(self, component: Component) -> None:
+        self._children.remove(component)
+
+    def operation(self) -> str:
         results = [child.operation() for child in self._children]
         return f"Composite({self.name})[{' + '.join(results)}]"
 ```
 
-## See Also
+### Example Usage:
+
+```python
+root = Composite("root")
+leaf1 = Leaf("A")
+leaf2 = Leaf("B")
+subtree = Composite("branch")
+subtree.add(Leaf("C"))
+
+root.add(leaf1)
+root.add(subtree)
+root.add(leaf2)
+
+print(root.operation())  # Composite(root)[Leaf(A) + Composite(branch)[Leaf(C)] + Leaf(B)]
+```
+
+## Learn More
 
-The corresponding Python file can be found [here](https://github.com/taggedzi/python-design-pattern-rag/blob/main/patterns/structural/composite.py).
+For the full implementation in Python, visit:
+[Composite Pattern on GitHub](https://github.com/taggedzi/python-design-pattern-rag/blob/main/patterns/structural/composite.py)