refactor(all): create specific modules for typing

Author: Athroniaeth

README.md

@@ -2,7 +2,7 @@
 
 ![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FAthroniaeth%2Ffastapi-api-key%2Fmain%2Fpyproject.toml)
 [![Tested with pytest](https://img.shields.io/badge/tests-pytest-informational.svg)](https://pytest.org/)
-![Coverage](https://img.shields.io/badge/coverage-69%25-brightgreen.svg)
+![Coverage](https://img.shields.io/badge/coverage-72%25-brightgreen.svg)
 [![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-4B32C3.svg)](https://docs.astral.sh/ruff/)
 [![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://bandit.readthedocs.io/)
 [![Deps: uv](https://img.shields.io/badge/deps-managed%20with%20uv-3E4DD8.svg)](https://docs.astral.sh/uv/)

src/fastapi_api_key/__init__.py

@@ -3,7 +3,7 @@
 import subprocess  # nosec: B404
 
 from fastapi_api_key.domain.entities import ApiKey
-from fastapi_api_key.service import ApiKeyService
+from fastapi_api_key.services.service import ApiKeyService
 from fastapi_api_key.api import create_api_keys_router, create_depends_api_key
 from fastapi_api_key.cli import create_api_keys_cli
 

src/fastapi_api_key/api.py

@@ -1,7 +1,8 @@
 import warnings
 
 
-from fastapi_api_key.service import AbstractApiKeyService
+from fastapi_api_key.services.service import AbstractApiKeyService
+from fastapi_api_key.types import SecurityHTTPBearer, SecurityAPIKeyHeader
 
 try:
     import fastapi  # noqa: F401
@@ -96,7 +97,7 @@ class DeletedResponse(BaseModel):
 def _to_out(entity: ApiKey) -> ApiKeyOut:
     """Map an `ApiKey` entity to the public `ApiKeyOut` schema."""
     return ApiKeyOut(
-        id=str(entity.id_),
+        id="entity.id_",
         name=entity.name,
         description=entity.description,
         is_active=entity.is_active,
@@ -351,10 +352,6 @@ async def _handle_verify_key(
         ) from exc
 
 
-SecurityHTTPBearer = Union[Callable[[HTTPAuthorizationCredentials], Awaitable[D]]]
-SecurityAPIKeyHeader = Union[Callable[[str], Awaitable[D]]]
-
-
 def create_depends_api_key(
     depends_svc_api_keys: Callable[[...], Awaitable[AbstractApiKeyService[D]]],
     security: Optional[Union[HTTPBearer, APIKeyHeader]] = None,

src/fastapi_api_key/cli.py

@@ -1,25 +1,18 @@
 import asyncio
 import json
-from contextlib import AbstractAsyncContextManager
 from dataclasses import asdict, is_dataclass
 from datetime import datetime, timezone
-from typing import TYPE_CHECKING, Any, Awaitable, Callable, Optional
+from typing import Any, Awaitable, Callable, Optional
 
-from fastapi_api_key.domain.entities import ApiKeyEntity
+from fastapi_api_key.domain.base import ApiKeyEntity
 from fastapi_api_key.domain.errors import (
     InvalidKey,
     KeyExpired,
     KeyInactive,
     KeyNotFound,
     KeyNotProvided,
 )
-from fastapi_api_key.service import AbstractApiKeyService
-
-if TYPE_CHECKING:
-    pass
-
-ServiceFactory = Callable[[], AbstractAsyncContextManager[AbstractApiKeyService[Any]]]
-"""Callable returning an async context manager that yields an API key service instance."""
+from fastapi_api_key.types import ServiceFactory
 
 DomainErrors = (
     InvalidKey,

src/fastapi_api_key/domain/base.py

@@ -0,0 +1,86 @@
+from datetime import datetime
+from typing import Optional, runtime_checkable, Protocol, TypeVar
+
+
+@runtime_checkable
+class ApiKeyEntity(Protocol):
+    """Protocol for an API key entity.
+
+    Attributes:
+        id_ (str): Unique identifier for the API key.
+        name (Optional[str]): Optional name for the API key.
+        description (Optional[str]): Optional description for the API key.
+        is_active (bool): Indicates if the API key is active.
+        expires_at (Optional[datetime]): Optional expiration datetime for the API key.
+        created_at (datetime): Datetime when the API key was created.
+        last_used_at (Optional[datetime]): Optional datetime when the API key was last used.
+        key_id (str): Public identifier part of the API key.
+        key_hash (Optional[str]): Hashed secret part of the API key.
+        _key_secret (str): The secret part of the API key, only available at creation time.
+        _key_secret_first (str): First part of the secret for display purposes.
+        _key_secret_last (str): Last part of the secret for display purposes.
+    """
+
+    id_: str
+    name: Optional[str]
+    description: Optional[str]
+    is_active: bool
+    expires_at: Optional[datetime]
+    created_at: datetime
+    last_used_at: Optional[datetime]
+    key_id: str
+    key_hash: Optional[str]
+    _key_secret: Optional[str]
+    _key_secret_first: Optional[str]
+    _key_secret_last: Optional[str]
+
+    @property
+    def key_secret(self) -> Optional[str]:
+        """The secret part of the API key, only available at creation time."""
+        key_secret = self._key_secret
+        self._key_secret = None  # Clear after first access
+        return key_secret
+
+    @property
+    def key_secret_first(self) -> str:
+        """First part of the secret for display purposes/give the user a clue as to which key we are talking about."""
+        ...
+
+    @property
+    def key_secret_last(self) -> str:
+        """Last part of the secret for display purposes/give the user a clue as to which key we are talking about."""
+        ...
+
+    def full_key_secret(
+        self,
+        global_prefix: str,
+        separator: str,
+        key_secret: str,
+    ) -> str:
+        """Construct the full API key string to be given to the user."""
+        ...
+
+    def disable(self) -> None:
+        """Disable the API key so it cannot be used for authentication."""
+        ...
+
+    def enable(self) -> None:
+        """Enable the API key so it can be used for authentication."""
+        ...
+
+    def touch(self) -> None:
+        """Mark the key as used now. Trigger for each ensured authentication."""
+        ...
+
+    def ensure_can_authenticate(self) -> None:
+        """Raise domain errors if this key cannot be used for authentication.
+
+        Raises:
+            ApiKeyDisabledError: If the key is disabled.
+            ApiKeyExpiredError: If the key is expired.
+        """
+        ...
+
+
+D = TypeVar("D", bound=ApiKeyEntity)
+"""Domain entity type variable bound to any ApiKeyEntity subclass."""

src/fastapi_api_key/domain/entities.py

@@ -1,7 +1,8 @@
 from dataclasses import field, dataclass
 from datetime import datetime, timezone
-from typing import Optional, runtime_checkable, Protocol, TypeVar
+from typing import Optional
 
+from fastapi_api_key.domain.base import ApiKeyEntity
 from fastapi_api_key.domain.errors import KeyExpired, KeyInactive
 from fastapi_api_key.utils import (
     uuid_factory,
@@ -10,88 +11,6 @@
 )
 
 
-@runtime_checkable
-class ApiKeyEntity(Protocol):
-    """Protocol for an API key entity.
-
-    Attributes:
-        id_ (str): Unique identifier for the API key.
-        name (Optional[str]): Optional name for the API key.
-        description (Optional[str]): Optional description for the API key.
-        is_active (bool): Indicates if the API key is active.
-        expires_at (Optional[datetime]): Optional expiration datetime for the API key.
-        created_at (datetime): Datetime when the API key was created.
-        last_used_at (Optional[datetime]): Optional datetime when the API key was last used.
-        key_id (str): Public identifier part of the API key.
-        key_hash (Optional[str]): Hashed secret part of the API key.
-        key_secret_first (str): First part of the secret for display purposes.
-        key_secret_last (str): Last part of the secret for display purposes.
-    """
-
-    id_: str
-    name: Optional[str]
-    description: Optional[str]
-    is_active: bool
-    expires_at: Optional[datetime]
-    created_at: datetime
-    last_used_at: Optional[datetime]
-    key_id: str
-    key_hash: Optional[str]
-    _key_secret: Optional[str]
-    _key_secret_first: Optional[str]
-    _key_secret_last: Optional[str]
-
-    @property
-    def key_secret(self) -> Optional[str]:
-        """The secret part of the API key, only available at creation time."""
-        key_secret = self._key_secret
-        self._key_secret = None  # Clear after first access
-        return key_secret
-
-    @property
-    def key_secret_first(self) -> str:
-        """First part of the secret for display purposes/give the user a clue as to which key we are talking about."""
-        ...
-
-    @property
-    def key_secret_last(self) -> str:
-        """Last part of the secret for display purposes/give the user a clue as to which key we are talking about."""
-        ...
-
-    def full_key_secret(
-        self,
-        global_prefix: str,
-        separator: str,
-        key_secret: str,
-    ) -> str:
-        """Construct the full API key string to be given to the user."""
-        ...
-
-    def disable(self) -> None:
-        """Disable the API key so it cannot be used for authentication."""
-        ...
-
-    def enable(self) -> None:
-        """Enable the API key so it can be used for authentication."""
-        ...
-
-    def touch(self) -> None:
-        """Mark the key as used now. Trigger for each ensured authentication."""
-        ...
-
-    def ensure_can_authenticate(self) -> None:
-        """Raise domain errors if this key cannot be used for authentication.
-
-        Raises:
-            ApiKeyDisabledError: If the key is disabled.
-            ApiKeyExpiredError: If the key is expired.
-        """
-        ...
-
-
-D = TypeVar("D", bound=ApiKeyEntity)
-
-
 def _normalize_datetime(value: Optional[datetime]) -> Optional[datetime]:
     """Ensure datetimes are timezone-aware (UTC)."""
     if value is None:

src/fastapi_api_key/repositories/base.py

@@ -1,7 +1,7 @@
 from abc import ABC, abstractmethod
 from typing import Generic, Optional, List
 
-from fastapi_api_key.domain.entities import D
+from fastapi_api_key.domain.base import D
 
 
 class AbstractApiKeyRepository(ABC, Generic[D]):

src/fastapi_api_key/repositories/in_memory.py

@@ -1,7 +1,7 @@
 from typing import Optional, List
 
+from fastapi_api_key.domain.base import D
 from fastapi_api_key.repositories.base import AbstractApiKeyRepository
-from fastapi_api_key.domain.entities import D
 
 
 class InMemoryApiKeyRepository(AbstractApiKeyRepository[D]):

src/fastapi_api_key/repositories/sql.py

@@ -1,3 +1,5 @@
+from fastapi_api_key.domain.base import D
+
 try:
     import sqlalchemy  # noqa: F401
 except ModuleNotFoundError as e:
@@ -15,7 +17,7 @@
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import Mapped, mapped_column, DeclarativeBase
 
-from fastapi_api_key.domain.entities import ApiKey, D
+from fastapi_api_key.domain.entities import ApiKey
 from fastapi_api_key.repositories.base import AbstractApiKeyRepository
 from fastapi_api_key.utils import datetime_factory