nx-framework 0.0.3__tar.gz

nx_framework-0.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Martin Wacker
+
+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.

nx_framework-0.0.3/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: nx-framework
+Version: 0.0.3
+Summary: Low-level FastAPI, asyncpg and Redis framework used by Nebula Broadcast and other projects.
+Author-email: Martin Wacker <martas@imm.cz>
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: aioshutil>=1.5
+Requires-Dist: asyncpg>=0.30.0
+Requires-Dist: fastapi>=0.115.8
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pydantic-settings>=2.7.1
+Requires-Dist: pydantic[email]>=2.10.6
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: redis>=5.2.1
+Requires-Dist: shortuuid>=1.0.13
+Requires-Dist: unidecode>=1.3.8
+Dynamic: license-file
+
+# nx
+Very opinionated set of tools

nx_framework-0.0.3/README.md

@@ -0,0 +1,2 @@
+# nx
+Very opinionated set of tools

nx_framework-0.0.3/nx/__init__.py

@@ -0,0 +1,15 @@
+__all__ = [
+    "coalesce",
+    "config",
+    "db",
+    "initialize",
+    "log",
+    "redis",
+]
+
+from nx.config import config
+from nx.db import db
+from nx.initialize import initialize
+from nx.logging import logger as log
+from nx.redis import redis
+from nx.utils import coalesce

nx_framework-0.0.3/nx/__main__.py

@@ -0,0 +1,110 @@
+"""nx cli
+======
+
+This entrypoint is used to run nx in a development environment.
+It is used to test various features of nx and to run the vanilla server
+without any modifications.
+
+It is not intended to be used in production.
+"""
+
+import asyncio
+import os
+import signal
+import subprocess
+import sys
+from typing import Any
+
+import nx
+from nx.version import __version__
+
+nx.initialize(standalone=True)
+
+
+GUNICORN_PID_FILE = "/tmp/gunicorn.pid"  # noqa: S108
+
+
+def version() -> None:
+    """Show the version."""
+    print(__version__, end="")  # noqa: T201
+
+
+def run(*args: Any) -> None:
+    """Run a command."""
+    nx.log.info(f"Running command, {args}")
+
+
+def serve() -> None:
+    """Run the server."""
+    cmd = [
+        "gunicorn",
+        "--bind",
+        f":{nx.config.server_port}",
+        "--reload",
+        "--worker-class",
+        "uvicorn_worker.UvicornWorker",
+        "--max-requests",
+        "1000",
+        "--log-level",
+        "warning",
+        "--pid",
+        GUNICORN_PID_FILE,
+        "nx.server.app:app",
+    ]
+
+    process = subprocess.Popen(cmd)  # noqa: S603
+    gunicorn_pid = process.pid
+
+    def handle_sigterm(signum, frame) -> None:  # type: ignore[no-untyped-def]
+        _ = signum, frame
+        nx.log.warning("Received SIGTERM")
+        os.kill(gunicorn_pid, signal.SIGTERM)
+
+    def handle_sigint(signum, frame) -> None:  # type: ignore[no-untyped-def]
+        _ = signum, frame
+        nx.log.warning("Received SIGINT")
+        os.kill(gunicorn_pid, signal.SIGINT)
+
+    signal.signal(signal.SIGTERM, handle_sigterm)
+    signal.signal(signal.SIGINT, handle_sigint)
+
+    process.wait()
+    nx.log.info("Gunicorn process terminated.")
+
+
+def reload() -> None:
+    """Reload the server by sending SIGHUP to Gunicorn."""
+    if os.path.exists(GUNICORN_PID_FILE):
+        with open(GUNICORN_PID_FILE) as f:
+            try:
+                gunicorn_pid = int(f.read().strip())
+                os.kill(gunicorn_pid, signal.SIGHUP)
+                nx.log.info(f"Sent SIGHUP to Gunicorn (PID: {gunicorn_pid}).")
+            except ValueError:
+                nx.log.error("Invalid PID in Gunicorn PID file.")
+            except ProcessLookupError:
+                nx.log.error("Gunicorn process not found.")
+    else:
+        nx.log.error("Gunicorn PID file not found.")
+
+
+async def debug() -> None:
+    print(nx.config.model_dump_json(indent=2, exclude_unset=True))  # noqa: T201
+    res = await nx.db.fetch("SELECT * FROM config")
+    print(res)  # noqa: T201
+
+
+if __name__ == "__main__":
+    if "version" in sys.argv:
+        version()
+    elif "run" in sys.argv:
+        run(sys.argv[2:])
+    elif "serve" in sys.argv:
+        serve()
+    elif "reload" in sys.argv:
+        reload()
+    elif "debug" in sys.argv:
+        asyncio.run(debug())
+    else:
+        nx.log.error("Invalid command. Use 'version', 'run', 'serve', or 'reload'.")
+        sys.exit(1)

