fastapi-singleton 0.1.0__tar.gz

fastapi_singleton-0.1.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: fastapi-singleton
+Version: 0.1.0
+Summary: Application-scoped dependencies for FastAPI
+Author: Alex Ward
+Author-email: Alex Ward <alxwrd@googlemail.com>
+License-Expression: MIT
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Framework :: FastAPI
+Requires-Dist: fastapi>=0.115
+Requires-Python: >=3.13
+Project-URL: Repository, https://github.com/alxwrd/fastapi-singleton
+Project-URL: Releases, https://github.com/alxwrd/fastapi-singleton/releases
+Description-Content-Type: text/markdown
+
+<div align="center">
+    <h1><code>fastapi-singleton</code></h1>
+    <p align="center"><i>
+        Application-scoped dependencies for <code>fastapi</code>
+    </i></p>
+    <img width="256px" src=".github/assets/three-card-trickster-768.png">
+    <div align="center">
+        <a href="https://github.com/alxwrd/fastapi-singleton/actions/workflows/test.yml"><img src="https://img.shields.io/github/actions/workflow/status/alxwrd/fastapi-singleton/test.yml?branch=main&label=main"></a>
+        <a href="https://pypi.python.org/pypi/fastapi-singleton"><img src="https://img.shields.io/pypi/v/fastapi-singleton.svg"></a>
+        <a href="https://github.com/alxwrd/fastapi-singleton/blob/main/LICENCE"><img src="https://img.shields.io/pypi/l/fastapi-singleton.svg?"></a>
+    </div>
+
+Every dependency resolved through FastAPI's `Depends` is request-scoped:
+created on each request and discarded once the response is sent. That's the
+right default for most things, but it's the wrong default for connection
+pools, HTTP clients, and anything else that's expensive to create and safe to
+share.
+
+`fastapi-singleton` gives you a `@singleton` decorator that turns any
+dependency, function or class, into one shared instance per process, with
+proper startup and shutdown hooks wired into FastAPI's `lifespan`, instead of
+leaving it to whatever a `SIGTERM` does to a `@lru_cache`d object.
+</div>
+
+## Example
+
+```python
+from typing import Annotated
+
+from fastapi import Depends, FastAPI
+from fastapi_singleton import singleton, lifespan
+
+
+@singleton
+class Settings:
+    def __init__(self):
+        self.dsn = "postgresql://localhost/app"
+
+
+@singleton
+async def get_pool(settings: Annotated[Settings, Depends(Settings)]):
+    pool = await create_pool(settings.dsn)
+    yield pool
+    await pool.close()
+
+
+@get_pool.before_start
+def log_pool_starting():
+    logger.info("opening connection pool")
+
+
+@get_pool.after_end
+def log_pool_closed():
+    logger.info("connection pool closed")
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+@app.get("/users/{user_id}")
+def read_user(pool: Annotated[Pool, Depends(get_pool)], user_id: int):
+    return pool.fetch_user(user_id)
+```
+
+```plain
+$ uvicorn app:app
+
+INFO:     opening connection pool
+INFO:     Application startup complete.
+...
+INFO:     Shutting down
+INFO:     connection pool closed
+INFO:     Application shutdown complete.
+```
+
+## Installation
+
+```shell
+uv add fastapi-singleton
+```
+
+## Defining a singleton
+
+`@singleton` wraps a function or a class so that it's only ever called once
+per process; every dependant that resolves it via `Depends` receives the
+exact same instance, the same guarantee `@lru_cache(maxsize=1)` gives you,
+but tracked in a registry so its lifecycle can be managed instead of left to
+the garbage collector.
+
+```python
+@singleton
+def get_other():
+    return Other()
+```
+
+Singletons can depend on other singletons the same way any FastAPI
+dependency does, by declaring them with `Depends` in the constructor or
+function signature:
+
+```python
+@singleton
+class Connection:
+    def __init__(self, other: Annotated[Other, Depends(get_other)]):
+        self.other = other
+```
+
+A class singleton's `__init__` is the constructor, plain and simple -
+`Depends(Connection)` calls it exactly once, the same way any FastAPI
+class-based dependency works. `__init__` can never be `async def` in
+Python, so a class singleton can't do real async setup itself - if you need
+that (an async connection pool, an `await`-based client, anything with
+teardown), write it as a function singleton instead and have your class
+depend on it, the same way `Connection` depends on `get_other` above.
+
+A singleton can't depend on a regular, request-scoped dependency - there's
+no request to resolve it from when the singleton is constructed eagerly at
+startup, or directly in plain Python. `@singleton`-ing something that
+depends on non-singleton `Depends(...)` raises an error rather than silently
+resolving it once and reusing stale data on every later request.
+
+A singleton is also constructed exactly once: calling it again with the
+same arguments it was first constructed with is a no-op (this is what lets
+FastAPI re-resolve a singleton's own `Depends`-declared dependencies on
+every request without recreating anything), but calling it again with
+genuinely different arguments raises rather than silently ignoring them.
+
+## Teardown with generators
+
+If a singleton needs to release what it acquired, write it as a generator,
+exactly like a request-scoped `yield` dependency in FastAPI. The code before
+`yield` runs once, on creation; the code after `yield` runs once, on
+shutdown.
+
+```python
+@singleton
+def get_other():
+    other = Other()
+    yield other
+    other.close()
+```
+
+## Lifecycle hooks
+
+Sometimes the setup or teardown you need isn't part of constructing the
+resource itself, things like metrics, logging, or cache warming. Each
+singleton exposes hooks you can register without touching its body:
+
+```python
+@Connection.before_start
+def before_start():
+    ...  # runs immediately before Connection is constructed
+
+
+@get_other.before_end
+def before_end():
+    ...  # runs immediately before get_other's teardown executes
+
+
+@get_other.after_end
+def after_end():
+    ...  # runs immediately after get_other's teardown completes
+```
+
+| Hook | Runs |
+|---|---|
+| `before_start` | Immediately before the singleton is constructed |
+| `before_end` | Immediately before the singleton's teardown executes |
+| `after_end` | Immediately after the singleton's teardown completes |
+
+A singleton can register any number of hooks for each event; they run in
+registration order.
+
+## Wiring up the lifespan
+
+Singletons are created lazily by default, on first resolution, the same as
+`@lru_cache`. To get deterministic startup and shutdown instead, pass
+`fastapi_singleton.lifespan` to your `FastAPI` app:
+
+```python
+from fastapi_singleton import lifespan
+
+app = FastAPI(lifespan=lifespan)
+```
+
+On startup, every registered singleton is constructed eagerly, in dependency
+order, so a connection pool is open and ready before the app accepts its
+first request. On shutdown, each singleton is torn down in reverse order,
+running any `before_end` hooks, its own post-`yield` teardown, then any
+`after_end` hooks, like a stack of context managers being unwound.
+
+If you already have a `lifespan` of your own, compose them:
+
+```python
+from contextlib import asynccontextmanager
+
+from fastapi_singleton import lifespan as singleton_lifespan
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with singleton_lifespan(app):
+        # your own startup
+        yield
+        # your own shutdown
+
+
+app = FastAPI(lifespan=lifespan)
+```
+
+Without the lifespan wired up, singletons still work, lazily, on first call,
+like a plain `@lru_cache`, but nothing guarantees their teardown code runs;
+register the lifespan whenever a singleton's cleanup actually matters.
+
+## One process, one app
+
+Singletons live in a process-global registry, the same way `@lru_cache`d
+state does. That makes `fastapi-singleton` a fit for one `FastAPI` app per
+process; running two `FastAPI(lifespan=lifespan)` apps side by side in the
+same process means they'd share singleton state, including teardown. If
+you're testing code that uses singletons, reset the registry between tests:
+
+```python
+from fastapi_singleton import reset
+
+
+@pytest.fixture(autouse=True)
+def reset_singletons():
+    reset()
+```

