grelmicro 0.1.0__tar.gz

grelmicro-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Coverage
+.coverage
+coverage.xml
+junittest.xml

grelmicro-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,52 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+default_language_version:
+  python: python3.11
+repos:
+
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.6.0
+  hooks:
+  - id: end-of-file-fixer
+  - id: check-toml
+  - id: check-yaml
+  - id: check-added-large-files
+  - id: trailing-whitespace
+
+- repo: https://github.com/astral-sh/uv-pre-commit
+  rev: 0.5.2
+  hooks:
+    - id: uv-lock
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.7.3
+  hooks:
+    - id: ruff
+      args: [ --fix ]
+    - id: ruff-format
+
+- repo: https://github.com/codespell-project/codespell
+  rev: v2.3.0
+  hooks:
+  - id: codespell
+
+- repo: local
+  hooks:
+  - id: mypy
+    name: mypy
+    description: "Run 'mypy' for static type checking"
+    entry: uv run mypy
+    language: system
+    types_or: [python, pyi]
+    args: ["--ignore-missing-imports", "--scripts-are-modules"]
+    require_serial: true
+  - id: pytest
+    name: pytest
+    description: "Run 'pytest' for testing and code coverage"
+    entry: uv run pytest
+    language: system
+    pass_filenames: false
+
+ci:
+  autofix_commit_msg: 🎨 [pre-commit.ci] Auto format from pre-commit.com hooks
+  autoupdate_commit_msg: ⬆ [pre-commit.ci] pre-commit autoupdate

grelmicro-0.1.0/.vscode/settings.json

@@ -0,0 +1,37 @@
+{
+    "editor.rulers": [88, 100],
+    "files.exclude": {
+      "**/.git": true,
+      "**/.DS_Store": true,
+      "**/Thumbs.db": true,
+      "**/__pycache__": true,
+      "**/.venv": true,
+      "**/.mypy_cache": true,
+      "**/.pytest_cache": true,
+      "**/.ruff_cache": true,
+      ".coverage": true,
+    },
+    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+    "python.terminal.activateEnvInCurrentTerminal": true,
+    "python.terminal.activateEnvironment": true,
+
+    "[python]": {
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": {
+          "source.fixAll": "explicit",
+          "source.organizeImports": "explicit"
+        },
+        "editor.defaultFormatter": "charliermarsh.ruff"
+      },
+      "mypy-type-checker.importStrategy": "fromEnvironment",
+
+      "python.testing.pytestEnabled": true,
+      "python.testing.unittestEnabled": false,
+      "python.testing.pytestArgs": [
+        "tests",
+        "--no-cov"
+      ],
+      "python.analysis.inlayHints.pytestParameters": true,
+      "files.trimTrailingWhitespace": true,
+      "terminal.integrated.scrollback": 10000,
+}

grelmicro-0.1.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.3
+Name: grelmicro
+Version: 0.1.0
+Summary: Grelmicro is a tool-kit designed to streamline the development cloud-native applications with FastAPI.
+Author-email: Loïc Gremaud <grelinfo@gmail.com>
+License: MIT
+Classifier: Development Status :: 1 - Planning
+Classifier: Environment :: Web Environment
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Pydantic
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+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
+Requires-Python: >=3.11
+Requires-Dist: anyio>=4.0.0
+Requires-Dist: fast-depends>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: cli
+Requires-Dist: typer>=0.12.3; extra == 'cli'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.30.0; extra == 'postgres'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# Grelmicro
+
+Grelmicro is a tool-kit designed to streamline the development cloud-native applications with FastAPI.

grelmicro-0.1.0/README.md

@@ -0,0 +1,3 @@
+# Grelmicro
+
+Grelmicro is a tool-kit designed to streamline the development cloud-native applications with FastAPI.

grelmicro-0.1.0/docs/sync/leaderelection.md

@@ -0,0 +1,6 @@
+# Leader Election
+
+It is using a distributed lock in order to guarantee that only one worker is the leader at any given time.
+
+It needs to be started as a background task that runs indefinitely and is responsible for acquiring and renewing
+the distributed lock. The lock is automatically released when the task is cancelled or stopped.

grelmicro-0.1.0/docs/sync/lock.md

