tiny-service-core 0.1.0__tar.gz

tiny_service_core-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.3
+Name: tiny-service-core
+Version: 0.1.0
+Summary: 🪐 Shared functionality for tiny microservices
+Keywords: async,fastapi,microservice,core
+Author: Aliaksei Urbanski
+Author-email: Aliaksei Urbanski <aliaksei.urbanski@gmail.com>
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Pydantic
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Internet
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Dist: fastapi
+Requires-Dist: pydantic-settings
+Requires-Dist: sentry-sdk[fastapi]
+Requires-Dist: redis ; extra == 'cache'
+Requires-Dist: alembic ; extra == 'db'
+Requires-Dist: asyncpg ; extra == 'db'
+Requires-Dist: sentry-sdk[asyncpg,sqlalchemy] ; extra == 'db'
+Requires-Dist: sqlmodel ; extra == 'db'
+Requires-Dist: fastapi[standard] ; extra == 'dev'
+Requires-Dist: httpx ; extra == 'http-client'
+Requires-Dist: sentry-sdk[httpx] ; extra == 'http-client'
+Maintainer: Aliaksei Urbanski
+Maintainer-email: Aliaksei Urbanski <aliaksei.urbanski@gmail.com>
+Requires-Python: >=3.12
+Project-URL: Issues, https://github.com/Jamim/tiny-service-core/issues
+Project-URL: Repository, https://github.com/Jamim/tiny-service-core
+Provides-Extra: cache
+Provides-Extra: db
+Provides-Extra: dev
+Provides-Extra: http-client
+Description-Content-Type: text/markdown
+
+# 🪐 Tiny Service Core
+
+[![CI][ci-badge]][ci]
+[![Coverage][cov-badge]][cov]
+[![License][license-badge]][license]
+[![Version][ver-badge]][pypi]
+[![Python][py-badge]][pypi]
+
+This library implements common functions that allows
+you to build tiny microservices with less boilerplate.
+
+[ci-badge]: https://img.shields.io/github/actions/workflow/status/Jamim/tiny-service-core/ci.yml.svg
+[ci]: https://github.com/Jamim/tiny-service-core/actions/workflows/ci.yml
+[cov-badge]: https://codecov.io/github/Jamim/tiny-service-core/graph/badge.svg
+[cov]: https://app.codecov.io/github/Jamim/tiny-service-core
+[license-badge]: https://img.shields.io/github/license/Jamim/tiny-service-core
+[ver-badge]: https://img.shields.io/pypi/v/tiny-service-core
+[pypi]: https://pypi.org/project/tiny-service-core/
+[py-badge]: https://img.shields.io/pypi/pyversions/tiny-service-core
+[license]: https://github.com/Jamim/tiny-service-core/blob/main/LICENSE
+
+## Installation
+
+Install with `pip`, including optional dependencies:
+
+```shell
+pip install tiny-service-core[cache,db,http-client]
+```
+
+Clearly, you can use any other Python package manager instead.  
+I personally prefer using [uv][uv] nowadays.
+
+```shell
+uv add tiny-service-core --extra cache --extra db --extra http-client
+```
+
+[uv]: https://docs.astral.sh/uv/
+
+## Dependencies
+
+Tiny Service Core is highly opinionated.  
+Current version glues together these components:
+  - [FastAPI][fastapi]
+  - [pydantic-settings][pydantic-settings]
+  - [Sentry][sentry]
+  - with `cache` [extra][installing-extras]
+    * [Redis][redis]
+  - `db`
+    * [SQLModel][sqlmodel]
+    * [asyncpg][asyncpg]
+    * [Alembic][alembic]
+  - `http-client`
+    * [HTTPX][httpx]
+
+[fastapi]: https://fastapi.tiangolo.com
+[pydantic-settings]: https://docs.pydantic.dev/latest/concepts/pydantic_settings/
+[sentry]: https://docs.sentry.io/platforms/python/
+[redis]: https://github.com/redis/redis-py
+[sqlmodel]: https://sqlmodel.tiangolo.com
+[asyncpg]: https://github.com/MagicStack/asyncpg
+[alembic]: https://alembic.sqlalchemy.org
+[httpx]: https://www.python-httpx.org
+
+[installing-extras]: https://packaging.python.org/en/latest/tutorials/installing-packages/#installing-extras

tiny_service_core-0.1.0/README.md