fastapi_singleton-0.1.0/README.md

@@ -0,0 +1,229 @@
+<div align="center">
+    <h1><code>fastapi-singleton</code></h1>
+    <p align="center"><i>
+        Application-scoped dependencies for <code>fastapi</code>
+    </i></p>
+    <img width="256px" src=".github/assets/three-card-trickster-768.png">
+    <div align="center">
+        <a href="https://github.com/alxwrd/fastapi-singleton/actions/workflows/test.yml"><img src="https://img.shields.io/github/actions/workflow/status/alxwrd/fastapi-singleton/test.yml?branch=main&label=main"></a>
+        <a href="https://pypi.python.org/pypi/fastapi-singleton"><img src="https://img.shields.io/pypi/v/fastapi-singleton.svg"></a>
+        <a href="https://github.com/alxwrd/fastapi-singleton/blob/main/LICENCE"><img src="https://img.shields.io/pypi/l/fastapi-singleton.svg?"></a>
+    </div>
+
+Every dependency resolved through FastAPI's `Depends` is request-scoped:
+created on each request and discarded once the response is sent. That's the
+right default for most things, but it's the wrong default for connection
+pools, HTTP clients, and anything else that's expensive to create and safe to
+share.
+
+`fastapi-singleton` gives you a `@singleton` decorator that turns any
+dependency, function or class, into one shared instance per process, with
+proper startup and shutdown hooks wired into FastAPI's `lifespan`, instead of
+leaving it to whatever a `SIGTERM` does to a `@lru_cache`d object.
+</div>
+
+## Example
+
+```python
+from typing import Annotated
+
+from fastapi import Depends, FastAPI
+from fastapi_singleton import singleton, lifespan
+
+
+@singleton
+class Settings:
+    def __init__(self):
+        self.dsn = "postgresql://localhost/app"
+
+
+@singleton
+async def get_pool(settings: Annotated[Settings, Depends(Settings)]):
+    pool = await create_pool(settings.dsn)
+    yield pool
+    await pool.close()
+
+
+@get_pool.before_start
+def log_pool_starting():
+    logger.info("opening connection pool")
+
+
+@get_pool.after_end
+def log_pool_closed():
+    logger.info("connection pool closed")
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+@app.get("/users/{user_id}")
+def read_user(pool: Annotated[Pool, Depends(get_pool)], user_id: int):
+    return pool.fetch_user(user_id)
+```
+
+```plain
+$ uvicorn app:app
+
+INFO:     opening connection pool
+INFO:     Application startup complete.
+...
+INFO:     Shutting down
+INFO:     connection pool closed
+INFO:     Application shutdown complete.
+```
+
+## Installation
+
+```shell
+uv add fastapi-singleton
+```
+
+## Defining a singleton
+
+`@singleton` wraps a function or a class so that it's only ever called once
+per process; every dependant that resolves it via `Depends` receives the
+exact same instance, the same guarantee `@lru_cache(maxsize=1)` gives you,
+but tracked in a registry so its lifecycle can be managed instead of left to
+the garbage collector.
+
+```python
+@singleton
+def get_other():
+    return Other()
+```
+
+Singletons can depend on other singletons the same way any FastAPI
+dependency does, by declaring them with `Depends` in the constructor or
+function signature:
+
+```python
+@singleton
+class Connection:
+    def __init__(self, other: Annotated[Other, Depends(get_other)]):
+        self.other = other
+```
+
+A class singleton's `__init__` is the constructor, plain and simple -
+`Depends(Connection)` calls it exactly once, the same way any FastAPI
+class-based dependency works. `__init__` can never be `async def` in
+Python, so a class singleton can't do real async setup itself - if you need
+that (an async connection pool, an `await`-based client, anything with
+teardown), write it as a function singleton instead and have your class
+depend on it, the same way `Connection` depends on `get_other` above.
+
+A singleton can't depend on a regular, request-scoped dependency - there's
+no request to resolve it from when the singleton is constructed eagerly at
+startup, or directly in plain Python. `@singleton`-ing something that
+depends on non-singleton `Depends(...)` raises an error rather than silently
+resolving it once and reusing stale data on every later request.
+
+A singleton is also constructed exactly once: calling it again with the
+same arguments it was first constructed with is a no-op (this is what lets
+FastAPI re-resolve a singleton's own `Depends`-declared dependencies on
+every request without recreating anything), but calling it again with
+genuinely different arguments raises rather than silently ignoring them.
+
+## Teardown with generators
+
+If a singleton needs to release what it acquired, write it as a generator,
+exactly like a request-scoped `yield` dependency in FastAPI. The code before
+`yield` runs once, on creation; the code after `yield` runs once, on
+shutdown.
+
+```python
+@singleton
+def get_other():
+    other = Other()
+    yield other
+    other.close()
+```
+
+## Lifecycle hooks
+
+Sometimes the setup or teardown you need isn't part of constructing the
+resource itself, things like metrics, logging, or cache warming. Each
+singleton exposes hooks you can register without touching its body:
+
+```python
+@Connection.before_start
+def before_start():
+    ...  # runs immediately before Connection is constructed
+
+
+@get_other.before_end
+def before_end():
+    ...  # runs immediately before get_other's teardown executes
+
+
+@get_other.after_end
+def after_end():
+    ...  # runs immediately after get_other's teardown completes
+```
+
+| Hook | Runs |
+|---|---|
+| `before_start` | Immediately before the singleton is constructed |
+| `before_end` | Immediately before the singleton's teardown executes |
+| `after_end` | Immediately after the singleton's teardown completes |
+
+A singleton can register any number of hooks for each event; they run in
+registration order.
+
+## Wiring up the lifespan
+
+Singletons are created lazily by default, on first resolution, the same as
+`@lru_cache`. To get deterministic startup and shutdown instead, pass
+`fastapi_singleton.lifespan` to your `FastAPI` app:
+
+```python
+from fastapi_singleton import lifespan
+
+app = FastAPI(lifespan=lifespan)
+```
+
+On startup, every registered singleton is constructed eagerly, in dependency
+order, so a connection pool is open and ready before the app accepts its
+first request. On shutdown, each singleton is torn down in reverse order,
+running any `before_end` hooks, its own post-`yield` teardown, then any
+`after_end` hooks, like a stack of context managers being unwound.
+
+If you already have a `lifespan` of your own, compose them:
+
+```python
+from contextlib import asynccontextmanager
+
+from fastapi_singleton import lifespan as singleton_lifespan
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with singleton_lifespan(app):
+        # your own startup
+        yield
+        # your own shutdown
+
+
+app = FastAPI(lifespan=lifespan)
+```
+
+Without the lifespan wired up, singletons still work, lazily, on first call,
+like a plain `@lru_cache`, but nothing guarantees their teardown code runs;
+register the lifespan whenever a singleton's cleanup actually matters.
+
+## One process, one app
+
+Singletons live in a process-global registry, the same way `@lru_cache`d
+state does. That makes `fastapi-singleton` a fit for one `FastAPI` app per
+process; running two `FastAPI(lifespan=lifespan)` apps side by side in the
+same process means they'd share singleton state, including teardown. If
+you're testing code that uses singletons, reset the registry between tests:
+
+```python
+from fastapi_singleton import reset
+
+
+@pytest.fixture(autouse=True)
+def reset_singletons():
+    reset()
+```