nx_framework-0.0.3/nx/config/__init__.py

@@ -0,0 +1,55 @@
+__all__ = [
+    "ConfigModel",
+    "ConfigProxy",
+    "config",
+]
+
+import os
+from typing import Any, Generic, TypeVar, cast
+
+from dotenv import load_dotenv
+from pydantic import BaseModel
+
+from .config_model import ConfigModel
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class ConfigProxy(Generic[T]):
+    _instance: "ConfigProxy[T] | None" = None
+    _config_model: type[T]
+    _fields: set[str]
+    _config: BaseModel | None = None
+
+    def __new__(cls, *args: Any, **kwargs: Any) -> "ConfigProxy[T]":
+        _ = args, kwargs
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def initialize(self, config_model: type[T], env_prefix: str) -> None:
+        self._config_model = config_model
+        self._fields = set(config_model.model_fields)
+        self._env_prefix = env_prefix
+
+        full_env_prefix = f"{env_prefix}_".lower()
+        load_dotenv()
+        env_data = {}
+        for key, value in dict(os.environ).items():
+            if not key.lower().startswith(full_env_prefix):
+                continue
+
+            fkey = key.lower().removeprefix(full_env_prefix)
+            if fkey in self._fields:
+                env_data[fkey] = value
+
+        self._config = self._config_model(**env_data)
+
+    def __getattr__(self, key: str) -> Any:
+        if not self._config:
+            raise AttributeError("Config not initialized. Call initialize() first.")
+        return getattr(self._config, key)
+
+
+_config_proxy = ConfigProxy()  # type: ignore[var-annotated]
+config = cast("ConfigModel", _config_proxy)

nx_framework-0.0.3/nx/config/config_model.py

@@ -0,0 +1,82 @@
+from typing import Any, Self, cast
+from urllib.parse import urlparse
+
+from pydantic import BaseModel, PostgresDsn, RedisDsn, field_validator, model_validator
+
+from .fields import (
+    LogLevel,
+    LogMode,
+    PostgresHost,
+    PostgresName,
+    PostgresPassword,
+    PostgresPort,
+    PostgresUser,
+    ServerPort,
+)
+
+
+class ConfigModel(BaseModel):
+    log_level: LogLevel = "DEBUG"
+    log_mode: LogMode = "text"
+    log_context: bool = True
+    server_host: str = "0.0.0.0"
+    server_port: ServerPort = 8765
+    postgres_url: PostgresDsn = PostgresDsn("postgresql://nx:nx@postgres:5432/nx")
+    redis_url: RedisDsn = RedisDsn("redis://redis")
+
+    # database connection overrides
+    # The folowing fields are used to override the default connection settings
+    # provided by POSTGRES_URL
+
+    postgres_host: PostgresHost = None
+    postgres_port: PostgresPort = None
+    postgres_name: PostgresName = None
+    postgres_user: PostgresUser = None
+    postgres_password: PostgresPassword = None
+
+    @field_validator("log_level", mode="before")
+    @classmethod
+    def validate_log_level(cls, v: Any) -> LogLevel:
+        assert isinstance(v, str), "Log level must be a string"
+        return cast("LogLevel", v.upper())
+
+    @model_validator(mode="after")
+    def construct_final_postgres_url(self) -> Self:
+        """Synchronize the postgres_url with the individual fields."""
+        parsed = urlparse(str(self.postgres_url))
+        # Extract the relevant components
+        user = parsed.username if self.postgres_user is None else self.postgres_user
+        password = (
+            parsed.password
+            if self.postgres_password is None
+            else self.postgres_password
+        )
+        host = parsed.hostname if self.postgres_host is None else self.postgres_host
+        port = parsed.port or 5432 if self.postgres_port is None else self.postgres_port
+        database = parsed.path[1:] if self.postgres_name is None else self.postgres_name
+
+        # rebuild the URL with the overrides
+
+        self.postgres_url = PostgresDsn.build(
+            scheme="postgresql",
+            username=user,
+            password=password,
+            host=host,
+            port=port,
+            path=database,
+        )
+
+        # and populate the fields again, so all values are in sync
+
+        parsed = urlparse(str(self.postgres_url))
+
+        self.postgres_host = parsed.hostname
+        self.postgres_port = parsed.port or 5432
+        self.postgres_name = parsed.path[1:]
+        self.postgres_user = parsed.username
+        self.postgres_password = parsed.password
+
+        return self
+
+    def initialize(self, **kwargs: Any) -> None:
+        _ = kwargs

