how to implement singleton pattern in python

Implementing Singleton Python via the __new__ Method

Most developers attempt to enforce the Singleton pattern by simply hiding the constructor or using a global variable. This is amateur hour. As a Senior Architect, I demand precision. To truly control instantiation in Python, you must intercept the object creation process itself.

That interception point is __new__. Unlike __init__, which initializes an existing object, __new__ is the factory that actually creates it. By overriding this method, we gain absolute control over whether a new instance is born or an existing one is returned.

class Singleton: # Class variable to hold the single instance _instance = None def __new__(cls, *args, **kwargs): # 1. Check if instance exists if cls._instance is None: # 2. If not, create it using the standard factory cls._instance = super().__new__(cls) # Optional: Initialize state here if needed else: # 3. If it exists, we skip __init__ to prevent resetting state # (This is a common optimization in Singleton patterns) pass # 4. Return the instance (either new or existing) return cls._instance def __init__(self, value): # This only runs once if we guard it, or every time if we don't. # For a strict Singleton, we usually guard this too. if not hasattr(self, 'initialized'): self.value = value self.initialized = True # Usage obj1 = Singleton("Alpha") obj2 = Singleton("Beta") print(obj1 is obj2) # True: They are the exact same object print(obj1.value) # "Alpha": The second init was skipped or ignored 

Key Takeaways

• Interception: __new__ is the only way to truly control object creation in Python.
• State Management: Be careful with __init__. It may run multiple times if you aren't careful with flags.
• Testing: Singletons are notorious for making unit tests brittle because state persists. Always reset your singletons in your test teardown.

You have mastered the control of state. Now, let's see how objects communicate. Dive into the Observer Pattern to see how objects can react to changes without tight coupling.

The Decorator Pattern: Wrapping Behavior

Imagine you are building a coffee ordering system. You have a base coffee, but customers want to add milk, sugar, or whipped cream. Do you create a subclass for BlackCoffeeWithMilk, BlackCoffeeWithSugar, and BlackCoffeeWithMilkAndSugar? That is the Class Explosion problem.

The Decorator Pattern solves this by wrapping objects dynamically. It allows you to attach additional responsibilities to an object without modifying its structure. It is the architectural equivalent of putting a wrapper around a gift—you can change the presentation without changing the gift itself.

Implementation: The Coffee Shop

In Python, we achieve this by having our decorators accept a component in their __init__ method. Notice how Milk and Sugar both inherit from Coffee but also wrap another Coffee instance.

# The Base Component
class Coffee:
    def cost(self):
        return 5.0
    def description(self):
        return "Black Coffee"

# The Concrete Component
class Espresso(Coffee):
    def cost(self):
        return 7.0
    def description(self):
        return "Strong Espresso"

# The Decorator Base Class
class CoffeeDecorator(Coffee):
    def __init__(self, coffee):
        self._coffee = coffee
    def cost(self):
        return self._coffee.cost()
    def description(self):
        return self._coffee.description()

# Concrete Decorators
class Milk(CoffeeDecorator):
    def cost(self):
        return super().cost() + 1.5
    def description(self):
        return super().description() + ", Milk"

class Sugar(CoffeeDecorator):
    def cost(self):
        return super().cost() + 0.5
    def description(self):
        return super().description() + ", Sugar"

# Usage
my_order = Sugar(Milk(Espresso()))
print(f"{my_order.description()} - ${my_order.cost():.2f}")
# Output: Strong Espresso, Milk, Sugar - $9.00

Why Architects Love This Pattern

Pro-Tip: Python has a built-in @decorator syntax for functions. While syntactically similar, the Structural Decorator Pattern we just built is about wrapping objects, not just functions.

Key Takeaways

• Composition over Inheritance: This pattern is the ultimate example of composition over inheritance. It builds complex behavior by combining simple objects.
• Transparency: The client code treats the decorated object exactly the same as the original object because they share the same interface.
• Order Matters: In some implementations, the order of decorators can affect the result (e.g., tax calculation vs. discount application).

