Edited creational patterns.

Author: taggedzi

docs/creational_abstract_factory.md

@@ -1,43 +1,55 @@
 # The Abstract Factory Pattern (Creational)
 
-## Intent
+## Purpose
 
-The Abstract Factory pattern provides an interface for creating families of related or dependent objects without specifying their concrete classes. It's used to abstract away the details of how a set of products are created, composed and represented.
+The Abstract Factory pattern provides an interface for creating groups of related or dependent objects without needing to specify their exact classes. It’s used to make systems more flexible and easier to extend by abstracting the creation of product families.
 
-## Problem It Solves
+## The Problem It Solves
 
-In software development, we often have systems that need to be flexible and adaptable. This is where the Abstract Factory pattern comes in handy. Imagine you’re developing an application for both Windows and MacOS platforms. You want your codebase to be as platform-independent as possible so it can easily support new operating systems without having to modify a lot of existing code. The Abstract Factory pattern allows you to do this by providing a way to encapsulate a group of individual factories that have a common theme, i.e., they create products belonging to the same product family.
+In some programs, you need to support multiple sets of objects that should work together—for example, GUI elements for different operating systems like Windows and macOS. Instead of scattering `if-else` or `switch` logic across your code to decide which object to create, you can use an abstract factory to centralize and simplify that decision. This makes it easier to support new platforms or themes in the future.
 
 ## When to Use It
 
-The Abstract Factory is all about decoupling the client from concrete implementations and making it work with any pre-configured factory or set of related factories without having to modify your codebase. This pattern should be used when you want a run-time pluggability of products, i.e., you need an application that can use instances of different families of products.
+Use the Abstract Factory pattern when:
+
+* Your code needs to work with multiple families of related objects (e.g., a GUI that supports different platforms).
+* You want to avoid hard-coding specific class names throughout your codebase.
+* You want to provide a way to switch between different product families at runtime.
 
 ## When NOT to Use It
 
-The Abstract Factory is not suitable for systems where the client needs to work with only one product family at a time. If your system deals with just two or three classes related by a common interface, it might be simpler and more straightforward to instantiate these classes directly using constructor injection.
+Avoid this pattern if:
+
+* Your app only uses a small number of related classes, and adding abstraction would complicate the design.
+* You don’t need to support multiple interchangeable families of products.
 
 ## How It Works
 
-In an Abstract Factory pattern, there are four main components:
+The pattern includes four main parts:
 
-1. **Abstract Products** - These are the interfaces that define operations for different types of products. In our example, this would include `Button` and `Checkbox` abstract classes.
-2. **Concrete Products** - These are the actual implementations of the Abstract Products. We have separate concrete product classes for each operating system (Windows and MacOS).
-3. **Abstract Factory** - This is an interface that provides methods to create different types of products. In our example, this would be `GUIFactory`.
-4. **Concrete Factories** - These are the implementations of Abstract Factory interfaces. Each Concrete Factory corresponds to a specific operating system and creates concrete product objects belonging to that family.
+1. **Abstract Products** – Interfaces that define common operations (e.g., `Button`, `Checkbox`).
+2. **Concrete Products** – Actual implementations of those interfaces for each product family (e.g., `WindowsButton`, `MacButton`).
+3. **Abstract Factory** – An interface for creating each type of product (e.g., `GUIFactory`).
+4. **Concrete Factories** – Implementations of the abstract factory for each product family (e.g., `WindowsFactory`, `MacFactory`).
 
 ## Real-World Analogy
 
-Imagine you're at a supermarket. You have different sections for fruits, vegetables, dairy products etc., each with their own counters and checkout lines. Now imagine if the supermarket had a way of dynamically managing these sections based on your shopping preferences (e.g., vegan or gluten-free). That's similar to how an Abstract Factory pattern allows for dynamic management of product families in an application, based on runtime configuration or user preference.
+Think of a supermarket that adapts to your dietary needs. If you choose "vegan," you’re directed to vegan fruit, vegan dairy alternatives, and vegan baked goods—all tailored to that lifestyle. Similarly, an abstract factory delivers a full set of products matched to a specific family or context, without mixing them up.
 
 ## Simplified Example
 
-Here is a simplified example:
+Here’s a basic structure in Python:
 
 ```python
-class ProductA:
+from abc import ABC, abstractmethod
+
+# Abstract Product
+class ProductA(ABC):
+    @abstractmethod
     def do_something(self) -> str:
         pass
 
+# Concrete Products
 class ConcreteProductA1(ProductA):
     def do_something(self) -> str:
         return "Implementation of Product A1"
@@ -47,8 +59,14 @@ class ConcreteProductA2(ProductA):
         return "Implementation of Product A2"
 ```
 