@@ -0,0 +1,64 @@
+# 🪐 Tiny Service Core
+
+[![CI][ci-badge]][ci]
+[![Coverage][cov-badge]][cov]
+[![License][license-badge]][license]
+[![Version][ver-badge]][pypi]
+[![Python][py-badge]][pypi]
+
+This library implements common functions that allows
+you to build tiny microservices with less boilerplate.
+
+[ci-badge]: https://img.shields.io/github/actions/workflow/status/Jamim/tiny-service-core/ci.yml.svg
+[ci]: https://github.com/Jamim/tiny-service-core/actions/workflows/ci.yml
+[cov-badge]: https://codecov.io/github/Jamim/tiny-service-core/graph/badge.svg
+[cov]: https://app.codecov.io/github/Jamim/tiny-service-core
+[license-badge]: https://img.shields.io/github/license/Jamim/tiny-service-core
+[ver-badge]: https://img.shields.io/pypi/v/tiny-service-core
+[pypi]: https://pypi.org/project/tiny-service-core/
+[py-badge]: https://img.shields.io/pypi/pyversions/tiny-service-core
+[license]: https://github.com/Jamim/tiny-service-core/blob/main/LICENSE
+
+## Installation
+
+Install with `pip`, including optional dependencies:
+
+```shell
+pip install tiny-service-core[cache,db,http-client]
+```
+
+Clearly, you can use any other Python package manager instead.  
+I personally prefer using [uv][uv] nowadays.
+
+```shell
+uv add tiny-service-core --extra cache --extra db --extra http-client
+```
+
+[uv]: https://docs.astral.sh/uv/
+
+## Dependencies
+
+Tiny Service Core is highly opinionated.  
+Current version glues together these components:
+  - [FastAPI][fastapi]
+  - [pydantic-settings][pydantic-settings]
+  - [Sentry][sentry]
+  - with `cache` [extra][installing-extras]
+    * [Redis][redis]
+  - `db`
+    * [SQLModel][sqlmodel]
+    * [asyncpg][asyncpg]
+    * [Alembic][alembic]
+  - `http-client`
+    * [HTTPX][httpx]
+
+[fastapi]: https://fastapi.tiangolo.com
+[pydantic-settings]: https://docs.pydantic.dev/latest/concepts/pydantic_settings/
+[sentry]: https://docs.sentry.io/platforms/python/
+[redis]: https://github.com/redis/redis-py
+[sqlmodel]: https://sqlmodel.tiangolo.com
+[asyncpg]: https://github.com/MagicStack/asyncpg
+[alembic]: https://alembic.sqlalchemy.org
+[httpx]: https://www.python-httpx.org
+
+[installing-extras]: https://packaging.python.org/en/latest/tutorials/installing-packages/#installing-extras

tiny_service_core-0.1.0/pyproject.toml