@@ -0,0 +1,12 @@
+# Lock
+
+Specifications:
+- Async: The lock must be acquired and released asynchronously.
+- Distributed: The lock must be distributed across multiple workers.
+- Reentrant: The lock must allow the same token to acquire it multiple times to extend the lease.
+- Expiring: The lock must have a timeout to auto-release after an interval to prevent deadlocks.
+- Non-blocking: Lock operations must not block the async event loop.
+- Vendor-agnostic: Must support multiple backends (Redis, Postgres, ConfigMap, etc.).
+
+Notes:
+- Not Thread-Safe: This lock is not thread-safe. It is designed to be used in async tasks within the same event loop.

grelmicro-0.1.0/docs/sync.md

@@ -0,0 +1 @@
+# Synchronization Primitives Module

grelmicro-0.1.0/docs/task.md

@@ -0,0 +1 @@
+# Task Module

grelmicro-0.1.0/examples/single_file_app.py

@@ -0,0 +1,116 @@
+"""Example of a single file app with FastAPI, Grelmicro tasks, locks, and leader election."""
+
+import time
+from contextlib import asynccontextmanager
+from typing import Annotated
+
+import anyio
+import typer
+from fast_depends import Depends
+from fastapi import FastAPI
+
+from grelmicro.backends.memory import MemoryLockBackend
+from grelmicro.sync.leaderelection import LeaderElection
+from grelmicro.sync.lock import LeasedLock
+from grelmicro.task import TaskManager
+
+backend = MemoryLockBackend()
+task = TaskManager()
+
+
+@asynccontextmanager
+async def lifespan(app):
+    async with backend, task:
+        typer.echo("App started")
+        yield
+        typer.echo("App stopped")
+
+
+app = FastAPI(lifespan=lifespan)
+
+leased_lock_10sec = LeasedLock(
+    name="leased_lock_10sec",
+    lease_duration=10,
+    backend=backend,
+)
+leased_lock_5sec = LeasedLock(
+    name="leased_lock_5sec",
+    lease_duration=5,
+    backend=backend,
+)
+
+leader_election = LeaderElection(name="simple-leader", backend=backend)
+
+task.add_task(leader_election)
+
+
+@task.interval(interval=1)
+def sync_func_with_no_param():
+    typer.echo("sync_with_no_param")
+
+
+@task.interval(interval=2)
+async def async_func_with_no_param():
+    typer.echo("async_with_no_param")
+
+
+def sync_dependency():
+    return "sync_dependency"
+
+
+@task.interval(interval=3)
+def sync_func_with_sync_dependency(
+    sync_dependency: Annotated[str, Depends(sync_dependency)],
+):
+    typer.echo(sync_dependency)
+
+
+async def async_dependency():
+    yield "async_with_async_dependency"
+
+
+@task.interval(interval=4)
+async def async_func_with_async_dependency(
+    async_dependency: Annotated[str, Depends(async_dependency)],
+):
+    typer.echo(async_dependency)
+
+
+@task.interval(interval=15, sync=leased_lock_10sec)
+def sync_func_with_leased_lock_10sec():
+    typer.echo("sync_func_with_leased_lock_10sec")
+    time.sleep(9)
+
+
+@task.interval(interval=15, sync=leased_lock_10sec)
+async def async_func_with_leased_lock_10sec():
+    typer.echo("async_func_with_leased_lock_10sec")
+    await anyio.sleep(9)
+
+
+@task.interval(interval=15, sync=leased_lock_5sec)
+def sync_func_with_sync_dependency_and_leased_lock_5sec(
+    sync_dependency: Annotated[str, Depends(sync_dependency)],
+):
+    typer.echo(sync_dependency)
+    time.sleep(4)
+
+
+@task.interval(interval=15, sync=leased_lock_5sec)
+async def async_func_with_async_dependency_and_leased_lock_5sec(
+    async_dependency: Annotated[str, Depends(async_dependency)],
+):
+    typer.echo(async_dependency)
+    await anyio.sleep(4)
+
+
+@task.interval(interval=15, sync=leader_election)
+def sync_func_with_leader_election():
+    typer.echo("sync_func_with_leader_election")
+    time.sleep(30)
+
+
+@task.interval(interval=15, sync=leader_election)
+async def async_func_with_leader_election():
+    typer.echo("async_func_with_leader_election")
+    await anyio.sleep(30)

grelmicro-0.1.0/grelmicro/__init__.py

@@ -0,0 +1 @@
+"""Grelmicro Cloud-Native Toolkit."""

grelmicro-0.1.0/grelmicro/abc/__init__.py

@@ -0,0 +1 @@
+"""Grelmicro Abstract Base Classes or Protocols Module."""