-In this example, `ProductA` is the Abstract Product and `ConcreteProductA1` and `ConcreteProductA2` are its concrete implementations.
+In this example:
+
+* `ProductA` is the abstract product.
+* `ConcreteProductA1` and `ConcreteProductA2` are platform- or theme-specific implementations.
+
+In a full version, you’d also have a factory interface and one or more factory classes to create the products.
 
-## See Also
+## Learn More
 
-The corresponding Python file for this lesson can be found [here](https://github.com/taggedzi/python-design-pattern-rag/blob/main/patterns/creational/abstract_factory.py).
+You can view the complete implementation in Python here:
+[Abstract Factory on GitHub](https://github.com/taggedzi/python-design-pattern-rag/blob/main/patterns/creational/abstract_factory.py)

docs/creational_borg.md

@@ -2,27 +2,35 @@
 
 ## Purpose
 
-The Borg pattern creates objects that share the same state without having to inherit from a common class. It helps simplify programs by allowing different objects to access and update shared data.
+The Borg pattern allows multiple instances of a class to share the same internal state. Unlike the Singleton pattern—which restricts you to a single instance—Borg lets you create many instances that all behave as if they share one brain.
 
 ## The Problem It Solves
 
-In complex systems, it's often hard to manage shared data across multiple objects. Normally, you’d use inheritance or global variables to do this, but those approaches can be messy or limiting. The Borg pattern solves this by letting every instance share the same internal state.
+In some applications, you need objects to share data—for example, configuration settings or a pool of reusable resources. While global variables or singletons can do this, they often come with drawbacks like tight coupling or reduced flexibility. Borg offers an alternative by letting multiple objects share state without being the same instance.
 
 ## When to Use It
 
-Use the Borg pattern when you need several objects to share and update the same data. For example, if you have many parts of a program that need to access the same settings or manage the same pool of resources, Borg can help keep things in sync without using global variables or inheritance.
+Use the Borg pattern when:
+
+* You want multiple instances to share the same internal data.
+* You need a lightweight way to synchronize state across objects.
+* You want to avoid singletons but still centralize shared information.
 
 ## When NOT to Use It
 
-Don’t use the Borg pattern if each object should keep its own separate data. Also, if you’re working in a multithreaded environment and need to prevent unexpected changes, Borg might not be the right choice—it's not designed to be thread-safe.
+Avoid the Borg pattern if:
+
+* Each object should have its own unique state.
+* You're working in a multithreaded environment—Borg is not thread-safe without extra precautions.
+* You're storing sensitive data that must be isolated per instance.
 
 ## How It Works
 
-The Borg class stores all shared data in a single dictionary called `_shared_state`. When you create a new Borg object, it links its internal data (`__dict__`) to this shared dictionary. So any change made by one object shows up in all others.
+The Borg pattern links every instance’s `__dict__` (its storage for instance variables) to a class-level shared dictionary. So any change made through one instance is immediately visible to all others.
 
 ## Real-World Analogy
 
-Think of a team of scientists using a shared notebook. Each scientist (object) may have their own pen (methods), but they all write in the same notebook (shared data). Whatever one writes, everyone else can see and change.
+Imagine several scientists using a single shared notebook. Each scientist can write or read from it, but there’s only one notebook. Whatever one scientist writes, the others will see—it’s a shared workspace for data.
 
 ## Simplified Example
 
@@ -37,10 +45,13 @@ class Borg:
 b1 = Borg()
 b2 = Borg()
 
-b1.x = 10  # Setting a value through one instance...
-print(b2.x)  # ...automatically affects the other.
+b1.x = 10  # Assigns x through one instance...
+print(b2.x)  # ...and it’s immediately visible in the other.
 ```
 
+In this example, both `b1` and `b2` have access to the same data, even though they're separate instances.
+
 ## Learn More
 
-You can see the full Borg pattern example on GitHub [here](https://github.com/taggedzi/python-design-pattern-rag/blob/main/patterns/creational/borg.py)
+You can explore the full implementation here:
+[Borg Pattern on GitHub](https://github.com/taggedzi/python-design-pattern-rag/blob/main/patterns/creational/borg.py)

docs/creational_builder.md

@@ -1,59 +1,117 @@
 # The Builder Pattern (Creational)
 
-## Intent
+## Purpose
 
-The Builder pattern is a design pattern designed to provide a flexible solution to various object creation problems in object-oriented programming. It allows constructing complex objects step by step.
+The Builder pattern helps you construct complex objects step by step. It separates the construction process from the final product, making it easier to create different versions or configurations of the same type of object.
 
-## Problem It Solves
+## The Problem It Solves
 
-Imagine you are building a complex house, say with multiple rooms and furniture. You don't want to build everything at once because it can take forever and your budget is tight. Instead, you start with the foundation (maybe just the basement), then gradually add more as you need them. This process of constructing an object step by step is what the Builder pattern solves for.
+Sometimes an object is too complex to create in one step—like building a house with a foundation, walls, windows, and furniture. You might want different versions of the house, such as a basic layout or a luxury model. The Builder pattern lets you construct such objects gradually, using a consistent process, while still allowing flexibility in the final result.
 
 ## When to Use It
 
-The Builder pattern should be used when:
+Use the Builder pattern when:
 
-1. You want your code to be able to create different representations of some product (for example, stone and wooden houses).
-2. The construction process must allow different representations for the product that are implemented in various subclasses.
-3. You need a simple interface to create complex objects.
+* You need to build complex objects with many parts.
+* You want to reuse the same construction process for different representations.
+* You want to isolate the construction logic from the actual product.
 
 ## When NOT to Use It
 
-The Builder pattern is not suitable when:
+Avoid this pattern if:
 
-1. The object creation algorithm can be defined once and does not get changed often.
-2. The client code should be simplified, without being overly complicated by the builder pattern.
-3. You need a simple interface that creates only complex objects.
+* The object is simple and doesn’t require step-by-step construction.
+* You only ever need one version of the object, and its structure rarely changes.
+* Adding builders introduces unnecessary complexity for your use case.
 
 ## How It Works
 
-The Builder pattern works with four roles: Product, Builder, Director, and Client.
+The pattern has four key components:
 
-1. **Product**: This is the object we are building. In our house example, it's the entire house.
-2. **Builder**: This defines an interface for creating parts of a product. In our house example, this could be adding rooms or furniture to the house.
-3. **Director**: This constructs an object using the Builder interface. It knows what part to build and in which order. In our house example, it would decide when to start building the basement first before moving on to add rooms later.
-4. **Client**: The client is responsible for creating a builder object, setting its properties, and running the construction process.
+1. **Product** – The final object being built (e.g., a house).
+2. **Builder** – Defines methods to build each part of the product (e.g., walls, windows).
+3. **ConcreteBuilder** – Implements the builder’s steps to build and assemble parts of the product.
+4. **Director** – Controls the construction process and calls builder methods in a specific order.
+
+The **Client** sets up the builder and director, then triggers the construction.
 
 ## Real-World Analogy
 
-Think of the Builder pattern as a blueprint for your house. You start with the foundation (reset), then gradually add more components like walls, doors, windows, etc., one by one. The director is like a builder guide who knows exactly when to build each part and in what order.
+Think of building a house. You use a blueprint (the builder interface), hire a contractor (the concrete builder), and follow a schedule (the director) to build it step by step. The builder adds pieces like the foundation, walls, and roof. The director decides what to build first and when.
 
 ## Simplified Example
 
-Here's a simplified example of how you might use it:
-
 ```python
+# Builder interface
+class Builder(ABC):
+    @abstractmethod
+    def build_part_a(self): pass
+    @abstractmethod
+    def build_part_b(self): pass
+    @abstractmethod
+    def get_product(self): pass
+
+# Concrete builder
+class ConcreteBuilder(Builder):
+    def __init__(self):
+        self.reset()
+    
+    def reset(self):
+        self._product = Product()
+    
+    def build_part_a(self):
+        self._product.add("PartA")
+    
+    def build_part_b(self):
+        self._product.add("PartB")
+    
+    def get_product(self):
+        product = self._product
+        self.reset()
+        return product
+
+# Product
+class Product:
+    def __init__(self):
+        self.parts = []
+    
+    def add(self, part):
+        self.parts.append(part)
+    
+    def list_parts(self):
+        return ", ".join(self.parts)
+
+# Director
+class Director:
+    def __init__(self, builder: Builder):
+        self._builder = builder
+    
+    def build_minimal_viable_product(self):
+        self._builder.build_part_a()
+    
+    def build_full_featured_product(self):
+        self._builder.build_part_a()
+        self._builder.build_part_b()
+
+# Example usage
 builder = ConcreteBuilder()
 director = Director(builder)
 
-director.build_minimal_viable_product() # Builds only part A
-print("Minimal product:", builder.get_product().list_parts()) 
+director.build_minimal_viable_product()
+print("Minimal product:", builder.get_product().list_parts())
 
-director.build_full_featured_product() # Builds parts A and B
+director.build_full_featured_product()
 print("Full product:", builder.get_product().list_parts())
 ```
 
-In this example, `ConcreteBuilder` is the Builder that knows how to build a complex object (the house), `Director` guides the construction process by calling the appropriate building steps in sequence, and the client code creates a ConcreteBuilder object, sets its properties, and runs the construction process.
+### Output
+
+```text
+Minimal product: PartA
+Full product: PartA, PartB
+```
 
-## See Also
+## Learn More
 
-You can find more details about this pattern [here](https://github.com/taggedzi/python-design-pattern-rag/blob/main/patterns/creational/builder.py).
+For a full implementation and examples, check:
+[Builder Pattern on GitHub](https://github.com/taggedzi/python-design-pattern-rag/blob/main/patterns/creational/builder.py)