fastapi_singleton-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "fastapi-singleton"
+version = "0.1.0"
+description = "Application-scoped dependencies for FastAPI"
+license = "MIT"
+readme = "README.md"
+authors = [
+    { name = "Alex Ward", email = "alxwrd@googlemail.com" }
+]
+classifiers = [
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3 :: Only",
+  "Framework :: FastAPI",
+]
+requires-python = ">=3.13"
+dependencies = [
+    "fastapi>=0.115",
+]
+
+[project.urls]
+Repository = "https://github.com/alxwrd/fastapi-singleton"
+Releases = "https://github.com/alxwrd/fastapi-singleton/releases"
+
+[build-system]
+requires = ["uv_build>=0.10.0,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "poethepoet>=0.42.1",
+    "ruff>=0.15.18",
+    "ty>=0.0.51",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "httpx>=0.27",
+    "uvicorn>=0.30",
+]
+
+[tool.poe.tasks]
+_format = "ruff format"
+_sort = "ruff check --select I --fix"
+format = ["_format", "_sort"]
+lint = "ruff check"
+check = "ty check"
+test = "pytest"
+all = ["format", "lint", "check", "test"]
+_check-format = "ruff format --check"
+_check-sort = "ruff check --select I"
+ci = ["_check-format", "_check-sort", "lint", "check", "test"]
+
+[tool.poe.tasks.example]
+cmd = "uvicorn example.main:app --reload"
+help = "Run the example app from README.md's ConnectionPool walkthrough"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