grelmicro-0.1.0/grelmicro/abc/lock.py

@@ -0,0 +1,95 @@
+"""Grelmicro Lock API."""
+
+from types import TracebackType
+from typing import Annotated, Protocol, Self
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict
+from typing_extensions import Doc
+
+from grelmicro.abc.synchronization import Synchronization
+
+
+class BaseLockConfig(BaseModel):
+    """Base Lock Config."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: Annotated[
+        str,
+        Doc("The name of the resource to lock."),
+    ]
+    worker: Annotated[
+        str | UUID,
+        Doc("The worker identity.\n\nBy default, use a UUIDv1."),
+    ]
+
+
+class BaseLock(Synchronization, Protocol):
+    """Base Lock Protocol."""
+
+    async def __aenter__(self) -> Self:
+        """Acquire the lock.
+
+        Raises:
+            LockAcquireError: If the lock cannot be acquired due to an error on the backend.
+        """
+        ...
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Release the lock.
+
+        Raises:
+            LockNotOwnedError: If the lock is not owned by the current token.
+            LockReleaseError: If the lock cannot be released due to an error on the backend.
+
+        """
+        ...
+
+    @property
+    def config(self) -> BaseLockConfig:
+        """Return the config."""
+        ...
+
+    async def acquire(self) -> None:
+        """Acquire the lock.
+
+        Raises:
+            LockAcquireError: If the lock cannot be acquired due to an error on the backend.
+
+        """
+        ...
+
+    async def acquire_nowait(self) -> None:
+        """
+        Acquire the lock, without blocking.
+
+        Raises:
+            WouldBlock: If the lock cannot be acquired without blocking.
+            LockAcquireError: If the lock cannot be acquired due to an error on the backend.
+
+        """
+        ...
+
+    async def release(self) -> None:
+        """Release the lock.
+
+        Raises:
+            LockNotOwnedError: If the lock is not owned by the current token.
+            LockReleaseError: If the lock cannot be released due to an error on the backend.
+
+        """
+        ...
+
+    async def locked(self) -> bool:
+        """Check if the lock is currently held."""
+        ...
+
+    async def owned(self) -> bool:
+        """Check if the lock is currently held by the current token."""
+        ...

grelmicro-0.1.0/grelmicro/abc/lockbackend.py

