philiprehberger-singleton

Thread-safe singleton and multiton pattern decorators.

Installation

pip install philiprehberger-singleton

Usage

Singleton

The @singleton decorator ensures only one instance of a class exists:

from philiprehberger_singleton import singleton

@singleton
class Database:
    def __init__(self, url: str) -> None:
        self.url = url

db1 = Database("postgres://localhost/mydb")
db2 = Database("postgres://localhost/other")

assert db1 is db2  # same instance
assert db1.url == "postgres://localhost/mydb"

Reset

Use reset() to discard the cached instance (useful in tests):

Database.reset()
db3 = Database("postgres://localhost/new")
assert db3.url == "postgres://localhost/new"

Read-only access via instance()

instance() returns the cached singleton without constructing one. Useful when callers should not be able to create the singleton, only access it.

Database("postgres://localhost/mydb")
db = Database.instance()        # → existing instance
Database.reset()
Database.instance()             # raises RuntimeError

Non-raising existence check via is_instantiated()

When you only need to know whether the singleton was constructed (and don't want to use try/except around instance()), call is_instantiated():

if Database.is_instantiated():
    Database.instance().close()

Multiton

The @multiton(key=...) decorator maintains one instance per unique key value:

from philiprehberger_singleton import multiton

@multiton(key="name")
class Connection:
    def __init__(self, name: str, timeout: int = 30) -> None:
        self.name = name
        self.timeout = timeout

cache = Connection("cache", timeout=10)
db = Connection("db", timeout=60)
cache2 = Connection("cache")

assert cache is cache2       # same key -> same instance
assert cache is not db        # different key -> different instance

Reset

Use reset() to discard all cached instances:

Connection.reset()

API

Development

pip install -e .
python -m pytest tests/ -v

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT