Add Null Object and Singleton patterns, enhance Specification

- Add Null Object behavioral pattern with Customer/NullCustomer example

- Add Singleton creational pattern with AppConfig example

- Enhance Specification with real-world e-commerce product filtering example, full docstrings, and additional doctests

Author: abdalwahab-daw

patterns/behavioral/null_object.py

@@ -0,0 +1,135 @@
+"""
+http://code.tutsplus.com/articles/null-object-design-pattern--mobile-19377
+
+*TL;DR
+Provides a default object that acts as a surrogate for a missing object,
+avoiding the need for null checks throughout the codebase.
+
+*Examples in Python ecosystem:
+Python's logging module uses a NullHandler to discard log records when
+no other handlers are configured: https://docs.python.org/3/library/logging.handlers.html#logging.NullHandler
+"""
+
+# null_object.py
+
+from __future__ import annotations
+from typing import Union
+
+
+class Customer:
+    """
+    A real customer with actual behavior.
+    """
+
+    def __init__(self, name: str, email: str) -> None:
+        """
+        Initialize a customer with a name and email.
+
+        Args:
+            name (str): The customer's name.
+            email (str): The customer's email address.
+        """
+        self.name = name
+        self.email = email
+
+    def send_notification(self, message: str) -> None:
+        """
+        Send a notification to the customer.
+
+        Args:
+            message (str): The notification message.
+        """
+        print(f"Sending '{message}' to {self.name} at {self.email}")
+
+    def is_null(self) -> bool:
+        """
+        Indicate that this is a real customer, not a null object.
+        """
+        return False
+
+
+class NullCustomer(Customer):
+    """
+    A null object that mimics a Customer but performs no action.
+    Used as a safe default when a real customer is not found.
+    """
+
+    def __init__(self) -> None:
+        """
+        Initialize the null customer with default empty values.
+        """
+        self.name = "N/A"
+        self.email = "N/A"
+
+    def send_notification(self, message: str) -> None:
+        """
+        Override to do nothing instead of sending a notification.
+
+        Args:
+            message (str): The notification message (ignored).
+        """
+        pass
+
+    def is_null(self) -> bool:
+        """
+        Indicate that this is a null customer.
+        """
+        return True
+
+
+class CustomerRepository:
+    """
+    A simple repository that stores and retrieves customers.
+    Returns a NullCustomer when the requested customer is not found.
+    """
+
+    def __init__(self) -> None:
+        self._customers = {
+            1: Customer("Ahmed", "ahmed@example.com"),
+            2: Customer("Sara", "sara@example.com"),
+        }
+
+    def get_customer(self, customer_id: int) -> Union[Customer, NullCustomer]:
+        """
+        Retrieve a customer by ID, or return a NullCustomer if not found.
+
+        Args:
+            customer_id (int): The customer's unique identifier.
+
+        Returns:
+            Customer or NullCustomer: The matching customer or a null object.
+        """
+        return self._customers.get(customer_id, NullCustomer())
+
+
+def main():
+    """
+    >>> repo = CustomerRepository()
+
+    # Retrieve an existing customer and send a notification
+    >>> customer = repo.get_customer(1)
+    >>> customer.is_null()
+    False
+    >>> customer.send_notification("Your order has shipped")
+    Sending 'Your order has shipped' to Ahmed at ahmed@example.com
+
+    # Retrieve a non-existing customer - returns NullCustomer
+    >>> missing = repo.get_customer(999)
+    >>> missing.is_null()
+    True
+
+    # Calling methods on NullCustomer is safe and does nothing
+    >>> missing.send_notification("Your order has shipped")
+
+    # No null checks needed - the code stays clean
+    >>> for customer_id in [1, 2, 999]:
+    ...     repo.get_customer(customer_id).send_notification("Hello")
+    Sending 'Hello' to Ahmed at ahmed@example.com
+    Sending 'Hello' to Sara at sara@example.com
+    """
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

patterns/behavioral/specification.py