@@ -0,0 +1,136 @@
+[project]
+name = "tiny-service-core"
+description = "🪐 Shared functionality for tiny microservices"
+
+# https://github.com/astral-sh/uv/issues/11718
+version = "0.1.0"
+
+readme = "README.md"
+license = { text = "MIT" }
+
+authors = [
+    { name = "Aliaksei Urbanski", email = "aliaksei.urbanski@gmail.com" },
+]
+maintainers = [
+    { name = "Aliaksei Urbanski", email = "aliaksei.urbanski@gmail.com" },
+]
+
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Framework :: AsyncIO",
+    "Framework :: FastAPI",
+    "Framework :: Pydantic",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Topic :: Internet",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+    "Topic :: Software Development",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Implementation :: CPython",
+]
+keywords = ["async", "fastapi", "microservice", "core"]
+
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi",
+    "pydantic-settings",
+    "sentry-sdk[fastapi]",
+]
+
+[project.optional-dependencies]
+dev = [
+    "fastapi[standard]",
+]
+cache = [
+    "redis",
+]
+db = [
+    "alembic",
+    "asyncpg",
+    "sentry-sdk[asyncpg,sqlalchemy]",
+    "sqlmodel",
+]
+http-client = [
+    "httpx",
+    "sentry-sdk[httpx]",
+]
+
+[dependency-groups]
+lint = [
+    "mypy",
+    "ruff",
+]
+test = [
+    "pytest",
+    "pytest-cov",
+    "pytest-env",
+]
+
+[project.urls]
+Repository = "https://github.com/Jamim/tiny-service-core"
+Issues = "https://github.com/Jamim/tiny-service-core/issues"
+
+[build-system]
+requires = ["uv_build>=0.9.15,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "core"
+
+[tool.ruff]
+line-length = 79
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.ruff.lint]
+select = [
+    # pycodestyle
+    "E",
+    # Pyflakes
+    "F",
+    # pyupgrade
+    "UP",
+    # flake8-bugbear
+    "B",
+    # flake8-simplify
+    "SIM",
+    # isort
+    "I",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/core/__init__.py" = ["F401", "E402"]
+"src/core/deps/__init__.py" = ["F401"]
+
+[tool.ruff.lint.isort]
+known-local-folder = ["core"]
+
+[tool.mypy]
+mypy_path = "stubs"
+files = "src/**/*.py"
+plugins = "pydantic.mypy"
+strict = true
+
+[tool.pytest.ini_options]
+addopts = "--cov core"
+
+[tool.pytest_env]
+APP_PROJ = "tiny-service"
+APP_NAME = "core"
+APP_ENV = "test"
+APP_KEY = "42"
+DB_URL = "postgresql+asyncpg://foo:bar@127.0.0.1/dummy"
+
+[tool.coverage.run]
+branch = true

tiny_service_core-0.1.0/src/core/__init__.py

@@ -0,0 +1,53 @@
+import logging
+from importlib.metadata import version
+from typing import Any, cast
+
+from fastapi import FastAPI
+
+from .config import CoreSettings
+
+settings_class: type[CoreSettings]
+try:
+    from app.config import Settings
+except ImportError:
+    settings_class = CoreSettings
+else:
+    if issubclass(Settings, CoreSettings):
+        settings_class = cast(type[CoreSettings], Settings)
+    else:
+        settings_class = type('CombinedSettings', (Settings, CoreSettings), {})
+
+
+settings = settings_class()
+logger = logging.getLogger(settings.app_title)
+
+from .app import make_app
+from .crypto import get_key_hash
+
+
+def run(app: FastAPI, **kwargs: Any) -> None:
+    import uvicorn
+
+    kwargs.setdefault('host', settings.app_host)
+    kwargs.setdefault('port', settings.app_port)
+
+    uvicorn.run(app, **kwargs)
+
+
+__all__ = [
+    'get_key_hash',
+    'logger',
+    'make_app',
+    'run',
+    'settings',
+]
+
+try:
+    from .lock import Lock
+except ImportError:
+    pass
+else:
+    __all__.append('Lock')
+
+__name__ = 'tiny-service-core'
+__version__ = version(__name__)

tiny_service_core-0.1.0/src/core/app.py

@@ -0,0 +1,50 @@
+from typing import Any, Literal
+
+from fastapi import APIRouter, FastAPI, params
+
+from . import settings
+from .deps import VerifyClient
+from .lifespan import lifespan
+from .sentry import init_sentry
+
+
+def make_app(**kwargs: Any) -> FastAPI:
+    init_sentry()
+
+    slug = settings.app_name
+
+    app = FastAPI(
+        lifespan=lifespan,
+        docs_url=f'/{slug}/docs',
+        redoc_url=f'/{slug}/redoc',
+        openapi_url=(
+            None
+            if settings.app_env == 'production'
+            else f'/{slug}/openapi.json'
+        ),
+        title=settings.app_title,
+        **kwargs,
+    )
+
+    add_router(app, 'public', f'/api/v1/{slug}')
+    add_router(app, 'internal', f'/internal/{slug}', [VerifyClient])
+
+    return app
+
+
+def add_router(
+    app: FastAPI,
+    router_type: Literal['public', 'internal'],
+    prefix: str,
+    dependencies: list[params.Depends] | None = None,
+) -> None:
+    from app import api
+
+    func_name = f'add_{router_type}_api'
+    if not hasattr(api, func_name):
+        return
+
+    router = APIRouter(prefix=prefix, dependencies=dependencies)
+    getattr(api, func_name)(router)
+
+    app.include_router(router)

tiny_service_core-0.1.0/src/core/config.py

@@ -0,0 +1,78 @@
+from typing import TYPE_CHECKING, Annotated, Literal
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, NoDecode
+
+SLUG_PATTERN = r'^[a-z0-9-]+$'
+
+
+class AppSettings(BaseSettings):
+    @property
+    def app_title(self) -> str:
+        return f'{self.app_proj}-{self.app_name}'
+
+    app_proj: str = Field(pattern=SLUG_PATTERN)
+    app_name: str = Field(pattern=SLUG_PATTERN)
+
+    app_env: Literal['production', 'staging', 'local', 'test']
+    app_key: str
+
+    app_host: str = '127.0.0.1'
+    app_port: int = 8080
+
+    app_client_key_hashes: Annotated[list[str], NoDecode] = []
+
+    @field_validator('app_client_key_hashes', mode='before')
+    @classmethod
+    def split_hashes(cls, hashes: str | list[str]) -> list[str]:
+        if isinstance(hashes, str):
+            hashes = hashes.split(',')
+        return hashes
+
+
+class SentrySettings(BaseSettings):
+    sentry_dsn: str | None = None
+    traces_sample_rate: float = 1.0
+
+
+class CacheSettings(BaseSettings):
+    cache_url: str = 'redis://localhost:6379'
+
+
+class DBSettings(BaseSettings):
+    db_url: str
+
+
+class HTTPClientSettings(BaseSettings):
+    http_retries: int = 2
+
+
+OPTIONAL_SETTINGS: dict[str, type[BaseSettings]] = {
+    'redis': CacheSettings,
+    'sqlmodel': DBSettings,
+    'httpx': HTTPClientSettings,
+}
+
+settings_bases = [AppSettings, SentrySettings]
+
+for module, base in OPTIONAL_SETTINGS.items():
+    try:
+        __import__(module)
+    except ImportError:
+        pass
+    else:
+        settings_bases.append(base)
+
+
+if TYPE_CHECKING:
+
+    class CoreSettings(
+        AppSettings,
+        SentrySettings,
+        CacheSettings,
+        DBSettings,
+        HTTPClientSettings,
+    ): ...
+else:
+
+    class CoreSettings(*settings_bases): ...

tiny_service_core-0.1.0/src/core/crypto.py

@@ -0,0 +1,5 @@
+from hashlib import blake2s
+
+
+def get_key_hash(key: str) -> str:
+    return blake2s(key.encode()).hexdigest()

tiny_service_core-0.1.0/src/core/deps/__init__.py

@@ -0,0 +1,28 @@
+from .auth import AppClientKey as Token
+from .auth import VerifyClient
+
+__all__ = [
+    'Token',
+    'VerifyClient',
+]
+
+try:
+    from .cache import Cache
+except ImportError:
+    pass
+else:
+    __all__.append('Cache')
+
+try:
+    from .db import Session
+except ImportError:
+    pass
+else:
+    __all__.append('Session')
+
+try:
+    from .http_client import HTTPClient
+except ImportError:
+    pass
+else:
+    __all__.append('HTTPClient')

tiny_service_core-0.1.0/src/core/deps/auth.py

@@ -0,0 +1,31 @@
+import hmac
+from typing import Annotated
+
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+
+import core
+from ..crypto import get_key_hash
+
+
+def get_app_client_key(
+    credentials: Annotated[
+        HTTPAuthorizationCredentials, Depends(HTTPBearer())
+    ],
+) -> str:
+    return credentials.credentials
+
+
+AppClientKey = Annotated[str, Depends(get_app_client_key)]
+
+
+def verify_app_client_key(app_key: AppClientKey) -> None:
+    key_hash = get_key_hash(app_key)
+    for allowed_key_hash in core.settings.app_client_key_hashes:
+        if hmac.compare_digest(key_hash, allowed_key_hash):
+            return
+
+    raise HTTPException(status.HTTP_401_UNAUTHORIZED, 'App key is not valid')
+
+
+VerifyClient = Depends(verify_app_client_key)

tiny_service_core-0.1.0/src/core/deps/cache.py

@@ -0,0 +1,11 @@
+from typing import Annotated, cast
+
+from fastapi import Depends, Request
+from redis.asyncio.client import Redis
+
+
+def get_cache(request: Request) -> Redis:
+    return cast(Redis, request.app.state.cache)
+
+
+Cache = Annotated[Redis, Depends(get_cache)]

tiny_service_core-0.1.0/src/core/deps/db.py

@@ -0,0 +1,20 @@
+from collections.abc import AsyncGenerator
+from typing import Annotated, cast
+
+from fastapi import Depends, Request
+from sqlalchemy.orm import sessionmaker
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+
+async def get_session(request: Request) -> AsyncGenerator[AsyncSession]:
+    async_session = sessionmaker(
+        request.app.state.db,
+        class_=AsyncSession,
+        expire_on_commit=False,
+    )
+    session = cast(AsyncSession, async_session())
+    async with session:
+        yield session
+
+
+Session = Annotated[AsyncSession, Depends(get_session)]

tiny_service_core-0.1.0/src/core/deps/http_client.py

@@ -0,0 +1,11 @@
+from typing import Annotated, cast
+
+from fastapi import Depends, Request
+from httpx import AsyncClient
+
+
+def get_http_client(request: Request) -> AsyncClient:
+    return cast(AsyncClient, request.app.state.http_client)
+
+
+HTTPClient = Annotated[AsyncClient, Depends(get_http_client)]

tiny_service_core-0.1.0/src/core/excs.py

@@ -0,0 +1,11 @@
+from fastapi import HTTPException, status
+
+
+class LimitExceeded(HTTPException):
+    def __init__(self) -> None:
+        super().__init__(status.HTTP_403_FORBIDDEN, 'Limit exceeded')
+
+
+class NotFound(HTTPException):
+    def __init__(self, name: str) -> None:
+        super().__init__(status.HTTP_404_NOT_FOUND, f'{name} not found')

tiny_service_core-0.1.0/src/core/lifespan.py

@@ -0,0 +1,55 @@
+import asyncio
+from collections.abc import AsyncGenerator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from typing import Any, cast
+
+from fastapi import FastAPI
+from starlette.datastructures import State
+
+from . import settings
+
+type CleanUpFunc = Callable[[], Awaitable[None]]
+
+
+def init_cache(state: State, cache_url: str) -> CleanUpFunc:
+    from redis.asyncio.client import Redis
+
+    state.cache = Redis.from_url(cache_url)
+    return cast(CleanUpFunc, state.cache.aclose)
+
+
+def init_db(state: State, db_url: str) -> CleanUpFunc:
+    from sqlalchemy.ext.asyncio import create_async_engine
+
+    state.db = create_async_engine(db_url)
+    return cast(CleanUpFunc, state.db.dispose)
+
+
+def init_http_client(state: State, retries: int) -> CleanUpFunc:
+    from httpx import AsyncClient, AsyncHTTPTransport
+
+    state.http_client = AsyncClient(
+        transport=AsyncHTTPTransport(retries=retries)
+    )
+    return cast(CleanUpFunc, state.http_client.aclose)
+
+
+INIT_FUNCS: dict[str, Callable[[State, Any], CleanUpFunc]] = {
+    'cache_url': init_cache,
+    'db_url': init_db,
+    'http_retries': init_http_client,
+}
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncGenerator[None]:
+    clean_up_funcs: list[CleanUpFunc] = []
+
+    for attr, init_func in INIT_FUNCS.items():
+        value = getattr(settings, attr, None)
+        if value:
+            clean_up_funcs.append(init_func(app.state, value))
+
+    yield
+
+    await asyncio.gather(*(func() for func in clean_up_funcs))

tiny_service_core-0.1.0/src/core/lock.py

@@ -0,0 +1,19 @@
+from redis.asyncio.client import Redis
+from redis.asyncio.lock import Lock as RedisLock
+
+from . import settings
+
+
+class Lock:
+    prefix: str = f'{settings.app_name}:lock'  # type: ignore[has-type]
+    template: str = ''
+    timeout: float | None = None
+
+    # https://github.com/python/mypy/issues/15182
+    def __new__(  # type: ignore[misc]
+        cls,
+        cache: Redis,
+        *args: str,
+    ) -> RedisLock:
+        name = f'{cls.prefix}:{cls.template.format(*args)}'
+        return cache.lock(name, timeout=cls.timeout)

tiny_service_core-0.1.0/src/core/main.py

@@ -0,0 +1,7 @@
+from core import make_app, run
+
+app = make_app()
+
+# for debugging purposes
+if __name__ == '__main__':
+    run(app)

tiny_service_core-0.1.0/src/core/sentry.py

@@ -0,0 +1,20 @@
+from . import settings
+
+
+def init_sentry() -> None:
+    if not settings.sentry_dsn:
+        return
+
+    import logging
+
+    import sentry_sdk
+    from sentry_sdk.integrations.logging import LoggingIntegration
+
+    logging.captureWarnings(True)
+
+    sentry_sdk.init(
+        dsn=settings.sentry_dsn,
+        environment=settings.app_env,
+        traces_sample_rate=settings.traces_sample_rate,
+        integrations=[LoggingIntegration(event_level=logging.WARNING)],
+    )