@@ -0,0 +1,84 @@
+"""Grelmicro Lock Backend API."""
+
+from types import TracebackType
+from typing import Protocol, Self
+
+
+class LockBackend(Protocol):
+    """Lock Backend Protocol.
+
+    This is the low level API for the distributed lock backend that is platform agnostic.
+    """
+
+    async def __aenter__(self) -> Self:
+        """Open the lock backend."""
+        ...
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Close the lock backend."""
+        ...
+
+    async def acquire(self, *, name: str, token: str, duration: float) -> bool:
+        """Acquire the lock.
+
+        Args:
+            name: The name of the lock.
+            token: The token to acquire the lock.
+            duration: The duration in seconds to hold the lock.
+
+        Returns:
+            True if the lock is acquired, False if the lock is already acquired by another token.
+
+        Raises:
+            Exception: Any exception can be raised if the lock cannot be acquired.
+        """
+        ...
+
+    async def release(self, *, name: str, token: str) -> bool:
+        """Release a lock.
+
+        Args:
+            name: The name of the lock.
+            token: The token to release the lock.
+
+        Returns:
+            True if the lock was released, False otherwise.
+
+        Raises:
+            Exception: Any exception can be raised if the lock cannot be released.
+        """
+        ...
+
+    async def locked(self, *, name: str) -> bool:
+        """Check if the lock is acquired.
+
+        Args:
+            name: The name of the lock.
+
+        Returns:
+            True if the lock is acquired, False otherwise.
+
+        Raises:
+            Exception: Any exception can be raised if the lock status cannot be checked.
+        """
+        ...
+
+    async def owned(self, *, name: str, token: str) -> bool:
+        """Check if the lock is owned.
+
+        Args:
+            name: The name of the lock.
+            token: The token to check.
+
+        Returns:
+            True if the lock is owned by the token, False otherwise.
+
+        Raises:
+            Exception: Any exception can be raised if the lock status cannot be checked.
+        """
+        ...

grelmicro-0.1.0/grelmicro/abc/synchronization.py

@@ -0,0 +1,21 @@
+"""Grelmicro Synchronization API."""
+
+from types import TracebackType
+from typing import Protocol, Self, runtime_checkable
+
+
+@runtime_checkable
+class Synchronization(Protocol):
+    """Synchronization Primitive Protocol."""
+
+    async def __aenter__(self) -> Self:
+        """Enter the synchronization primitive."""
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> bool | None:
+        """Exit the synchronization primitive."""
+        ...

grelmicro-0.1.0/grelmicro/abc/task.py

@@ -0,0 +1,31 @@
+"""Task API."""
+
+from typing import Protocol
+
+from anyio import TASK_STATUS_IGNORED
+from anyio.abc import TaskStatus
+from typing_extensions import runtime_checkable
+
+
+@runtime_checkable
+class Task(Protocol):
+    """Task Protocol.
+
+    A task that runs in background in the async event loop.
+    """
+
+    @property
+    def name(self) -> str:
+        """Name to uniquely identify the task."""
+        ...
+
+    async def __call__(
+        self,
+        *,
+        task_status: TaskStatus[None] = TASK_STATUS_IGNORED,
+    ) -> None:
+        """Run the task.
+
+        This is the entry point of the task to be run in the async event loop.
+        """
+        ...

grelmicro-0.1.0/grelmicro/backends/__init__.py

@@ -0,0 +1,5 @@
+"""Grelmicro Backends Module.
+
+This module provides technology-agnostic, low-level implementations for various database and broker
+systems.
+"""

grelmicro-0.1.0/grelmicro/backends/memory/__init__.py

@@ -0,0 +1,9 @@
+"""Memory Backend.
+
+This backend is used for testing purposes and should not be used in production. Memory backends are
+not persistent and are not shared between different workers.
+"""
+
+from grelmicro.backends.memory.lock import MemoryLockBackend
+
+__all__ = ["MemoryLockBackend"]

grelmicro-0.1.0/grelmicro/backends/memory/lock.py

@@ -0,0 +1,72 @@
+"""Memory Lock Backend."""
+
+from time import monotonic
+from types import TracebackType
+from typing import Annotated, Self
+
+from typing_extensions import Doc
+
+from grelmicro.abc.lockbackend import LockBackend
+from grelmicro.backends.registry import loaded_backends
+
+
+class MemoryLockBackend(LockBackend):
+    """Memory Lock Backend.
+
+    This is not a backend with a real distributed lock. It is a local lock that can be used for
+    testing purposes or for locking operations that are executed in the same AnyIO event loop.
+    """
+
+    def __init__(
+        self,
+        *,
+        auto_register: Annotated[
+            bool,
+            Doc("Automatically register the lock backend in the backend registry."),
+        ] = True,
+    ) -> None:
+        """Initialize the lock backend."""
+        self._locks: dict[str, tuple[str | None, float]] = {}
+        if auto_register:
+            loaded_backends["lock"] = self
+
+    async def __aenter__(self) -> Self:
+        """Enter the lock backend."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Exit the lock backend."""
+        self._locks.clear()
+
+    async def acquire(self, *, name: str, token: str, duration: float) -> bool:
+        """Acquire the lock."""
+        current_token, expire_at = self._locks.get(name, (None, 0))
+        if current_token is None or current_token == token or expire_at < monotonic():
+            self._locks[name] = (token, monotonic() + duration)
+            return True
+        return False
+
+    async def release(self, *, name: str, token: str) -> bool:
+        """Release the lock."""
+        current_token, expire_at = self._locks.get(name, (None, 0))
+        if current_token == token and expire_at >= monotonic():
+            del self._locks[name]
+            return True
+        if current_token and expire_at < monotonic():
+            del self._locks[name]
+        return False
+
+    async def locked(self, *, name: str) -> bool:
+        """Check if the lock is acquired."""
+        current_token, expire_at = self._locks.get(name, (None, 0))
+        return current_token is not None and expire_at >= monotonic()
+
+    async def owned(self, *, name: str, token: str) -> bool:
+        """Check if the lock is owned."""
+        current_token, expire_at = self._locks.get(name, (None, 0))
+        return current_token == token and expire_at >= monotonic()

grelmicro-0.1.0/grelmicro/backends/postgres/__init__.py

@@ -0,0 +1,8 @@
+"""PostgreSQL Backend.
+
+To use this backend, please install `grelmicro[postgres]` or manually install `asyncpg`.
+"""
+
+from grelmicro.backends.postgres.lock import PostgresLockBackend
+
+__all__ = ["PostgresLockBackend"]