blakemere-wraptools 0.1.0__py3-none-any.whl

blakemere_wraptools-0.1.0.dist-info/METADATA

@@ -0,0 +1,355 @@
+Metadata-Version: 2.4
+Name: blakemere-wraptools
+Version: 0.1.0
+Summary: A focused library of useful Python decorators for reliability, caching, rate limiting, timeouts, and developer ergonomics.
+Project-URL: Homepage, https://github.com/RusDavies/pydecorators
+Project-URL: Repository, https://github.com/RusDavies/pydecorators
+Project-URL: Issues, https://github.com/RusDavies/pydecorators/issues
+Author: Russ Davies
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cache,decorators,python,rate-limit,retry,timeout
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.14; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Provides-Extra: redis
+Requires-Dist: redis>=5; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# PyDecorators
+
+A focused Python library of useful decorators for everyday reliability, caching, rate limiting, timeouts, and developer ergonomics.
+
+The goal is to provide small, typed, well-tested decorators that work in scripts, CLIs, services, and libraries without requiring a framework or a dependency shrubbery.
+
+## Planned first release
+
+The initial `v0.1.0` scope is:
+
+- `@deprecated` — implemented
+- `@cache_result` — sync/disk backend implemented
+- `@retry` — implemented
+- `@rate_limit` — implemented
+- `@timeout` — async implementation complete
+- `@log_calls` — implemented
+- `@measure_time` — implemented
+- `@validate_types` — implemented
+- `@require_env` — implemented
+- `@circuit_breaker` — implemented
+
+
+## Installation
+
+Not published yet. For local development:
+
+```bash
+python -m pip install -e '.[dev]'
+```
+
+For a built local wheel:
+
+```bash
+python -m build
+python -m pip install dist/blakemere_wraptools-0.1.0-py3-none-any.whl
+```
+
+## Quick start
+
+Pick the smallest decorator that solves the immediate problem:
+
+```python
+from pydecorators import retry
+
+
+@retry(attempts=3, delay=0.25, backoff=2, exceptions=(ConnectionError, TimeoutError))
+def call_service() -> str:
+    return "ok"
+```
+
+Then read the per-decorator docs and `docs/composition.md` before stacking decorators together. Decorator soup is still soup, even when typed.
+
+## Development status
+
+Pre-alpha. The project foundation exists and the first wave of decorators is implemented, including `@deprecated`, `@cache_result`, `@retry`, `@rate_limit`, async `@timeout`, `@log_calls`, `@measure_time`, `@validate_types`, `@require_env`, and `@circuit_breaker`.
+
+Warnings use `DeprecationWarning` by default, which Python may hide depending on warning filters. See `docs/deprecated.md` for details.
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev]'
+ruff check .
+ruff format --check .
+mypy
+python scripts/smoke_imports.py
+python scripts/smoke_examples.py
+pytest
+python -m build
+python scripts/smoke_wheel_install.py
+python scripts/dogfood_local_wheel.py
+python scripts/dogfood_external_project.py
+```
+
+`pytest` enforces coverage for `pydecorators` with terminal and XML coverage reports.
+
+Optional local pre-commit hooks are available:
+
+```bash
+pre-commit install
+pre-commit run --all-files
+```
+
+## Dogfooding before release
+
+Publishing is intentionally paused while the package is dogfooded locally. See `DOGFOOD.md` and run:
+
+```bash
+python scripts/dogfood_local_wheel.py
+python scripts/dogfood_external_project.py
+```
+
+## Documentation
+
+Start with `docs/index.md`, then use the focused pages when you need specifics:
+
+- `docs/PUBLIC_API.md` — public API and compatibility policy
+- `docs/API_DESIGN.md` — broader API design notes
+- `docs/API_REFERENCE.md` — compact public API reference
+- `docs/composition.md` — decorator stacking guidance
+- `docs/exceptions.md` — public exception behavior
+- `docs/security_hardening.md` — cache/logging/validation safety guidance
+- `CONTRIBUTING.md` — new-decorator and documentation-maintenance checklist
+
+Executable documentation examples live under `docs/examples/`.
+
+## Release process
+
+See `RELEASE.md` for the release checklist.
+
+## Decorator design docs
+
+See `docs/cache_result.md` for the cache decorator design, `docs/retry.md` for retry behavior, `docs/rate_limit.md` for rate limiting, `docs/timeout.md` for async timeout behavior, `docs/log_calls.md` for call logging, `docs/measure_time.md` for timing hooks, `docs/validate_types.md` for lightweight runtime type validation, `docs/require_env.md` for environment checks, `docs/circuit_breaker.md` for circuit-breaker behavior, `docs/composition.md` for stacking guidance, and `docs/API_REFERENCE.md` for a compact API reference.
+
+## Decorator overview
+
+- `@deprecated`: warn when old APIs are used.
+- `@cache_result`: cache expensive sync results in memory or trusted local disk storage.
+- `@retry`: retry transient failures with explicit policy.
+- `@rate_limit`: enforce in-process sliding-window call limits.
+- `@timeout`: apply async deadlines using `asyncio.wait_for`.
+- `@log_calls`: log calls, durations, exceptions, and optional summaries.
+- `@measure_time`: emit timing data to callbacks, loggers, or metrics hooks.
+- `@validate_types`: shallow runtime checks for simple annotations.
+- `@require_env`: check environment requirements at call time.
+- `@circuit_breaker`: stop hammering a failing dependency until a reset window opens.
+
+## Security and operational notes
+
+See `docs/security_hardening.md` for the centralized hardening checklist.
+
+- Treat `DiskCacheBackend` files as trusted local data. The default pickle serializer must not load untrusted cache databases.
+- Do not put disk cache files in world-writable directories.
+- Keep cache values disposable; use namespaces or clear caches when semantics change.
+- Argument/result logging is opt-in because logs preserve secrets with the enthusiasm of a museum curator.
+- `@validate_types` is not a schema validator or security boundary.
+- `@rate_limit` and `@circuit_breaker` are in-process only; they do not coordinate across workers, containers, or hosts.
+- Environment checks protect configuration mistakes, not secret storage. Use proper secret-management systems for real secrets.
+
+## Async support notes
+
+- `@deprecated`, `@retry`, `@rate_limit`, `@timeout`, `@log_calls`, `@measure_time`, `@validate_types`, `@require_env`, and `@circuit_breaker` support async callables.
+- `@cache_result` is sync-only for now.
+- `@timeout` is deliberately async-only. Sync timeout strategies based on signals or worker threads have sharp edges, so sync functions currently raise `ConfigurationError` instead of pretending the problem is easy.
+
+### Deprecated example
+
+```python
+from pydecorators import deprecated
+
+
+@deprecated("Kept for compatibility.", replacement="new_function", version="0.1.0")
+def old_function() -> str:
+    return "still works"
+```
+
+### Retry example
+
+```python
+from pydecorators import retry
+
+
+@retry(attempts=3, delay=0.25, backoff=2, exceptions=ConnectionError)
+def call_service() -> str:
+    return "ok"
+```
+
+`@retry` supports sync and async functions, exception filtering, predicate-based retry decisions, attempt hooks, jitter, max-delay caps, and injectable sleep functions for fast tests.
+
+### Rate-limit example
+
+```python
+from pydecorators import rate_limit
+
+
+@rate_limit(calls=10, period=60, key=lambda user_id: user_id)
+def call_user_api(user_id: str) -> str:
+    return "ok"
+```
+
+`@rate_limit` uses an in-process sliding window and supports global or keyed buckets, raise or block mode, async functions, and injectable clocks/sleep functions for tests.
+
+### Timeout example
+
+```python
+from pydecorators import timeout
+
+
+@timeout(seconds=2)
+async def fetch_user(user_id: str) -> str:
+    return user_id
+```
+
+`@timeout` currently supports async functions using `asyncio.wait_for`. Sync functions are rejected deliberately until a safe, well-documented sync timeout strategy exists.
+
+### Logging example
+
+```python
+from pydecorators import log_calls
+
+
+@log_calls(include_args=True, redact_args={"password"})
+def authenticate(*, username: str, password: str) -> bool:
+    return bool(username and password)
+```
+
+`@log_calls` logs start/finish duration and exceptions by default. Argument and result logging are opt-in; use redaction and summaries carefully because logs are where secrets go to become immortal.
+
+### Timing example
+
+```python
+from pydecorators import TimingInfo, measure_time
+
+
+timings: list[TimingInfo] = []
+
+
+@measure_time(callback=timings.append)
+def rebuild_index() -> None:
+    pass
+```
+
+`@measure_time` records sync and async durations through optional callback, logger, or metrics hooks.
+
+### Type-validation example
+
+```python
+from pydecorators import validate_types
+
+
+@validate_types(validate_return=True)
+def double(value: int) -> int:
+    return value * 2
+```
+
+`@validate_types` provides lightweight, shallow runtime checks for simple annotations. It is not a full schema validator; sometimes the boring warning label is the difference between a tool and a liability.
+
+### Environment requirement example
+
+```python
+from pydecorators import require_env
+
+
+@require_env("API_TOKEN")
+def call_service() -> str:
+    return "ok"
+```
+
+`@require_env` checks variables at call time, so tests and deployment systems can patch environment state after import.
+
+### Circuit-breaker example
+
+```python
+from pydecorators import CircuitBreakerOpen, circuit_breaker
+
+
+@circuit_breaker(failure_threshold=2, reset_timeout=10)
+def call_vendor_api() -> str:
+    return "ok"
+
+
+try:
+    call_vendor_api()
+except CircuitBreakerOpen:
+    pass
+```
+
+`@circuit_breaker` is an in-process breaker with closed, open, and half-open states. Useful, not magic. Architecture remains annoyingly undefeated.
+
+### Cache example
+
+```python
+from pydecorators import cache_result
+
+
+@cache_result(maxsize=128)
+def expensive_lookup(value: str) -> str:
+    return value.upper()
+```
+
+`@cache_result` uses `MemoryCacheBackend` by default and also includes `DiskCacheBackend` for trusted local persistent caches. Future backend work is planned for Redis storage.
+
+Shared cache backends can be isolated with `namespace=` when multiple decorated functions use the same backend. For persistent disk caches, treat namespace names and custom key functions as part of the cache file's compatibility contract: changing either one can strand old entries, collide with another decorated function, or return values computed under older semantics. Use explicit namespaces for long-lived caches, keep custom key functions stable across releases, and clear or rotate the cache when function behavior, argument meaning, serializer format, or namespace strategy changes.
+
+TTL is fixed from write time by default; pass `refresh_ttl_on_hit=True` to `@cache_result` or a backend when hot entries should use sliding expiry. Fixed TTL is better for predictable freshness and retention: an entry expires at a known time even if it is popular. Sliding TTL is better for expensive hot data that may stay cached while traffic continues, but it can keep stale or sensitive values alive indefinitely unless you also bound cache size, choose conservative TTLs, and clear caches when semantics change. Pass `coalesce_misses=True` to `@cache_result` when duplicate concurrent misses for the same key should share one in-flight computation.
+
+A simple cache-versioning recipe is to include an application-controlled version in the namespace, such as `namespace="users:v1"`, and bump it to `users:v2` when cached value shape, authorization assumptions, serializer behavior, or key semantics change. That intentionally abandons old rows without needing to parse or migrate them. For larger applications, keep the version string near the code that defines the cached value contract, not buried in a random decorator where future-you will absolutely forget it.
+
+For a trusted local persistent cache, create one `DiskCacheBackend`, pass it to `@cache_result`, and close it when your script or service shuts down:
+
+```python
+from pathlib import Path
+
+from pydecorators import DiskCacheBackend, cache_namespace, cache_result
+
+backend = DiskCacheBackend(
+    Path(".cache/pydecorators.sqlite3"),
+    ttl=3600,
+    maxsize=10_000,
+)
+
+
+@cache_result(backend=backend, namespace=cache_namespace("users", 1))
+def load_user_display_name(user_id: str) -> str:
+    return fetch_user_display_name(user_id)
+
+
+try:
+    print(load_user_display_name("user-123"))
+finally:
+    backend.close()
+```
+
+For long-running applications, keep the backend for the application lifetime and close it from your normal shutdown hook. For short scoped backend operations that are not decorator-bound, `DiskCacheBackend` also supports `with DiskCacheBackend(...) as backend:`.
+
+Do **not** create a decorator-bound `DiskCacheBackend` inside a short `with` block unless all decorated calls happen before the block exits. The context manager closes the backend on exit; later calls through the decorated function raise `CacheBackendClosedError`.
+
+Disk backend design lives in `docs/disk_cache_backend.md`; implementation uses SQLite and the cache serializer interface. The default disk payload serializer uses pickle, so cache databases must be treated as trusted local files only — do not load cache DBs from untrusted sources or place them in world-writable directories. For simple JSON-compatible payloads, use `JsonCacheSerializer` instead of pickle when values should be easier to inspect or consume from other languages.
+
+`DiskCacheBackend` is intended for single-host local caching. It uses normal SQLite file locking, requests WAL mode by default, and configures a 5000 ms busy timeout to reduce transient `database is locked` failures. Those settings improve local reader/writer behavior, but they do not make it a distributed cache and they do not promise safe cross-host semantics on shared/network filesystems. If multiple processes use the same cache file, expect normal SQLite contention behavior and keep cached values disposable. If you need visibility into rows dropped because of serializer mismatches or corrupt payloads, pass `on_drop=` to `DiskCacheBackend` and log the `DiskCacheDropEvent`.

blakemere_wraptools-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+pydecorators/__init__.py,sha256=Wyk6U2-LfKH-I9KWTuBbOmVlQAfu4Sp3Vf91aYLJfSY,2745
+pydecorators/_core.py,sha256=Xv7izivU8ruoWrWh0u1ndOMOsVmbMUtOEtheMMYaxB0,2192
+pydecorators/_typing.py,sha256=-gsBvCZnJNL3i32s_KZhZ2rnp4avE7fxiQvP7hzWGl0,870
+pydecorators/cache_result.py,sha256=nGx0M6v1MQKOT25khACaSNh-OxLdvdRVaiNxLe7S1e0,43291
+pydecorators/circuit_breaker.py,sha256=2IkYTtlVpfRGPtD6JLzxnOAiDu0bAe6mN988S47sMlk,6061
+pydecorators/deprecated.py,sha256=MxRZYKjwxu5TqQDgWPrWzZnQOD5NvFHS-YkOpjaVbPY,4634
+pydecorators/exceptions.py,sha256=M_I20h18hiWTPGGfXbPuk5qREnu4Rh8srdPcM99o6Hc,1457
+pydecorators/log_calls.py,sha256=ST6p6mkDj3_mYeEFAlHLfxBRShKps1sWCM1yP-1wAe8,9596
+pydecorators/measure_time.py,sha256=2kMIJfbOzDRZHFl8c0_Qr_-Cx5edbjfmXUFae2UA1Zc,6000
+pydecorators/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pydecorators/rate_limit.py,sha256=s6HPspCkoqRovkcB1_mQEPbDskXBrjQ4-TVNs4lQvpE,4702
+pydecorators/redis_backend.py,sha256=SldKcpNq32-nuwx63ENWp6DID3FEX3_IFH4-RbeoYUw,9068
+pydecorators/require_env.py,sha256=OPId8ETjEDKkJoMWASmRj7pJ_Goa3EeC14vQSqDjmBY,4877
+pydecorators/retry.py,sha256=IDOsbpMFj5bVkUTMKy58sZm1KpiZ8XyA7hIECY97wyk,7419
+pydecorators/timeout.py,sha256=B41N5KBcBS1pR1CvSzGx54QeTskTayqLbT4sD948Nng,2220
+pydecorators/validate_types.py,sha256=7J3pzwhjnhFMvyZJUhXJxBlATLXzZ2neFgaHnnzMNSU,5772
+blakemere_wraptools-0.1.0.dist-info/METADATA,sha256=zfgrtip1sGzQF__ADI_KLvLkwi7vEiaLXIK4jZ_6lzM,14681
+blakemere_wraptools-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+blakemere_wraptools-0.1.0.dist-info/licenses/LICENSE,sha256=f1q4FlcGQ_N11BjVPpGOxPC28rAAHmQlBWyXUy7-zH4,1068
+blakemere_wraptools-0.1.0.dist-info/RECORD,,

blakemere_wraptools-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

blakemere_wraptools-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Russ Davies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pydecorators/__init__.py

@@ -0,0 +1,98 @@
+"""Useful decorators for everyday Python projects.
+
+The package is intentionally small and boring: reliability, caching, rate limiting,
+timeouts, and developer ergonomics without dragging in a framework-shaped sofa.
+"""
+
+from pydecorators.cache_result import (
+    CacheBackend,
+    CacheCoalescingInfo,
+    CacheInfo,
+    CacheSerializer,
+    DiskCacheAggregateInspectionReport,
+    DiskCacheBackend,
+    DiskCacheDropEvent,
+    DiskCacheInspectionEntry,
+    DiskCacheInspectionReport,
+    DiskCacheIntegrityReport,
+    DiskCacheMaintenanceReport,
+    DiskCacheMetadata,
+    DiskCachePreviewContext,
+    JsonCacheSerializer,
+    MemoryCacheBackend,
+    PickleCacheSerializer,
+    cache_directory,
+    cache_namespace,
+    cache_result,
+    redact_json_preview,
+)
+from pydecorators.circuit_breaker import CircuitBreakerOpen, CircuitState, circuit_breaker
+from pydecorators.deprecated import deprecated
+from pydecorators.exceptions import (
+    CacheBackendClosedError,
+    CacheKeyError,
+    CacheSerializationError,
+    ConfigurationError,
+    FunctionTimedOut,
+    RateLimitExceeded,
+    UnsupportedCacheSchemaVersionError,
+    UsefulDecoratorsError,
+    ValidationError,
+)
+from pydecorators.log_calls import log_calls
+from pydecorators.measure_time import TimingInfo, measure_time
+from pydecorators.rate_limit import rate_limit
+from pydecorators.redis_backend import RedisCacheBackend, RedisCacheClient
+from pydecorators.require_env import EnvRequirementError, require_env
+from pydecorators.retry import retry
+from pydecorators.timeout import timeout
+from pydecorators.validate_types import validate_types
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CacheBackend",
+    "CacheBackendClosedError",
+    "CacheCoalescingInfo",
+    "CacheInfo",
+    "CacheKeyError",
+    "CacheSerializationError",
+    "CacheSerializer",
+    "CircuitBreakerOpen",
+    "CircuitState",
+    "ConfigurationError",
+    "DiskCacheAggregateInspectionReport",
+    "DiskCacheBackend",
+    "DiskCacheDropEvent",
+    "DiskCacheInspectionEntry",
+    "DiskCacheInspectionReport",
+    "DiskCacheIntegrityReport",
+    "DiskCacheMaintenanceReport",
+    "DiskCacheMetadata",
+    "DiskCachePreviewContext",
+    "EnvRequirementError",
+    "FunctionTimedOut",
+    "JsonCacheSerializer",
+    "MemoryCacheBackend",
+    "PickleCacheSerializer",
+    "RateLimitExceeded",
+    "RedisCacheBackend",
+    "RedisCacheClient",
+    "TimingInfo",
+    "UnsupportedCacheSchemaVersionError",
+    "UsefulDecoratorsError",
+    "ValidationError",
+    "cache_directory",
+    "cache_namespace",
+    "cache_result",
+    "circuit_breaker",
+    "deprecated",
+    "log_calls",
+    "measure_time",
+    "rate_limit",
+    "redact_json_preview",
+    "require_env",
+    "retry",
+    "timeout",
+    "validate_types",
+]

pydecorators/_core.py

@@ -0,0 +1,70 @@
+"""Internal helpers shared by decorator implementations."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import time
+from collections.abc import Awaitable, Callable
+from functools import wraps
+from typing import Any, TypeGuard, cast
+
+from pydecorators._typing import P, R
+from pydecorators.exceptions import ConfigurationError
+
+
+def is_async_callable(func: object) -> TypeGuard[Callable[..., Awaitable[Any]]]:
+    """Return whether *func* is an async callable.
+
+    `inspect.iscoroutinefunction` handles normal async functions. The `__call__`
+    fallback lets callable objects participate without each decorator needing to
+    remember that Python allows functions to wear fake moustaches.
+    """
+
+    if inspect.iscoroutinefunction(func):
+        return True
+    if not callable(func):
+        return False
+    return inspect.iscoroutinefunction(type(func).__call__)
+
+
+def monotonic() -> float:
+    """Return a monotonic timestamp suitable for elapsed-time calculations."""
+
+    return time.monotonic()
+
+
+def sync_sleep(seconds: float) -> None:
+    """Sleep synchronously for *seconds*. Exists mainly for injection in tests."""
+
+    time.sleep(seconds)
+
+
+async def async_sleep(seconds: float) -> None:
+    """Sleep asynchronously for *seconds*. Exists mainly for injection in tests."""
+
+    await asyncio.sleep(seconds)
+
+
+def require_positive_number(name: str, value: float | int) -> None:
+    """Raise :class:`ConfigurationError` unless *value* is greater than zero."""
+
+    if value <= 0:
+        raise ConfigurationError(f"{name} must be greater than zero")
+
+
+def require_non_negative_number(name: str, value: float | int) -> None:
+    """Raise :class:`ConfigurationError` unless *value* is zero or greater."""
+
+    if value < 0:
+        raise ConfigurationError(f"{name} must be zero or greater")
+
+
+def mirror_metadata(wrapper: Callable[P, R], wrapped: Callable[P, R]) -> Callable[P, R]:
+    """Apply standard wrapped-function metadata to *wrapper*.
+
+    This is a tiny wrapper around :func:`functools.wraps` so decorators can use a
+    single convention and tests can assert the convention once.
+    """
+
+    return cast(Callable[P, R], wraps(wrapped)(wrapper))

pydecorators/_typing.py

@@ -0,0 +1,30 @@
+"""Shared typing primitives for decorator implementations."""
+
+from collections.abc import Awaitable, Callable
+from typing import Any, ParamSpec, Protocol, TypeAlias, TypeVar
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+SyncCallable: TypeAlias = Callable[P, R]
+AsyncCallable: TypeAlias = Callable[P, Awaitable[R]]
+AnyCallable: TypeAlias = Callable[..., Any]
+Decorator: TypeAlias = Callable[[SyncCallable[P, R]], SyncCallable[P, R]]
+
+
+class Clock(Protocol):
+    """Callable protocol for injectable monotonic clocks."""
+
+    def __call__(self) -> float: ...
+
+
+class SyncSleep(Protocol):
+    """Callable protocol for injectable synchronous sleep functions."""
+
+    def __call__(self, seconds: float) -> None: ...
+
+
+class AsyncSleep(Protocol):
+    """Callable protocol for injectable asynchronous sleep functions."""
+
+    def __call__(self, seconds: float) -> Awaitable[None]: ...