nx_framework-0.0.3/nx/config/fields.py

@@ -0,0 +1,79 @@
+from typing import Annotated, Literal
+
+from pydantic import Field
+
+LogMode = Annotated[
+    Literal["text", "json"],
+    Field(
+        title="Log mode",
+        description="The log mode for the server",
+        examples=["text"],
+    ),
+]
+
+LogLevel = Annotated[
+    Literal["CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG", "TRACE"],
+    Field(
+        title="Log Level",
+        description="The log level for the server",
+        examples=["INFO"],
+    ),
+]
+
+ServerPort = Annotated[
+    int,
+    Field(
+        title="Port",
+        description="The port the server will listen on",
+        examples=[8765],
+        ge=0,
+        le=65535,
+    ),
+]
+
+PostgresHost = Annotated[
+    str | None,
+    Field(
+        title="Postgres host",
+        description="Override the default Postgres host",
+        examples=["localhost", "postgres"],
+    ),
+]
+
+PostgresPort = Annotated[
+    int | None,
+    Field(
+        title="Postgres port",
+        description="Override the default Postgres port provided by POSTGRES_URL",
+        examples=[5432],
+        ge=0,
+        le=65535,
+    ),
+]
+
+PostgresName = Annotated[
+    str | None,
+    Field(
+        title="Postgres database name",
+        description="Override the default Postgres database name from POSTGRES_URL",
+        examples=["nx"],
+    ),
+]
+
+PostgresUser = Annotated[
+    str | None,
+    Field(
+        title="Postgres user",
+        description="Override the default Postgres user from POSTGRES_URL",
+        examples=["nx"],
+    ),
+]
+
+PostgresPassword = Annotated[
+    str | None,
+    Field(
+        title="Postgres password",
+        description="Override the default Postgres password from POSTGRES_URL",
+        examples=["nx"],
+    ),
+]

nx_framework-0.0.3/nx/db.py