You have mastered wrapping objects. But what if you want to wrap a function's behavior instead? Explore how to implement custom decorators in Python to see how this concept powers frameworks like Flask and Django.

Advanced Control: Metaclasses for Singleton Python

You have mastered classes. You know how to instantiate objects. But have you ever asked: who creates the class? In Python, classes are objects too. And just as you can control the creation of an object, you can control the creation of a class. This is the realm of Metaclasses.

The Architect's Perspective: Why Metaclasses?

Most of the time, you will never need metaclasses. They are the "nuclear option" of Python. However, for enforcing architectural patterns like the Singleton Pattern (ensuring a class has only one instance), they provide the cleanest, most transparent solution.

Implementation: The Singleton Metaclass

To implement a Singleton, we need to override the __call__ method of the metaclass. This method is invoked when you call the class (e.g., MyClass()). By caching the instance in a dictionary, we ensure only one object ever exists.

# Define the Metaclass
class SingletonMeta(type):
    """ The Singleton Metaclass. Overrides __call__ to control instance creation. """
    _instances = {}
    def __call__(cls, *args, **kwargs):
        # Check if instance already exists
        if cls not in cls._instances:
            # If not, create it using the standard mechanism
            instance = super().__call__(*args, **kwargs)
            cls._instances[cls] = instance
        # Return the existing instance
        return cls._instances[cls]

# Define the Singleton Class
class DatabaseConnection(metaclass=SingletonMeta):
    def __init__(self):
        print("Initializing Database Connection...")
        self.connection_string = "postgresql://localhost:5432/db"

# Usage
if __name__ == "__main__":
    # First call
    db1 = DatabaseConnection()
    # Second call (should return cached instance)
    db2 = DatabaseConnection()
    # Verification
    print(f"db1 is db2: {db1 is db2}")
    # Output: db1 is db2: True

Metaclasses vs. Decorators

You might wonder why not just use a decorator? If you are interested in wrapping behavior, you should explore how to implement custom decorators in Python. However, decorators modify the class object itself, whereas metaclasses control the lifecycle of the instances.

The Pythonic Singleton: Leveraging Modules for Single Instance

Listen closely, because this is where many junior developers get lost in the weeds of design patterns. In languages like Java or C++, creating a Singleton requires boilerplate, private constructors, and reflection hacks. In Python? The language gives you a Singleton for free.

As a Senior Architect, I often tell my team: "If you are writing a metaclass to enforce a Singleton in Python, you are fighting the language." The secret lies in Python's Import System. A Python module is a Singleton by definition. It is instantiated exactly once per process, cached in memory, and reused on every subsequent import.

The Implementation: A Database Connection Pool

Let's look at a practical scenario. You need a global database connection. Instead of complex classes, we simply define the connection in a dedicated module. When other parts of your application import it, they all get the exact same object.

# database.py
# This module IS the singleton instance
class DatabaseConnection:
    def __init__(self):
        self.connection_string = "postgresql://localhost:5432/mydb"
        self.is_connected = False
        print(f"Initializing connection to {self.connection_string}")

    def connect(self):
        if not self.is_connected:
            print("Establishing network handshake...")
            self.is_connected = True
        return self

    def query(self, sql):
        if self.is_connected:
            return f"Executing: {sql}"
        return "Error: Not connected"

# Create the single instance immediately upon import
# This is the "Global" object
db_instance = DatabaseConnection()

Now, observe how we consume this in our application logic. We can import db_instance from multiple files, and it will always point to the same memory address.

# app.py
from database import db_instance

# First usage
db_instance.connect()
print(db_instance.query("SELECT * FROM users"))

# service.py (Imported elsewhere)
from database import db_instance

# Second usage - NO new connection is created!
# It uses the existing one from app.py
print(db_instance.query("SELECT * FROM orders"))