fastapi_singleton-0.1.0/src/fastapi_singleton/__init__.py

@@ -0,0 +1,29 @@
+"""Application-scoped dependencies for FastAPI.
+
+See README.md for the full guide. Public API:
+
+    from fastapi_singleton import singleton, lifespan
+"""
+
+import inspect
+from typing import Any
+
+from ._class import make_class_singleton
+from ._function import make_function_singleton
+from ._lifespan import lifespan
+from ._registry import reset
+from ._signature import UsageError
+
+
+def singleton(obj: Any) -> Any:
+    if inspect.isclass(obj):
+        return make_class_singleton(obj)
+    return make_function_singleton(obj)
+
+
+__all__ = [
+    "singleton",
+    "lifespan",
+    "reset",
+    "UsageError",
+]

fastapi_singleton-0.1.0/src/fastapi_singleton/_class.py

@@ -0,0 +1,105 @@
+"""@singleton for classes.
+
+Classes are always a sync, `__init__`-only "value singleton": `__init__`
+can never be `async def` in Python, so there's no mechanism by which a
+class-based dependency could do real async resource setup (`await
+asyncpg.create_pool(...)` and friends) - FastAPI itself never awaits a
+class's constructor either, for the same reason. If a singleton needs async
+construction or generator-based teardown, write it as a function (see
+_function.py); a class singleton can still depend on one via `Depends` in
+its `__init__` the same way any other dependency does.
+
+Because `@singleton class Foo` only ever constructs via `__init__`, calling
+it is exactly "call the constructor" - the same mental model as a plain
+FastAPI class-based dependency (`Depends(Foo)`), just memoized.
+"""
+
+import inspect
+import threading
+import time
+from collections.abc import Callable
+from typing import Any
+
+from . import _hooks, _registry, _signature
+
+_UNSET = object()
+
+
+class _ClassSingleton:
+    def __init__(self, cls: type) -> None:
+        self._cls = cls
+        self._hooks = _hooks.HookRegistry()
+        self.__name__ = cls.__name__
+        self.__doc__ = cls.__doc__
+        self.__module__ = cls.__module__
+        init_signature = inspect.signature(cls.__init__)
+        params = [p for name, p in init_signature.parameters.items() if name != "self"]
+        self.__signature__ = init_signature.replace(parameters=params)
+        setattr(self, _registry.MARKER, True)
+        self._created: float | None = None
+        self._torn_down = False
+        self._value: Any = _UNSET
+        self._construction_args: tuple[Any, ...] = ()
+        self._construction_kwargs: dict[str, Any] = {}
+        self._lock = threading.Lock()
+
+    def _existing(self, args: tuple[Any, ...], kwargs: dict[str, Any]) -> Any:
+        if not self._created:
+            return _UNSET
+        _signature.check_no_conflict(
+            repr(self),
+            (self._construction_args, self._construction_kwargs),
+            (args, kwargs),
+        )
+        return self._value
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        existing = self._existing(args, kwargs)
+        if existing is not _UNSET:
+            return existing
+        with _signature.guard_against_cycles(self):
+            with self._lock:
+                existing = self._existing(args, kwargs)
+                if existing is not _UNSET:
+                    return existing
+                if not args and not kwargs:
+                    kwargs = _signature.self_resolve_kwargs(self._cls.__init__)
+                _hooks.run_sync(self._hooks.before_start)
+                self._value = self._cls(*args, **kwargs)
+                self._created = time.time()
+                self._construction_args = args
+                self._construction_kwargs = kwargs
+                return self._value
+
+    def teardown(self) -> None:
+        if not self._created or self._torn_down:
+            return
+        self._torn_down = True
+        _hooks.run_sync(self._hooks.before_end)
+        _hooks.run_sync(self._hooks.after_end)
+
+    def before_start(self, hook: Callable[[], Any]) -> Callable[[], Any]:
+        self._hooks.before_start.append(hook)
+        return hook
+
+    def before_end(self, hook: Callable[[], Any]) -> Callable[[], Any]:
+        self._hooks.before_end.append(hook)
+        return hook
+
+    def after_end(self, hook: Callable[[], Any]) -> Callable[[], Any]:
+        self._hooks.after_end.append(hook)
+        return hook
+
+    def _reset(self) -> None:
+        self._created = None
+        self._torn_down = False
+        self._value = _UNSET
+        self._construction_args = ()
+        self._construction_kwargs = {}
+        self._lock = threading.Lock()
+
+
+def make_class_singleton(cls: type) -> _ClassSingleton:
+    instance = _ClassSingleton(cls)
+    _registry.register(instance)
+    return instance

