singleton-decorator

What it is and what it does

singleton-decorator is a minimal Python decorator that enforces the singleton pattern—ensuring only one instance of a decorated class exists—while solving a key testing problem. Standard singleton decorators wrap a class in a function, making the class inaccessible for direct method calls in unit tests. This package instead uses a wrapper object that exposes the original class via `__wrapped__`, allowing tests to call class methods in isolation without instantiation.

The decorator is straightforward to use: apply `@singleton` to any class, then instantiate it normally. All calls return the same instance. For unit testing, access `ClassName.__wrapped__` to get the raw class and call its methods with mock objects as `self`, avoiding constructor side effects and test isolation problems.

Use it for:

• Enforce singleton pattern on configuration or service classes that should have exactly one instance across an application.
• Unit test singleton-decorated classes by calling methods directly on `__wrapped__` with mock objects, avoiding constructor execution.
• Ensure test isolation by accessing the underlying class without triggering singleton instance creation or initialization logic.
• Replace hand-written singleton boilerplate with a simple decorator for cleaner, more readable class definitions.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides a decorator that enforces singleton pattern on classes while preserving direct access to the underlying class for unit testing via the `__wrapped__` attribute.

No. The package is under GPLv3 copyleft, which restricts use in proprietary or permissively-licensed projects. More critically, it has been dormant since 2017 with no Python version specification and no updates for modern Python ecosystems. The core functionality is trivial to implement inline (a few lines of code), and the lack of maintenance creates compatibility and security uncertainty. Use only if you are in a GPLv3-compatible codebase and willing to accept the maintenance risk.

Install

singleton-decorator on PyPI

pip install singleton-decorator

uv add singleton-decorator

poetry add singleton-decorator

Installing singleton-decorator

Before you install

High install friction and dormant maintenance: last release was 2017-08-10 with no updates since, though the repository remains active. No runtime dependencies, but the package has not been maintained for years.

License in practice

Licensed under GPLv3 (copyleft). Any code that imports and uses this package must be distributed under a compatible copyleft license; proprietary or permissive-licensed projects cannot use it without legal review.

Quickstart

from singleton_decorator import singleton

@singleton
class MyClass:
    def method(self):
        pass

obj = MyClass()  # creates instance
obj2 = MyClass()  # returns same instance

# In tests, access the class directly:
MyClass.__wrapped__.method(mock_self)

Verify before relying

• Whether the package works with modern Python versions (requires_python is unspecified)
• Whether GPLv3 copyleft applies to derived works or only to modifications of the package itself
• Whether the dormant status and lack of updates since 2017 poses compatibility risks with current Python ecosystems

Package facts

Evidence: singleton-decorator-1.0.0.tar.gz

Keywords: singleton, decorator, unittest

Tags

More Testing packages