# Verification
print(f"ID in app.py: {id(db_instance)}")
# If you print id(db_instance) in service.py, it matches exactly.

Why This Beats the "Classic" Singleton

The "Classic" Singleton pattern often relies on overriding __new__ or using metaclasses. This adds cognitive load and makes testing difficult. By using a module:

• Lazy Loading: The instance is only created when the module is first imported.
• Testability: You can easily mock the database module in your unit tests without complex setup.
• Readability: It is immediately obvious to any Python developer what is happening.

Ensuring Thread Safety in Concurrent Singleton Python Environments

As you scale your applications, the Singleton pattern faces its ultimate test: Concurrency. In a multi-threaded environment, the simple "lazy initialization" we discussed earlier can crumble. Without proper synchronization, you risk the dreaded Check-then-Act Race Condition, where two threads simultaneously decide to create the Singleton, resulting in multiple instances and corrupted state.

The Race Condition: A Visual Breakdown

Imagine two threads, Thread A and Thread B, arriving at the Singleton factory at the exact same millisecond. Without a lock, both see that the instance is None and proceed to instantiate it.

class Singleton:
    _instance = None

    def __new__(cls):
        # RACE CONDITION HERE
        if cls._instance is None:
            # Both threads can pass this check simultaneously
            cls._instance = super().__new__(cls)
        return cls._instance

The Solution: Mutual Exclusion (Mutex)

To fix this, we introduce a Lock. A lock acts as a traffic cop, ensuring that only one thread can execute the critical section (instantiation) at a time. If Thread A holds the lock, Thread B must wait until A finishes.

import threading

class ThreadSafeSingleton:
    _instance = None
    _lock = threading.Lock()

    def __new__(cls):
        if cls._instance is None:
            with cls._lock:
                # Double-check inside the lock
                if cls._instance is None:
                    cls._instance = super().__new__(cls)
        return cls._instance

Testing Strategies for Singleton Pattern in Python Applications

The Singleton pattern is a classic architectural tool, but it is notorious for being the "villain" of unit testing. Why? Because global state is the enemy of isolation. When your code relies on a hidden, shared instance, your tests become fragile, order-dependent, and a nightmare to debug.

As a Senior Architect, I don't just tell you to "avoid Singletons." I teach you how to test them effectively when you absolutely must use them. The secret lies in Dependency Injection (DI) and Mocking.

The Problem: Hidden Dependencies

In a standard Singleton implementation, the class creates its own instance. This creates a hidden dependency. If you want to test a class that uses a Singleton, you are forced to interact with the real Singleton, which might hit a database or a network.

The Solution: Dependency Injection

The most robust strategy is to stop the Singleton from being a "God Object." Instead, pass the instance into the class that needs it. This is the core principle of how to implement observer pattern for loosely coupled systems.

# Bad: Hard to Mock
class DatabaseService:
    def __init__(self):
        # Hidden dependency!
        self.db = DatabaseSingleton.get_instance()

    def query(self, sql):
        return self.db.execute(sql)

# Good: Injected Dependency
class DatabaseService:
    def __init__(self, db_connection=None):
        # Default to Singleton, but allow override
        self.db = db_connection or DatabaseSingleton.get_instance()

    def query(self, sql):
        return self.db.execute(sql)

Executing the Test with Mocks

Now that we have injected the dependency, we can use Python's unittest.mock library to swap the real Singleton with a fake one. This ensures your tests run in milliseconds and never touch a real database.

from unittest.mock import MagicMock
from database_service import DatabaseService

def test_query_success():
    # 1. Create a fake database object
    mock_db = MagicMock()
    mock_db.execute.return_value = "Success"

    # 2. Inject the fake into the service
    service = DatabaseService(db_connection=mock_db)

    # 3. Run the test
    result = service.query("SELECT * FROM users")

    # 4. Verify the interaction
    assert result == "Success"
    mock_db.execute.assert_called_once_with("SELECT * FROM users")