A Testable Singleton Decorator

Warnings

• gotcha The `__init__` method of a decorated singleton class is only executed during the *first* instantiation. Subsequent calls to the class constructor (e.g., `MyClass()`) will return the existing singleton instance, but any arguments passed in these later calls will be completely ignored and will not affect the already initialized instance.
  Fix: Design your singleton's `__init__` to handle initial setup only. If dynamic reconfiguration is needed, provide a separate public method (e.g., `configure(new_value)`) on the singleton instance.
• gotcha While `singleton-decorator` is designed to mitigate issues with `isinstance()` checks and direct static method calls by providing `__wrapped__`, many simpler singleton decorator implementations can break these functionalities. This library's explicit use of `__wrapped__` allows access to the original class definition.
  Fix: For unit testing or to access static/class methods of the original, undecorated class directly, use `YourClass.__wrapped__.your_method(obj)` (as demonstrated in the library's documentation) rather than `YourClass.your_method()`, especially when providing mock objects for `self`.
• gotcha The `singleton-decorator` does not explicitly implement thread-safety mechanisms. In a multi-threaded application, it is possible for multiple threads to concurrently attempt to create the first instance, potentially leading to the creation of more than one singleton object, thus violating the pattern.
  Fix: If your application operates in a multi-threaded environment and requires a truly thread-safe singleton, you must add explicit synchronization (e.g., using `threading.Lock`) within your class's initialization logic or consider a different thread-safe singleton implementation.
• gotcha The singleton pattern itself is often considered an anti-pattern due to its potential to introduce global state, tight coupling between components, and challenges in unit testing. While `singleton-decorator` attempts to make testing easier, these inherent drawbacks of the pattern should be carefully considered.
  Fix: Evaluate whether the singleton pattern is truly the most appropriate design for your specific use case. Alternative patterns like dependency injection or factory methods can often lead to more modular and testable code.

Install

• pip install singleton-decorator Install with pip

Imports

• singleton

  from singleton_decorator import singleton

Quickstart

This example demonstrates how to apply the `@singleton` decorator to a class. It shows that only one instance of `MyClass` is ever created, and subsequent calls to the constructor will return the existing instance without re-running `__init__`. It also highlights how to access the original, undecorated class using `__wrapped__` for testing purposes.

from singleton_decorator import singleton

@singleton
class MyClass:
    def __init__(self, value=0):
        self.value = value
        print(f"MyClass initialized with value: {self.value}")

    def get_value(self):
        return self.value

# First instance creates and initializes
obj1 = MyClass(10)
print(f"Obj1 value: {obj1.get_value()}")

# Second instance returns the same object, __init__ is NOT called again
obj2 = MyClass(20) # Arguments are ignored after the first call
print(f"Obj2 value: {obj2.get_value()}")
print(f"Are obj1 and obj2 the same instance? {obj1 is obj2}")

# Accessing the original class for testing or static methods
# Note: Use __wrapped__ for direct class method calls or inspection in tests
print(f"Accessing original class via __wrapped__: {MyClass.__wrapped__.__name__}")