@@ -1,91 +1,196 @@
 """
 @author: Gordeev Andrey <gordeev.and.and@gmail.com>
 
+https://en.wikipedia.org/wiki/Specification_pattern
+
 *TL;DR
-Provides recombination business logic by chaining together using boolean logic.
+Encapsulates business rules as standalone objects that can be combined using
+boolean logic (AND, OR, NOT). This allows complex selection criteria to be
+built dynamically without hardcoding conditions throughout the codebase.
+
+*Examples in Python ecosystem:
+Django QuerySet API uses Q objects to compose database queries with logical
+operators, applying the same composition principle as the Specification pattern:
+https://docs.djangoproject.com/en/stable/topics/db/queries/#complex-lookups-with-q-objects
 """
 
 from abc import abstractmethod
 from typing import Union
 
 
 class Specification:
+    """
+    Base interface for all specifications.
+
+    A specification encapsulates a single business rule and can be combined
+    with other specifications using logical operators.
+    """
+
     def and_specification(self, candidate):
+        """Combine this specification with another using logical AND."""
         raise NotImplementedError()
 
     def or_specification(self, candidate):
+        """Combine this specification with another using logical OR."""
         raise NotImplementedError()
 
     def not_specification(self):
+        """Return the logical negation of this specification."""
         raise NotImplementedError()
 
     @abstractmethod
     def is_satisfied_by(self, candidate):
+        """
+        Check whether the given candidate satisfies this specification.
+
+        Args:
+            candidate: The object to evaluate against the rule.
+
+        Returns:
+            bool: True if the candidate satisfies the rule, otherwise False.
+        """
         pass
 
 
 class CompositeSpecification(Specification):
+    """
+    Abstract specification that provides default implementations for
+    combining specifications using AND, OR, and NOT.
+
+    All concrete specifications should inherit from this class to gain
+    automatic support for logical composition.
+    """
+
     @abstractmethod
     def is_satisfied_by(self, candidate):
         pass
 
     def and_specification(self, candidate: "Specification") -> "AndSpecification":
+        """Return a new specification that is satisfied when both rules are satisfied."""
         return AndSpecification(self, candidate)
 
     def or_specification(self, candidate: "Specification") -> "OrSpecification":
+        """Return a new specification that is satisfied when at least one rule is satisfied."""
         return OrSpecification(self, candidate)
 
     def not_specification(self) -> "NotSpecification":
+        """Return a new specification that is satisfied when this rule is NOT satisfied."""
         return NotSpecification(self)
 
 
 class AndSpecification(CompositeSpecification):
+    """
+    Composite specification satisfied only when BOTH inner specifications are satisfied.
+    """
+
     def __init__(self, one: "Specification", other: "Specification") -> None:
         self._one: Specification = one
         self._other: Specification = other
 
-    def is_satisfied_by(self, candidate: Union["User", str]) -> bool:
+    def is_satisfied_by(self, candidate) -> bool:
         return bool(
             self._one.is_satisfied_by(candidate)
             and self._other.is_satisfied_by(candidate)
         )
 
 
 class OrSpecification(CompositeSpecification):
+    """
+    Composite specification satisfied when AT LEAST ONE of the inner specifications is satisfied.
+    """
+
     def __init__(self, one: "Specification", other: "Specification") -> None:
         self._one: Specification = one
         self._other: Specification = other
 
-    def is_satisfied_by(self, candidate: Union["User", str]):
+    def is_satisfied_by(self, candidate) -> bool:
         return bool(
             self._one.is_satisfied_by(candidate)
             or self._other.is_satisfied_by(candidate)
         )
 
 
 class NotSpecification(CompositeSpecification):
-    def __init__(self, wrapped: "Specification"):
+    """
+    Composite specification satisfied when the wrapped specification is NOT satisfied.
+    """
+
+    def __init__(self, wrapped: "Specification") -> None:
         self._wrapped: Specification = wrapped
 