fastapi_singleton-0.1.0/src/fastapi_singleton/_function.py

@@ -0,0 +1,163 @@
+"""@singleton for plain functions.
+
+A sync and an async wrapper class exist separately, rather than one wrapper
+that internally awaits, because FastAPI decides how to invoke a dependency
+(directly await it, or run it in a threadpool) based on whether the
+callable itself is `async def` - so the wrapper's own sync/async-ness must
+match the underlying provider's, not just delegate to it.
+
+Deliberately does NOT use functools.wraps/update_wrapper on the raw
+provider: that would set __wrapped__, and FastAPI's own generator detection
+(fastapi.dependencies.models.Dependant.is_gen_callable) calls
+inspect.unwrap() on whatever it's given, which would find the original
+generator/async-generator function and misclassify our cached-value wrapper
+as a live per-request resource. Identity (__name__/__doc__/__signature__) is
+copied by hand instead.
+"""
+
+import asyncio
+import inspect
+import threading
+import time
+from collections.abc import Callable
+from typing import Any, Generic, TypeVar
+
+from . import _hooks, _registry, _signature
+from ._provider import Provider
+
+_UNSET = object()
+
+_LockT = TypeVar("_LockT", threading.Lock, asyncio.Lock)
+
+
+class _BaseFunctionSingleton(Generic[_LockT]):
+    LOCK_METHOD: type[_LockT]
+    _lock: _LockT
+
+    def __init__(self, fn: Callable[..., Any], provider: Provider) -> None:
+        self._fn = fn
+        self._reset()
+        self._construction_kwargs: dict[str, Any] = {}
+        self._hooks = _hooks.HookRegistry()
+        self.__name__ = getattr(fn, "__name__", "singleton")
+        self.__doc__ = fn.__doc__
+        self.__module__ = fn.__module__
+        self.__signature__ = inspect.signature(fn)
+        setattr(self, _registry.MARKER, True)
+
+    def before_start(self, hook: Callable[[], Any]) -> Callable[[], Any]:
+        self._hooks.before_start.append(hook)
+        return hook
+
+    def before_end(self, hook: Callable[[], Any]) -> Callable[[], Any]:
+        self._hooks.before_end.append(hook)
+        return hook
+
+    def after_end(self, hook: Callable[[], Any]) -> Callable[[], Any]:
+        self._hooks.after_end.append(hook)
+        return hook
+
+    def _reset(self) -> None:
+        self._provider = Provider(self._fn)
+        self._created = None
+        self._torn_down = False
+        self._before_end_done = False
+        self._value = _UNSET
+        self._construction_kwargs = {}
+        self._lock = self.LOCK_METHOD()
+
+    def _existing(self, kwargs: dict[str, Any]) -> Any:
+        """Returns the cached value if already created, else _UNSET.
+
+        Shared between the sync and async fast-path/locked-path checks,
+        which are otherwise identical aside from await placement.
+        """
+        if self._torn_down:
+            raise _signature.UsageError(
+                f"{self!r} was already torn down and cannot be called again."
+            )
+        if not self._created:
+            return _UNSET
+        _signature.check_no_conflict(
+            repr(self), ((), self._construction_kwargs), ((), kwargs)
+        )
+        return self._value
+
+    def _commit(self, value: Any, kwargs: dict[str, Any]) -> Any:
+        self._value = value
+        self._created = time.time()
+        self._construction_kwargs = kwargs
+        return value
+
+    def _should_teardown(self) -> bool:
+        return bool(self._created) and not self._torn_down
+
+
+class SyncFunctionSingleton(_BaseFunctionSingleton[threading.Lock]):
+    LOCK_METHOD = threading.Lock
+
+    def __call__(self, **kwargs: Any) -> Any:
+        existing = self._existing(kwargs)
+        if existing is not _UNSET:
+            return existing
+        with _signature.guard_against_cycles(self):
+            with self._lock:
+                existing = self._existing(kwargs)
+                if existing is not _UNSET:
+                    return existing
+                if not kwargs:
+                    kwargs = _signature.self_resolve_kwargs(self._fn)
+                _hooks.run_sync(self._hooks.before_start)
+                value = self._provider.create(**kwargs)
+                return self._commit(value, kwargs)
+
+    def teardown(self) -> None:
+        if not self._should_teardown():
+            return
+        if not self._before_end_done:
+            self._before_end_done = True
+            _hooks.run_sync(self._hooks.before_end)
+        self._provider.teardown()
+        _hooks.run_sync(self._hooks.after_end)
+        self._torn_down = True
+
+
+class AsyncFunctionSingleton(_BaseFunctionSingleton[asyncio.Lock]):
+    LOCK_METHOD = asyncio.Lock
+
+    async def __call__(self, **kwargs: Any) -> Any:
+        existing = self._existing(kwargs)
+        if existing is not _UNSET:
+            return existing
+        with _signature.guard_against_cycles(self):
+            async with self._lock:
+                existing = self._existing(kwargs)
+                if existing is not _UNSET:
+                    return existing
+                if not kwargs:
+                    kwargs = await _signature.async_self_resolve_kwargs(self._fn)
+                await _hooks.run_async(self._hooks.before_start)
+                value = await self._provider.create(**kwargs)
+                return self._commit(value, kwargs)
+
+    async def teardown(self) -> None:
+        if not self._should_teardown():
+            return
+        if not self._before_end_done:
+            self._before_end_done = True
+            await _hooks.run_async(self._hooks.before_end)
+        result = self._provider.teardown()
+        if inspect.isawaitable(result):
+            await result
+        await _hooks.run_async(self._hooks.after_end)
+        self._torn_down = True
+
+
+def make_function_singleton(
+    fn: Callable[..., Any],
+) -> SyncFunctionSingleton | AsyncFunctionSingleton:
+    provider = Provider(fn)
+    cls = AsyncFunctionSingleton if provider.is_async else SyncFunctionSingleton
+    instance = cls(fn, provider)
+    _registry.register(instance)
+    return instance