@@ -0,0 +1,185 @@
+__all__ = ["db"]
+
+import asyncio
+import sys
+import uuid
+from collections.abc import AsyncGenerator, AsyncIterator
+from contextlib import asynccontextmanager
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, Any
+
+import asyncpg
+
+from nx.config import config
+from nx.logging import logger
+from nx.utils import json_dumps, json_loads, normalize_uuid
+
+if TYPE_CHECKING:
+    from asyncpg.pool import PoolConnectionProxy
+    from asyncpg.prepared_stmt import PreparedStatement
+
+_current_connection: ContextVar["PoolConnectionProxy | None"] = ContextVar(  # type: ignore[type-arg]
+    "_current_connection", default=None
+)
+
+_connection_lock = asyncio.Lock()
+
+
+class DB:
+    _instance: "DB | None" = None
+    _pool: asyncpg.pool.Pool | None = None  # type: ignore[type-arg]
+
+    def __new__(cls, *args: Any, **kwargs: Any) -> "DB":
+        _ = args, kwargs
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    async def _init_connection(self, conn) -> None:  # type: ignore[no-untyped-def]
+        await conn.set_type_codec(
+            "jsonb",
+            encoder=json_dumps,
+            decoder=json_loads,
+            schema="pg_catalog",
+        )
+        await conn.set_type_codec(
+            "uuid",
+            encoder=str,
+            decoder=lambda x: uuid.UUID(x).hex,
+            schema="pg_catalog",
+        )
+        await conn.set_type_codec(
+            "uuid",
+            encoder=lambda x: normalize_uuid(x, True),
+            decoder=lambda x: normalize_uuid(x, True),
+            schema="pg_catalog",
+        )
+
+    async def _connect(self) -> None:
+        """Create a Postgres connection pool."""
+        async with _connection_lock:
+            if self._pool is not None:
+                return  # Double check
+
+            try:
+                self._pool = await asyncpg.create_pool(
+                    str(config.postgres_url),
+                    init=self._init_connection,
+                )
+            except Exception as e:
+                logger.error(f"Failed to connect to the database: {e}")
+                logger.error(
+                    f"Unrecoverable error while "
+                    f"connecting to '{config.postgres_url}'. Exiting."
+                )
+                sys.exit(1)
+
+    @asynccontextmanager
+    async def acquire(
+        self,
+        *,
+        timeout: int | None = None,  # noqa: ASYNC109
+        force_new: bool = False,
+    ) -> AsyncIterator["PoolConnectionProxy"]:  # type: ignore[type-arg]
+        """Resolve the current connection from the contextvar or acquire a new one.
+        If the connection is not available, create a new one.
+        """
+        conn = _current_connection.get()
+        if not force_new and conn is not None:
+            yield conn
+            return
+
+        if self._pool is None:
+            await self._connect()
+        assert self._pool is not None, "Database pool is not initialized"
+
+        try:
+            connection_proxy = await self._pool.acquire(timeout=timeout)
+        except TimeoutError as e:
+            raise ConnectionError("Database pool timeout") from e
+
+        token = _current_connection.set(connection_proxy)
+
+        try:
+            yield connection_proxy
+        finally:
+            _current_connection.reset(token)
+            await self._pool.release(connection_proxy)
+
+    @asynccontextmanager
+    async def transaction(
+        self,
+        timeout: int | None = None,  # noqa: ASYNC109
+        force_new: bool = False,
+    ) -> AsyncIterator["PoolConnectionProxy"]:  # type: ignore[type-arg]
+        """Acquire a connection from the pool and manage transaction state."""
+        async with self.acquire(timeout=timeout, force_new=force_new) as connection:
+            if connection.is_in_transaction():
+                yield connection
+            else:
+                async with connection.transaction():
+                    yield connection
+
+    @property
+    def is_in_transaction(self) -> bool:
+        """Check if the current connection is in a transaction."""
+        conn = _current_connection.get()
+        if conn is None:
+            return False
+        return conn.is_in_transaction()
+
+    async def execute(self, query: str, *args: Any) -> str:
+        """Exeuute a query and return the status."""
+        async with self.acquire() as conn:
+            return await conn.execute(query, *args)
+
+    async def executemany(self, query: str, *args: Any) -> None:
+        """Execute a query multiple times and return the result."""
+        async with self.acquire() as conn:
+            await conn.executemany(query, *args)
+
+    async def prepare(self, query: str, *args: Any) -> "PreparedStatement":  # type: ignore[type-arg]
+        """Fetch a query and return the result."""
+        async with self.acquire() as conn:
+            if not conn.is_in_transaction():
+                raise RuntimeError("Transaction not started")
+            return await conn.prepare(query, *args)
+
+    async def fetch(self, query: str, *args: Any) -> list[asyncpg.Record]:
+        """Fetch a query and return the result."""
+        async with self.acquire() as conn:
+            return await conn.fetch(query, *args)
+
+    async def fetchrow(self, query: str, *args: Any) -> asyncpg.Record | None:
+        """Fetch a query and return the first result."""
+        async with self.acquire() as conn:
+            return await conn.fetchrow(query, *args)
+
+    async def iterate(
+        self,
+        query: str,
+        *args: Any,
+        timeout: int | None = None,  # noqa: ASYNC109
+    ) -> AsyncGenerator[asyncpg.Record]:
+        """Run a query and yield rows in batches using cursor.fetch()."""
+        if self._pool is None:
+            await self._connect()
+        assert self._pool is not None, "Database pool is not initialized"
+
+        conn = await self._pool.acquire(timeout=timeout)
+
+        try:
+            if not conn.is_in_transaction():
+                async with conn.transaction():
+                    statement = await conn.prepare(query)
+                    async for record in statement.cursor(*args):
+                        yield record
+            else:
+                statement = await conn.prepare(query)
+                async for record in statement.cursor(*args):
+                    yield record
+        finally:
+            await self._pool.release(conn)
+
+
+db = DB()

nx_framework-0.0.3/nx/exceptions.py

@@ -0,0 +1,19 @@
+class BaseNXError(Exception):
+    """Base class for all exceptions raised by the NX library."""
+
+    status = 500
+
+    def __init__(self, detail: str | None = None) -> None:
+        super().__init__(detail)
+        if detail is not None:
+            self.detail = detail
+
+
+class NotFoundError(BaseNXError):
+    status = 404
+    detail = "Not Found"
+
+
+class UnauthorizedError(BaseNXError):
+    status = 401
+    detail = "Unauthorized"

nx_framework-0.0.3/nx/ffmpeg/__init__.py

@@ -0,0 +1,11 @@
+__all__ = [
+    "FFProbeError",
+    "FFmpegAbortedError",
+    "FFmpegError",
+    "FFmpegProgress",
+    "ffmpeg",
+    "ffprobe",
+]
+
+from .ffmpeg import FFmpegAbortedError, FFmpegError, FFmpegProgress, ffmpeg
+from .ffprobe import FFProbeError, ffprobe