-    def is_satisfied_by(self, candidate: Union["User", str]):
+    def is_satisfied_by(self, candidate) -> bool:
         return bool(not self._wrapped.is_satisfied_by(candidate))
 
 
+# ---------------------------------------------------------------------------
+# Original example: User / SuperUser
+# ---------------------------------------------------------------------------
+
+
 class User:
     def __init__(self, super_user: bool = False) -> None:
         self.super_user = super_user
 
 
 class UserSpecification(CompositeSpecification):
-    def is_satisfied_by(self, candidate: Union["User", str]) -> bool:
+    """Specification satisfied when the candidate is a User instance."""
+
+    def is_satisfied_by(self, candidate) -> bool:
         return isinstance(candidate, User)
 
 
 class SuperUserSpecification(CompositeSpecification):
-    def is_satisfied_by(self, candidate: "User") -> bool:
+    """Specification satisfied when the candidate is a super-user."""
+
+    def is_satisfied_by(self, candidate) -> bool:
         return getattr(candidate, "super_user", False)
 
 
+# ---------------------------------------------------------------------------
+# Real-world example: filtering products in an e-commerce catalog
+# ---------------------------------------------------------------------------
+
+
+class Product:
+    """A simple product in an e-commerce catalog."""
+
+    def __init__(self, name: str, price: float, category: str, in_stock: bool) -> None:
+        self.name = name
+        self.price = price
+        self.category = category
+        self.in_stock = in_stock
+
+    def __repr__(self) -> str:
+        return self.name
+
+
+class PriceBelowSpecification(CompositeSpecification):
+    """Specification satisfied when the product's price is below a given limit."""
+
+    def __init__(self, limit: float) -> None:
+        self._limit = limit
+
+    def is_satisfied_by(self, candidate: Product) -> bool:
+        return candidate.price < self._limit
+
+
+class InCategorySpecification(CompositeSpecification):
+    """Specification satisfied when the product belongs to a given category."""
+
+    def __init__(self, category: str) -> None:
+        self._category = category
+
+    def is_satisfied_by(self, candidate: Product) -> bool:
+        return candidate.category == self._category
+
+
+class InStockSpecification(CompositeSpecification):
+    """Specification satisfied when the product is in stock."""
+
+    def is_satisfied_by(self, candidate: Product) -> bool:
+        return candidate.in_stock
+
+
 def main():
     """
     >>> andrey = User()
@@ -101,10 +206,38 @@ def main():
     (True, 'ivan')
     >>> root_specification.is_satisfied_by(vasiliy), 'vasiliy'
     (False, 'vasiliy')
+
+    # Real-world example: filtering products in an e-commerce catalog
+    >>> products = [
+    ...     Product('Python Book', 45.0, 'books', True),
+    ...     Product('Laptop', 1200.0, 'electronics', True),
+    ...     Product('Headphones', 80.0, 'electronics', False),
+    ...     Product('Notebook', 5.0, 'stationery', True),
+    ... ]
+
+    # Build composable rules
+    >>> cheap = PriceBelowSpecification(100)
+    >>> electronics = InCategorySpecification('electronics')
+    >>> available = InStockSpecification()
+
+    # Show cheap products that are in stock
+    >>> cheap_and_available = cheap.and_specification(available)
+    >>> [p for p in products if cheap_and_available.is_satisfied_by(p)]
+    [Python Book, Notebook]
+
+    # Show electronics that are out of stock (using NOT)
+    >>> out_of_stock_electronics = electronics.and_specification(available.not_specification())
+    >>> [p for p in products if out_of_stock_electronics.is_satisfied_by(p)]
+    [Headphones]
+
+    # Show cheap items OR electronics
+    >>> cheap_or_electronics = cheap.or_specification(electronics)
+    >>> [p for p in products if cheap_or_electronics.is_satisfied_by(p)]
+    [Python Book, Laptop, Headphones, Notebook]
     """
 
 
 if __name__ == "__main__":
     import doctest
 
-    doctest.testmod()
+    doctest.testmod()