fastapi_singleton-0.1.0/src/fastapi_singleton/_hooks.py

@@ -0,0 +1,43 @@
+"""before_start/before_end/after_end lifecycle hooks.
+
+Hooks run in registration order. A hook may be sync or async, but firing an
+async hook requires an await-capable path (an async provider, or the
+lifespan context manager) - firing one from a purely sync path raises a
+clear error rather than silently dropping it or blocking on the coroutine.
+"""
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+
+class AsyncHookError(RuntimeError):
+    """Raised when an async hook fires on a purely sync lifecycle path."""
+
+
+class HookRegistry:
+    def __init__(self) -> None:
+        self.before_start: list[Callable[[], Any]] = []
+        self.before_end: list[Callable[[], Any]] = []
+        self.after_end: list[Callable[[], Any]] = []
+
+
+def run_sync(hooks: list[Callable[[], Any]]) -> None:
+    for hook in hooks:
+        result = hook()
+        if inspect.isawaitable(result):
+            close = getattr(result, "close", None)
+            if close is not None:
+                close()
+            raise AsyncHookError(
+                f"{hook!r} is an async hook but fired on a sync singleton "
+                "lifecycle path. Use fastapi_singleton.lifespan, or make "
+                "the singleton's provider async, to run async hooks."
+            )
+
+
+async def run_async(hooks: list[Callable[[], Any]]) -> None:
+    for hook in hooks:
+        result = hook()
+        if inspect.isawaitable(result):
+            await result

fastapi_singleton-0.1.0/src/fastapi_singleton/_lifespan.py

@@ -0,0 +1,46 @@
+"""The `lifespan` async context manager: eager startup, reverse-order
+teardown.
+
+No explicit topological sort is needed: calling every registered singleton
+once is enough, because self-resolution (see _signature.py) recursively
+constructs a singleton's own dependencies before it finishes constructing
+itself. Each singleton's `_created` timestamp is therefore set in a valid
+dependency order (deps before dependents) for free, and sorting by it -
+see registry.creation_order() - then reversing is a valid teardown order,
+exactly like unwinding a stack of context managers.
+"""
+
+import inspect
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+from . import _registry
+
+
+async def _teardown_all() -> None:
+    for singleton in reversed(_registry.creation_order()):
+        result = singleton.teardown()
+        if inspect.isawaitable(result):
+            await result
+
+
+@asynccontextmanager
+async def lifespan(app: Any) -> AsyncIterator[None]:
+    try:
+        for singleton in _registry.all_singletons():
+            if singleton._created:
+                continue
+            result = singleton()
+            if inspect.isawaitable(result):
+                await result
+    except BaseException:
+        # A later singleton failing to construct must not leak whatever
+        # earlier singletons already acquired - tear down everything that
+        # did get created before re-raising.
+        await _teardown_all()
+        raise
+    try:
+        yield
+    finally:
+        await _teardown_all()

fastapi_singleton-0.1.0/src/fastapi_singleton/_provider.py

@@ -0,0 +1,72 @@
+"""Normalizes the four sync/async x plain/generator dependency shapes that
+FastAPI itself supports into a single create-once/teardown-once interface.
+
+Detection runs on the raw function the user wrote, never on a wrapper we
+hand to FastAPI - see _function.py and _class.py for why that distinction
+matters.
+"""
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+_UNSET = object()
+
+
+class MultipleYieldError(RuntimeError):
+    """Raised when a generator-based provider yields more than once."""
+
+
+class Provider:
+    """Drives a single sync/async, plain/generator callable exactly once."""
+
+    def __init__(self, fn: Callable[..., Any]) -> None:
+        self._fn = fn
+        self._is_gen = inspect.isgeneratorfunction(fn)
+        self._is_async_gen = inspect.isasyncgenfunction(fn)
+        self._is_coroutine = inspect.iscoroutinefunction(fn)
+        self.is_async = self._is_async_gen or self._is_coroutine
+        self._generator: Any = _UNSET
+
+    def create(self, **kwargs: Any) -> Any:
+        if self._is_async_gen:
+            return self._acreate(**kwargs)
+        if self._is_coroutine:
+            return self._fn(**kwargs)
+        if self._is_gen:
+            generator = self._fn(**kwargs)
+            value = next(generator)
+            self._generator = generator
+            return value
+        return self._fn(**kwargs)
+
+    async def _acreate(self, **kwargs: Any) -> Any:
+        generator = self._fn(**kwargs)
+        value = await anext(generator)
+        self._generator = generator
+        return value
+
+    def teardown(self) -> Any:
+        if self._generator is _UNSET:
+            return None
+        if self._is_async_gen:
+            return self._ateardown()
+        generator = self._generator
+        sentinel = _UNSET
+        result = next(generator, sentinel)
+        if result is not sentinel:
+            raise MultipleYieldError(
+                f"{self._fn!r} yielded more than once; "
+                "singleton providers must yield exactly once"
+            )
+        return None
+
+    async def _ateardown(self) -> None:
+        generator = self._generator
+        sentinel = _UNSET
+        result = await anext(generator, sentinel)
+        if result is not sentinel:
+            raise MultipleYieldError(
+                f"{self._fn!r} yielded more than once; "
+                "singleton providers must yield exactly once"
+            )

fastapi_singleton-0.1.0/src/fastapi_singleton/_registry.py

@@ -0,0 +1,53 @@
+"""Process-global registry of every @singleton-wrapped object.
+
+This package is single-FastAPI-app-per-process by design: singleton state
+lives at module scope, the same way @lru_cache(maxsize=1) does. reset() is
+provided for tests, where leaking state across test functions would
+otherwise be a footgun.
+"""
+
+from typing import Any, Protocol, runtime_checkable
+
+#: marker attribute used by is_singleton() to recognize anything @singleton
+#: produces, including objects (like _InstanceProxy) that don't themselves
+#: own a create/teardown lifecycle but stand in for one.
+MARKER = "__fastapi_singleton__"
+
+
+@runtime_checkable
+class _Lifecycle(Protocol):
+    #: unix timestamp set when the singleton is created, None until then.
+    #: Doubles as the creation-order sort key, so no separate list of
+    #: created singletons needs to be maintained.
+    _created: float | None
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any: ...
+    def teardown(self) -> Any: ...
+    def _reset(self) -> None: ...
+
+
+_singletons: list[_Lifecycle] = []
+
+
+def register(singleton: _Lifecycle) -> None:
+    _singletons.append(singleton)
+
+
+def all_singletons() -> tuple[_Lifecycle, ...]:
+    return tuple(_singletons)
+
+
+def creation_order() -> tuple[_Lifecycle, ...]:
+    created = [s for s in _singletons if s._created is not None]
+    created.sort(key=lambda s: s._created)
+    return tuple(created)
+
+
+def is_singleton(obj: Any) -> bool:
+    return getattr(obj, MARKER, False) is True
+
+
+def reset() -> None:
+    for singleton in _singletons:
+        singleton._reset()
+    _singletons.clear()

fastapi_singleton-0.1.0/src/fastapi_singleton/_signature.py

@@ -0,0 +1,167 @@
+"""Depends()-aware signature introspection and self-resolution.
+
+Mirrors fastapi.dependencies.utils.analyze_param's two ways of finding a
+Depends() marker on a parameter (bare default, or Annotated[...] metadata),
+so @singleton-decorated callables can be resolved both by FastAPI itself
+(during a real request) and by our own code (direct calls in plain Python,
+and the eager lifespan startup walk).
+"""
+
+import contextlib
+import contextvars
+import inspect
+import math
+import typing
+from collections.abc import Callable, Iterator
+from typing import Any
+
+from fastapi.params import Depends
+
+from . import _registry
+
+
+class UsageError(RuntimeError):
+    """Raised when a singleton's dependency graph can't be resolved."""
+
+
+#: ids of singletons currently under construction on this thread/task, used
+#: to detect a singleton depending on itself, directly or transitively.
+#: contextvars rather than a plain set: each thread gets its own context by
+#: default, and the value propagates correctly across awaits within a single
+#: asyncio task, so concurrent unrelated constructions never collide.
+_constructing: contextvars.ContextVar[frozenset[int]] = contextvars.ContextVar(
+    "_constructing", default=frozenset()
+)
+
+
+@contextlib.contextmanager
+def guard_against_cycles(singleton: Any) -> Iterator[None]:
+    """Raises UsageError if `singleton` is already being constructed further
+    up the current call stack, instead of letting construction proceed into
+    a re-acquire of its own non-reentrant lock, which would deadlock rather
+    than fail."""
+    current = _constructing.get()
+    key = id(singleton)
+    if key in current:
+        raise UsageError(
+            f"{singleton!r} depends on itself, directly or transitively. "
+            "A singleton's dependency graph must be acyclic."
+        )
+    token = _constructing.set(current | {key})
+    try:
+        yield
+    finally:
+        _constructing.reset(token)
+
+
+def _values_equal(a: Any, b: Any) -> bool:
+    """Like `==`, but treats two NaN floats as equal to each other.
+
+    Plain `==` follows IEEE 754, where NaN is never equal to anything,
+    including another NaN - so a repeat call with a semantically-unchanged
+    NaN-valued argument would otherwise look like a conflicting argument."""
+    if (
+        isinstance(a, float)
+        and isinstance(b, float)
+        and math.isnan(a)
+        and math.isnan(b)
+    ):
+        return True
+    if isinstance(a, dict) and isinstance(b, dict):
+        return a.keys() == b.keys() and all(_values_equal(a[key], b[key]) for key in a)
+    if (
+        isinstance(a, (list, tuple))
+        and isinstance(b, (list, tuple))
+        and len(a) == len(b)
+    ):
+        return all(_values_equal(x, y) for x, y in zip(a, b))
+    return a == b
+
+
+def check_no_conflict(
+    name: str,
+    original: tuple[tuple[Any, ...], dict[str, Any]],
+    attempted: tuple[tuple[Any, ...], dict[str, Any]],
+) -> None:
+    """A singleton is constructed once; calling it again with the same
+    resolved args (e.g. FastAPI re-passing an already-cached nested
+    singleton dependency on every request) is a no-op, but calling it again
+    with genuinely different args is almost certainly a bug, not something
+    to silently ignore."""
+    attempted_args, attempted_kwargs = attempted
+    if not attempted_args and not attempted_kwargs:
+        return
+    if _values_equal(attempted, original):
+        return
+    raise UsageError(
+        f"{name} was already constructed with {original!r}; called again "
+        f"with different arguments {attempted!r}. A singleton is "
+        "constructed exactly once - if you need different configurations, "
+        "use separate singletons."
+    )
+
+
+def depends_params(fn: Callable[..., Any]) -> dict[str, Callable[..., Any]]:
+    signature = inspect.signature(fn)
+    try:
+        hints = typing.get_type_hints(fn, include_extras=True)
+    except NameError:
+        hints = {}
+    found: dict[str, Callable[..., Any]] = {}
+    for name, param in signature.parameters.items():
+        if name == "self":
+            continue
+        depends = None
+        if isinstance(param.default, Depends):
+            depends = param.default
+        else:
+            annotation = hints.get(name, param.annotation)
+            if typing.get_origin(annotation) is typing.Annotated:
+                for meta in typing.get_args(annotation)[1:]:
+                    if isinstance(meta, Depends):
+                        depends = meta
+        if depends is None:
+            continue
+        target = depends.dependency
+        if target is None:
+            target = hints.get(name, param.annotation)
+        found[name] = target
+    return found
+
+
+def _check_target(fn: Callable[..., Any], target: Callable[..., Any]) -> None:
+    if not _registry.is_singleton(target):
+        raise UsageError(
+            f"{fn!r} depends on {target!r} via Depends(), but {target!r} "
+            "is not @singleton-wrapped. Singletons can only depend on "
+            "other singletons, never on request-scoped data."
+        )
+
+
+def self_resolve_kwargs(fn: Callable[..., Any]) -> dict[str, Any]:
+    """Sync resolution: raises if a dependency turns out to be async."""
+    kwargs: dict[str, Any] = {}
+    for name, target in depends_params(fn).items():
+        _check_target(fn, target)
+        result = target()
+        if inspect.isawaitable(result):
+            result.close()
+            raise UsageError(
+                f"{fn!r} depends on {target!r}, which is async. Resolve it "
+                "from an async context instead - make this singleton's own "
+                "provider `async def`, or rely on fastapi_singleton.lifespan "
+                "for eager startup, rather than calling it directly."
+            )
+        kwargs[name] = result
+    return kwargs
+
+
+async def async_self_resolve_kwargs(fn: Callable[..., Any]) -> dict[str, Any]:
+    kwargs: dict[str, Any] = {}
+    for name, target in depends_params(fn).items():
+        _check_target(fn, target)
+        result = target()
+        if inspect.isawaitable(result):
+            result = await result
+        kwargs[name] = result
+    return kwargs