nexus-kit 0.4.0__py3-none-any.whl

nexus_kit/__init__.py

@@ -0,0 +1,11 @@
+from nexus_kit.interfaces.application import ApplicationInterface
+from nexus_kit.interfaces.container import ContainerInterface
+from nexus_kit.interfaces.environment import EnvironmentInterface
+from nexus_kit.root import Root
+
+__all__ = [
+    "ApplicationInterface",
+    "ContainerInterface",
+    "EnvironmentInterface",
+    "Root",
+]

nexus_kit/cli.py

@@ -0,0 +1,295 @@
+import sys
+from importlib.metadata import version
+from pathlib import Path
+
+
+_TEMPLATES: dict[str, str] = {
+    "main.py": """\
+import faulthandler
+
+from app.application import Application
+from app.config.di import DI_CONFIG
+from app.config.environment import Environment
+from nexus_kit import Root
+from nexus_kit.impl import ContainerInjector
+
+if __name__ == "__main__":
+    faulthandler.enable(all_threads=True)
+
+    env = Environment(Root.external(".env"))
+    container = ContainerInjector(DI_CONFIG)
+    container.set(Environment, env)
+    Application(env, container).run()
+""",
+    "pyproject.toml": """\
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "{{APP_NAME}}"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+    "nexus-kit~={{NEXUS_REF}}",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["app"]
+""",
+    ".gitignore": """\
+.venv/
+__pycache__/
+*.pyc
+.env
+dist/
+build/
+*.spec
+.pytest_cache/
+.ruff_cache/
+.idea/
+""",
+    ".env": """\
+APP_NAME={{APP_NAME}}
+TICK_SECONDS=0.7
+RUN_SECONDS=3
+""",
+    "app/__init__.py": "",
+    "app/application.py": """\
+import time
+
+from nexus_kit.impl import ServiceRunner
+from nexus_kit.interfaces import ApplicationInterface, ContainerInterface
+
+from app.config.environment import Environment
+from app.services.ticker import Ticker
+
+
+class Application(ApplicationInterface):
+    SERVICES = [Ticker]  # startup order; stopped in reverse on any exit
+
+    def __init__(self, environment: Environment, container: ContainerInterface) -> None:
+        self._env = environment
+        self._container = container
+
+    def run(self) -> None:
+        with ServiceRunner(self._container, self.SERVICES):
+            print(f"[{self._env.APP_NAME}] running for {self._env.RUN_SECONDS}s — Ctrl+C to stop early")
+            try:
+                # Replace with your main loop: server.wait(), app.exec(), game loop
+                time.sleep(self._env.RUN_SECONDS)
+            except KeyboardInterrupt:
+                pass
+        # leaving the block stopped the ticker and joined its thread — nothing orphaned
+""",
+    "app/config/__init__.py": "",
+    "app/config/di.py": """\
+# Register your swappable seams here: {Interface: Implementation}
+from app.services.console_reporter import ConsoleReporter
+from app.services.reporter_interface import ReporterInterface
+
+DI_CONFIG = {
+    ReporterInterface: ConsoleReporter,
+}
+""",
+    "app/config/environment.py": """\
+from pathlib import Path
+
+from injector import singleton
+
+from nexus_kit.interfaces import EnvironmentInterface
+
+
+@singleton
+class Environment(EnvironmentInterface):
+    # Add your config fields here — they are read from .env automatically
+    APP_NAME: str = "{{APP_NAME}}"
+    TICK_SECONDS: float = 0.7
+    RUN_SECONDS: float = 3.0
+
+    def __init__(self, env_path: Path) -> None:
+        super().__init__(_env_file=env_path)
+""",
+    "app/services/__init__.py": "",
+    "app/services/ticker.py": """\
+import threading
+
+from injector import inject, singleton
+
+from nexus_kit.interfaces import ServiceInterface
+
+from app.config.environment import Environment
+from app.services.reporter_interface import ReporterInterface
+
+
+# The worker-thread skeleton every long-lived app ends up hand-rolling:
+# stop Event + bounded join. Swap the loop body for your poller, device
+# monitor or queue drainer. Not in DI_CONFIG: a concrete @singleton
+# service resolves itself; its dependencies arrive via @inject.
+@singleton
+class Ticker(ServiceInterface):
+    @inject
+    def __init__(self, env: Environment, reporter: ReporterInterface) -> None:
+        self._interval = env.TICK_SECONDS
+        self._reporter = reporter
+        self._ticks = 0
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+
+    def start(self) -> None:
+        print(f"[ticker] started (every {self._interval}s)")
+        self._thread = threading.Thread(target=self._run, name="ticker", daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:  # must be idempotent
+        self._stop_event.set()
+        if self._thread is not None:
+            self._thread.join(timeout=5.0)
+            self._thread = None
+            print(f"[ticker] stopped after {self._ticks} ticks")
+
+    def _run(self) -> None:
+        while not self._stop_event.wait(self._interval):
+            self._ticks += 1
+            self._reporter.report(self._ticks)
+""",
+    "app/services/reporter_interface.py": """\
+from abc import ABC, abstractmethod
+
+
+class ReporterInterface(ABC):
+    @abstractmethod
+    def report(self, tick: int) -> None: ...
+""",
+    "app/services/console_reporter.py": """\
+from injector import singleton
+
+from app.services.reporter_interface import ReporterInterface
+
+
+@singleton
+class ConsoleReporter(ReporterInterface):
+    def report(self, tick: int) -> None:
+        print(f"tick #{tick}")
+""",
+    "CLAUDE.md": """\
+# CLAUDE.md
+
+Guidance for Claude Code (and other AI assistants) working in this repository.
+
+This app is built on the **nexus** framework. Its API, the bootstrap pattern and the
+gotchas are in `.ai/nexus-kit.md` — read it before touching DI, config or the composition
+root (`app/config/di.py`). Keep this file thin: put engineering discipline in `.ai/`
+and only repo-specific facts here.
+""",
+    ".ai/nexus-kit.md": """\
+# Nexus — quick reference (how to build an app on this framework)
+
+Compact cheat-sheet for the **nexus** framework (PyPI dist `nexus-kit`, imports as
+`nexus`; github.com/Astislav/nexus), pinned to **~={{NEXUS_REF}}**. For depth: the
+framework's own `.ai/guide.md`, or the installed source at
+`.venv/Lib/site-packages/nexus_kit/`.
+
+## What it is
+
+A tiny application bootstrap: a **DI container** (wraps `injector`) + a **config base**
+(wraps `pydantic-settings`) + **logging** + **`Root`** (paths) + the `nexus-kit new` CLI.
+No domain, HTTP or DB.
+
+## Public API
+
+| Symbol | Import | Role |
+|---|---|---|
+| `ApplicationInterface` | `nexus_kit.interfaces` | run contract: `__init__(env, container)` + `run()` |
+| `ContainerInterface` | `nexus_kit.interfaces` | DI contract: `get(cls)`, `set(cls, value)` |
+| `EnvironmentInterface` | `nexus_kit.interfaces` | typed config base (pydantic BaseSettings + `@singleton`) |
+| `ServiceInterface` | `nexus_kit.interfaces` | long-lived service: `start()`/`stop()` (sync or async, `stop()` idempotent) |
+| `Root` | `nexus` | paths: `Root.internal(*p)` (bundled assets) / `Root.external(*p)` (files next to the exe — or next to `main.py` in dev: `.env`, db) |
+| `ContainerInjector` | `nexus_kit.impl` | concrete container; constructor takes `DI_CONFIG: dict[Type, Impl]` |
+| `ServiceRunner` | `nexus_kit.impl` | ordered start / guaranteed reverse-order stop: `with`/`async with ServiceRunner(container, SERVICES)` around the app body |
+| `NamedLogger` / `StdoutHandler` / `LogFormatter` | `nexus_kit.logging` | DI-injectable logging |
+
+**Gotcha:** `@singleton`, `@inject`, `Injector` come from the `injector` package, NOT
+from nexus-kit (`from injector import inject, singleton`). Nexus never re-exports them.
+
+**Dependencies:** `injector` and `pydantic-settings` are core dependencies of nexus —
+no extras, everything works out of the box.
+
+## Bootstrap (`main.py`)
+
+```python
+env = Environment(Root.external(".env"))   # 1. config
+container = ContainerInjector(DI_CONFIG)   # 2. wiring
+container.set(Environment, env)            # 3. env is NOT auto-bound — bind it by hand
+Application(env, container).run()          # 4. start
+```
+
+- `DI_CONFIG` (composition root) is a `dict{Interface: Impl}`; register only swappable
+  seams — `@singleton @inject` services are built by the container from their constructors.
+- **Do not bind a class to itself.** Interfaces carry the `Interface` suffix; implementations don't.
+- Long-lived services are `@singleton`, dependencies come via an `@inject` constructor.
+- Logging: subclass `NamedLogger` (class attr `name`), inject by type; change the format
+  by rebinding `LogFormatter` in `DI_CONFIG`.
+
+## Lifecycle (`ServiceRunner`)
+
+Long-lived services implement `ServiceInterface` — `start()`/`stop()`, sync or async,
+`stop()` must be idempotent. `Application` lists them in `SERVICES` (startup order) and
+wraps the app body in the runner; see `app/services/ticker.py` for the pattern
+(worker thread + stop Event + bounded join):
+
+```python
+class Application(ApplicationInterface):
+    SERVICES = [Database, Poller, HttpApiService]      # startup order
+
+    def run(self) -> None:
+        with ServiceRunner(self._container, self.SERVICES):   # async app: `async with`
+            self._main_loop()
+        # leaving the block stops everything in reverse — on return, exception, Ctrl+C
+```
+
+Guarantees: crash-safe startup (a failed `start()` rolls back the already-started
+services and re-raises); a failing `stop()` is logged, teardown continues; async stops
+are bounded by `stop_grace` (default 10s), then cancelled. The runner never grabs
+signals — the exit is triggered by uvicorn / Qt `aboutToQuit` / your own code. Services
+do NOT go into `DI_CONFIG` (concrete `@singleton` classes resolve themselves).
+
+## What nexus does NOT provide (you hand-roll these)
+
+Signal handling (`ServiceRunner` never grabs SIGINT/SIGTERM — exit is triggered by
+uvicorn, Qt `aboutToQuit`, or your own code); a background-service/worker base;
+a repository/DB layer; a test harness; HTTP/routing/retries.
+""",
+}
+
+
+def main() -> None:
+    if len(sys.argv) < 3 or sys.argv[1] != "new":
+        print("Usage: nexus-kit new <app-name>")
+        sys.exit(1)
+
+    app_name = sys.argv[2]
+    root = Path(app_name)
+
+    if root.exists():
+        print(f"Error: '{app_name}' already exists")
+        sys.exit(1)
+
+    root.mkdir()
+
+    nexus_ref = version("nexus-kit")
+    for rel_path, content in _TEMPLATES.items():
+        path = root / rel_path
+        path.parent.mkdir(parents=True, exist_ok=True)
+        content = content.replace("{{APP_NAME}}", app_name).replace("{{NEXUS_REF}}", nexus_ref)
+        path.write_text(content, encoding="utf-8")
+
+    print(f"Created {app_name}/")
+    print(f"")
+    print(f"  cd {app_name}")
+    print(f"")
+    print(f"  # install dependencies:")
+    print(f"  uv sync                  # uv")
+    print(f"  pip install -e .         # pip")
+    print(f"")
+    print(f"  python main.py")

nexus_kit/impl/__init__.py

@@ -0,0 +1,4 @@
+from nexus_kit.impl.container_injector import ContainerInjector
+from nexus_kit.impl.service_runner import ServiceRunner
+
+__all__ = ["ContainerInjector", "ServiceRunner"]

nexus_kit/impl/container_injector.py

@@ -0,0 +1,25 @@
+from typing import Any, Mapping, Type, TypeVar
+
+from injector import Injector, singleton
+
+from nexus_kit.interfaces.container import ContainerInterface
+
+
+@singleton
+class ContainerInjector(ContainerInterface):
+    T = TypeVar("T")
+
+    def __init__(self, bindings: Mapping[Type[Any], Any]):
+        self.__injector = Injector()
+        self.__injector.binder.bind(Injector, to=self.__injector)
+        self.__injector.binder.bind(ContainerInterface, to=self)
+
+        for cls, value in bindings.items():
+            self.set(cls, value)
+
+    def get(self, cls: Type[T]) -> T:
+        return self.__injector.get(cls)
+
+    def set(self, cls: Type[T], value: Any) -> "ContainerInterface":
+        self.__injector.binder.bind(cls, to=value)
+        return self

nexus_kit/impl/service_runner.py

@@ -0,0 +1,121 @@
+import asyncio
+import inspect
+import logging
+from typing import Sequence, Type
+
+from nexus_kit.interfaces.container import ContainerInterface
+from nexus_kit.interfaces.service import ServiceInterface
+
+
+class ServiceRunner:
+    """Starts services in order, stops them in reverse — guaranteed.
+
+    Sync app (pygame, Qt worker threads):
+
+        runner = ServiceRunner(container, SERVICES)
+        with runner:
+            main_loop()
+
+    Async app (asyncio servers):
+
+        async with ServiceRunner(container, SERVICES) as runner:
+            await http.wait()
+
+    Startup is crash-safe: if the N-th service fails to start, the already
+    started N-1 are stopped in reverse order and the error is re-raised.
+    Teardown runs on any exit — normal return, exception, Ctrl+C — and keeps
+    going past individual stop() failures (they are logged, not raised, so
+    every service gets its chance to shut down).
+
+    The runner does NOT install signal handlers: who triggers the exit is
+    the application's business (uvicorn's own handlers, Qt's aboutToQuit,
+    or your own). In the async context each async stop() is bounded by
+    `stop_grace` seconds, then cancelled; a SYNC stop() runs inline and is
+    not bounded — deliberately, because offloading it to a thread would
+    silently break thread-affine teardown (Qt, COM). If the surrounding
+    task is cancelled mid-teardown, the remaining services are still
+    stopped before the cancellation is re-raised.
+    """
+
+    def __init__(
+            self,
+            container: ContainerInterface,
+            services: Sequence[Type[ServiceInterface]],
+            stop_grace: float = 10.0,
+            logger: logging.Logger | None = None,
+    ) -> None:
+        self._container = container
+        self._service_types = list(services)
+        self._stop_grace = stop_grace
+        self._log = logger or logging.getLogger("nexus.services")
+        self._started: list[ServiceInterface] = []
+
+    # --- sync context ---
+
+    def __enter__(self) -> "ServiceRunner":
+        for cls in self._service_types:
+            try:
+                service = self._container.get(cls)
+                if inspect.iscoroutinefunction(service.start) or inspect.iscoroutinefunction(service.stop):
+                    raise TypeError(f"{cls.__name__} is async — use 'async with' instead of 'with'")
+                service.start()
+            except BaseException:
+                self.stop_all()
+                raise
+            self._started.append(service)
+            self._log.info("started %s", cls.__name__)
+        return self
+
+    def __exit__(self, *exc_info) -> None:
+        self.stop_all()
+
+    def stop_all(self) -> None:
+        while self._started:
+            service = self._started.pop()
+            try:
+                service.stop()
+                self._log.info("stopped %s", type(service).__name__)
+            except Exception:
+                self._log.exception("%s.stop() failed", type(service).__name__)
+
+    # --- async context ---
+
+    async def __aenter__(self) -> "ServiceRunner":
+        for cls in self._service_types:
+            try:
+                service = self._container.get(cls)
+                result = service.start()
+                if inspect.isawaitable(result):
+                    await result
+            except BaseException:
+                await self.stop_all_async()
+                raise
+            self._started.append(service)
+            self._log.info("started %s", cls.__name__)
+        return self
+
+    async def __aexit__(self, *exc_info) -> None:
+        await self.stop_all_async()
+
+    async def stop_all_async(self) -> None:
+        # Cancellation of the surrounding task must not abandon the remaining
+        # services half-stopped: swallow CancelledError per service, finish
+        # the teardown, then re-raise it once.
+        cancelled = False
+        while self._started:
+            service = self._started.pop()
+            name = type(service).__name__
+            try:
+                result = service.stop()
+                if inspect.isawaitable(result):
+                    await asyncio.wait_for(asyncio.ensure_future(result), self._stop_grace)
+                self._log.info("stopped %s", name)
+            except asyncio.CancelledError:
+                cancelled = True
+                self._log.warning("cancelled while stopping %s — finishing the remaining teardown", name)
+            except TimeoutError:
+                self._log.error("%s.stop() exceeded the %.1fs grace period and was cancelled", name, self._stop_grace)
+            except Exception:
+                self._log.exception("%s.stop() failed", name)
+        if cancelled:
+            raise asyncio.CancelledError

nexus_kit/interfaces/__init__.py

@@ -0,0 +1,11 @@
+from nexus_kit.interfaces.application import ApplicationInterface
+from nexus_kit.interfaces.container import ContainerInterface
+from nexus_kit.interfaces.environment import EnvironmentInterface
+from nexus_kit.interfaces.service import ServiceInterface
+
+__all__ = [
+    "ApplicationInterface",
+    "ContainerInterface",
+    "EnvironmentInterface",
+    "ServiceInterface",
+]

nexus_kit/interfaces/application.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from nexus_kit.interfaces.container import ContainerInterface
+from nexus_kit.interfaces.environment import EnvironmentInterface
+
+
+class ApplicationInterface(ABC):
+    @abstractmethod
+    def __init__(
+            self, environment: EnvironmentInterface, container: ContainerInterface
+    ): ...
+
+    @abstractmethod
+    def run(self): ...

nexus_kit/interfaces/container.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+from typing import Any, Type, TypeVar
+
+
+T = TypeVar("T")
+
+
+class ContainerInterface(ABC):
+    @abstractmethod
+    def get(self, cls: Type[T]) -> T: ...
+
+    @abstractmethod
+    def set(self, cls: Type[Any], value: Any) -> "ContainerInterface": ...

nexus_kit/interfaces/environment.py

@@ -0,0 +1,10 @@
+from injector import singleton
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+@singleton
+class EnvironmentInterface(BaseSettings):
+    # utf-8-sig: Windows editors (Notepad) save .env with a BOM — without this the
+    # first key silently becomes 'KEY' and validation fails with a cryptic error.
+    # extra="ignore": .env files often carry keys for other tools (compose, direnv).
+    model_config = SettingsConfigDict(env_file_encoding="utf-8-sig", extra="ignore")

nexus_kit/interfaces/service.py

@@ -0,0 +1,19 @@
+from abc import ABC, abstractmethod
+
+
+class ServiceInterface(ABC):
+    """Contract for a long-lived service managed by ServiceRunner.
+
+    Both methods may be sync or async — the runner awaits the result when it
+    is awaitable. In a sync runner context (`with runner:`) async services
+    are rejected.
+
+    stop() must be idempotent: the runner may call it after a failed start()
+    or more than once during teardown.
+    """
+
+    @abstractmethod
+    def start(self) -> None: ...
+
+    @abstractmethod
+    def stop(self) -> None: ...

nexus_kit/logging/__init__.py

@@ -0,0 +1,5 @@
+from nexus_kit.logging.log_formatter import LogFormatter
+from nexus_kit.logging.named_logger import NamedLogger
+from nexus_kit.logging.stdout_handler import StdoutHandler
+
+__all__ = ["LogFormatter", "NamedLogger", "StdoutHandler"]

nexus_kit/logging/log_formatter.py

@@ -0,0 +1,24 @@
+import logging
+from typing import ClassVar
+
+from injector import singleton
+
+
+@singleton
+class LogFormatter(logging.Formatter):
+    """Default log line format.
+
+    Subclass and override `format_string`, then bind the subclass in place of
+    LogFormatter to change how every handler renders a record — this is
+    independent of *where* logs go (see StdoutHandler):
+
+        class JsonFormatter(LogFormatter):
+            format_string = '{"ts":"%(asctime)s","level":"%(levelname)s",...}'
+
+        DI_CONFIG = {LogFormatter: JsonFormatter}
+    """
+
+    format_string: ClassVar[str] = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+
+    def __init__(self):
+        super().__init__(self.format_string)

nexus_kit/logging/named_logger.py

@@ -0,0 +1,47 @@
+import logging
+from typing import ClassVar
+
+from injector import inject
+
+from nexus_kit.logging.stdout_handler import StdoutHandler
+
+
+class NamedLogger(logging.Logger):
+    """Base for a typed, DI-injectable logger channel.
+
+    Subclass and set `name` (and optionally `level`) — nexus wires the
+    handler for you. Each subclass is its own container-resolvable type:
+    inject it by type annotation, no string-keyed lookups.
+
+        @singleton
+        class SessionLogger(NamedLogger):
+            name = "app.session"
+
+        class SessionManager:
+            @inject
+            def __init__(self, log: SessionLogger): ...
+
+    To add another handler (e.g. a Qt signal sink for a log-view widget),
+    override `__init__` and call `super().__init__(handler)` first:
+
+        @singleton
+        class SessionLogger(NamedLogger):
+            name = "app.session"
+
+            @inject
+            def __init__(self, handler: StdoutHandler, qt_handler: QtLogHandler):
+                super().__init__(handler)
+                self.addHandler(qt_handler)
+    """
+
+    name: ClassVar[str]
+    level: ClassVar[int] = logging.INFO
+
+    @inject
+    def __init__(self, handler: StdoutHandler):
+        # Read the class attribute before Logger.__init__ shadows `self.level`
+        # with an instance attribute (it defaults to NOTSET if not passed here).
+        level = self.level
+        super().__init__(self.name, level)
+        self.addHandler(handler)
+        self.propagate = False

nexus_kit/logging/stdout_handler.py

@@ -0,0 +1,17 @@
+import logging
+import sys
+
+from injector import inject, singleton
+
+from nexus_kit.logging.log_formatter import LogFormatter
+
+
+@singleton
+class StdoutHandler(logging.StreamHandler):
+    """Writes log records to the console. Formatting is a separate concern —
+    see LogFormatter."""
+
+    @inject
+    def __init__(self, formatter: LogFormatter):
+        super().__init__(sys.stdout)
+        self.setFormatter(formatter)

nexus_kit/root.py

@@ -0,0 +1,31 @@
+import sys
+from pathlib import Path
+
+
+class Root:
+    @staticmethod
+    def internal(*relative_parts: str) -> str:
+        if hasattr(sys, "_MEIPASS"):
+            base_dir = Path(sys._MEIPASS)
+        else:
+            base_dir = Root._dev_base()
+        return str(base_dir.joinpath(*relative_parts))
+
+    @staticmethod
+    def external(*relative_parts: str) -> str:
+        if hasattr(sys, "_MEIPASS"):
+            base_dir = Path(sys.executable).resolve().parent
+        else:
+            base_dir = Root._dev_base()
+        return str(base_dir.joinpath(*relative_parts))
+
+    @staticmethod
+    def _dev_base() -> Path:
+        # Anchor to the entry script's directory, not cwd: launching
+        # `python d:/apps/game/main.py` from another directory (IDE, task
+        # scheduler, shortcut) must still find .env next to main.py —
+        # matching the frozen build, which anchors to the exe.
+        main_file = getattr(sys.modules.get("__main__"), "__file__", None)
+        if main_file:
+            return Path(main_file).resolve().parent
+        return Path.cwd()  # REPL, python -c

nexus_kit-0.4.0.dist-info/METADATA

@@ -0,0 +1,425 @@
+Metadata-Version: 2.4
+Name: nexus-kit
+Version: 0.4.0
+Summary: Application kernel for long-lived Python apps: one entry point, typed config, constructor DI, service lifecycle, PyInstaller-safe paths.
+Project-URL: Repository, https://github.com/Astislav/nexus
+Author-email: Astislav Bozhevolnov <astislav@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: application,bootstrap,dependency-injection,di,framework
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.12
+Requires-Dist: injector>=0.24.0
+Requires-Dist: pydantic-settings>=2.13.1
+Description-Content-Type: text/markdown
+
+# nexus
+
+[![ci](https://github.com/Astislav/nexus/actions/workflows/ci.yml/badge.svg)](https://github.com/Astislav/nexus/actions/workflows/ci.yml)
+
+A minimal application kernel for long-lived Python apps: one entry point,
+typed config, constructor DI, logger channels, service lifecycle — and paths
+that survive PyInstaller.
+
+PyPI dist **`nexus-kit`**, imports as **`nexus_kit`**, CLI command **`nexus-kit`**.
+
+## Why
+
+If you build long-lived Python apps **outside a web framework's cradle** — a
+Qt tool driving hardware, a pygame game, a Windows daemon, an API server
+where uvicorn is just one service among many — you end up hand-rolling the
+same bootstrap in every repo: an entry point, `.env` parsing, wiring services
+together, logging setup, ordered start/stop, and the `sys._MEIPASS` dance for
+frozen builds.
+
+nexus is that bootstrap extracted once and turned into a convention. Every
+app gets the same shape: `main.py` is four lines, config is a typed class,
+services declare their dependencies in constructors, long-lived services
+start in order and stop in reverse — guaranteed. Your fifth app looks like
+your first, and anyone (human or AI assistant) who has seen one has seen
+them all.
+
+## Who it's for
+
+- You ship Python as **PyInstaller executables** and are tired of path bugs
+  that only appear after freezing.
+- You maintain **several apps** — web and not — and want them all shaped the
+  same instead of each inventing its own bootstrap.
+- You want **constructor injection without magic**: one explicit
+  `{Interface: Implementation}` dict, no string keys, no globals, no
+  auto-scanning.
+- Your app has **services that must start in order and stop cleanly** —
+  DB pools, pollers, device monitors, an embedded HTTP server.
+
+## Who it's NOT for
+
+- **Short scripts.** A module with functions is already dependency
+  injection. This would be ceremony.
+- **Apps living happily inside FastAPI/Django conventions.** Their lifespan
+  and DI are enough; nexus solves the world outside that cradle.
+- **Teams that want a mainstream stack.** This is an opinionated personal
+  kernel: conventions over ecosystem, no Stack Overflow answers.
+
+## What it is, honestly
+
+Opinionated glue — not invention. Config is stock
+[pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/),
+DI is stock [injector](https://injector.readthedocs.io/); nexus adds the
+parts nobody packages: the `Root` path resolver for frozen builds, typed
+logger channels, the `ServiceRunner` lifecycle, a scaffolder, and the
+convention that ties them together. Extracted from real production apps
+(a Qt device farm, a WhatsApp gateway, analytics services), not designed in
+a vacuum.
+
+## Install
+
+```bash
+# uv
+uv add nexus-kit
+
+# pip
+pip install nexus-kit
+```
+
+Requires Python 3.12+. Ships with [injector](https://injector.readthedocs.io/) and
+[pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) —
+no extras, everything works out of the box.
+
+## Bootstrap a new app
+
+```bash
+nexus-kit new my-app
+cd my-app
+
+# install dependencies:
+uv sync          # uv
+pip install -e . # pip
+
+python main.py
+# [ticker] started (every 0.7s)
+# [my-app] running for 3.0s — Ctrl+C to stop early
+# tick #1
+# tick #2
+# tick #3
+# tick #4
+# [ticker] stopped after 4 ticks
+```
+
+## What you get
+
+```
+my-app/
+├── main.py                          # entry point — the whole bootstrap, 4 lines
+├── pyproject.toml
+├── .env
+└── app/
+    ├── application.py               # SERVICES + ServiceRunner around the main loop
+    ├── config/
+    │   ├── di.py                    # DI_CONFIG = {Interface: Implementation}
+    │   └── environment.py           # typed fields read from .env
+    └── services/
+        ├── ticker.py                # worker thread with clean start/stop (ServiceInterface)
+        ├── reporter_interface.py    # a swappable seam
+        └── console_reporter.py     # its default implementation
+```
+
+## How it fits together
+
+```python
+# main.py — the whole bootstrap
+env       = Environment(Root.external(".env"))  # 1. load typed config
+container = ContainerInjector(DI_CONFIG)         # 2. wire up services
+container.set(Environment, env)                  # 3. make config injectable
+Application(env, container).run()                # 4. start the app
+```
+
+| File | Role |
+|------|------|
+| `app/config/environment.py` | Declare config fields — read from `.env` automatically |
+| `app/config/di.py` | Register services — `{Interface: Implementation}` |
+| `app/application.py` | Entry point — resolve services, own the `run()` lifecycle |
+
+## Environment
+
+`EnvironmentInterface` is a [Pydantic BaseSettings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) subclass.
+Add typed fields — they are read from `.env` automatically:
+
+```python
+# app/config/environment.py
+from nexus_kit.interfaces import EnvironmentInterface
+
+class Environment(EnvironmentInterface):
+    APP_NAME: str = "my-app"
+    DEBUG: bool = False
+    DB_URL: str = "sqlite:///data.db"
+```
+
+`.env` is passed at startup via `Root.external(".env")` (see below):
+
+```python
+env = Environment(Root.external(".env"))
+```
+
+Fields can be overridden at runtime with environment variables — Pydantic picks them up automatically.
+
+`Environment` is also bound into the container at startup, so services can inject it directly:
+
+```python
+# main.py (generated by `nexus-kit new`)
+env = Environment(Root.external(".env"))
+container = ContainerInjector(DI_CONFIG)
+container.set(Environment, env)   # ← makes env injectable
+Application(env, container).run()
+```
+
+This means any service can receive config via `@inject` without going through `Application`:
+
+```python
+from injector import inject, singleton
+from app.config.environment import Environment
+
+@singleton
+class DatabaseService:
+    @inject
+    def __init__(self, env: Environment) -> None:
+        self._url = env.DB_URL
+```
+
+## Paths
+
+`Root` resolves paths correctly in both development and PyInstaller-bundled executables.
+
+```python
+from nexus_kit import Root
+
+# next to the .exe (or next to main.py in dev) — user data, configs, output
+config = Root.external(".env")
+db     = Root.external("data", "app.db")
+
+# inside the bundle (or next to main.py in dev) — shipped assets, templates
+html   = Root.internal("templates", "report.html")
+```
+
+| Method | Dev (plain Python) | Bundled (PyInstaller) |
+|--------|--------------------|-----------------------|
+| `Root.external(...)` | `dir(main.py) / path` | `dir(exe) / path` |
+| `Root.internal(...)` | `dir(main.py) / path` | `_MEIPASS / path` |
+
+In dev the anchor is the entry script's directory (not the current working
+directory), so launching `python d:/apps/game/main.py` from anywhere — an IDE,
+a task scheduler, a shortcut — resolves the same paths as running it in place.
+
+Use `external` for anything the user owns (configs, databases, output files).
+Use `internal` for assets you ship inside the bundle (templates, images, default configs).
+
+## Logging
+
+`NamedLogger` is a base for typed, DI-injectable logger channels — subclass
+it, set `name`, and inject the subclass by type. No string-keyed
+`logging.getLogger(...)` calls scattered through the codebase:
+
+```python
+# app/loggers.py
+from injector import singleton
+from nexus_kit.logging import NamedLogger
+
+@singleton
+class SessionLogger(NamedLogger):
+    name = "app.session"
+
+@singleton
+class SenderLogger(NamedLogger):
+    name = "app.sender"
+```
+
+```python
+# app/core/session_manager.py
+from injector import inject, singleton
+from app.loggers import SessionLogger
+
+@singleton
+class SessionManager:
+    @inject
+    def __init__(self, log: SessionLogger) -> None:
+        self._log = log
+
+    def start(self) -> None:
+        self._log.info("Session manager started")
+```
+
+Each subclass gets its own `StdoutHandler` (console, one shared instance)
+wired up automatically — no duplicate-handler bugs, no manual `addHandler`.
+
+**Custom format** — *where* logs go (`StdoutHandler`) and *how they look*
+(`LogFormatter`) are separate, like in stdlib `logging`. Subclass
+`LogFormatter` and rebind it — no need to touch the handler:
+
+```python
+# app/loggers.py
+from nexus_kit.logging import LogFormatter
+
+class JsonFormatter(LogFormatter):
+    format_string = '{"ts":"%(asctime)s","level":"%(levelname)s","logger":"%(name)s","msg":"%(message)s"}'
+```
+
+```python
+# app/config/di.py
+DI_CONFIG = {
+    LogFormatter: JsonFormatter,
+    ...
+}
+```
+
+**Extra handlers** (e.g. forwarding logs to a UI widget) — override `__init__`
+and add the handler after calling `super().__init__(handler)`:
+
+```python
+@singleton
+class SessionLogger(NamedLogger):
+    name = "app.session"
+
+    @inject
+    def __init__(self, handler: StdoutHandler, ui_handler: LogViewHandler) -> None:
+        super().__init__(handler)
+        self.addHandler(ui_handler)
+```
+
+## Services & lifecycle
+
+`ServiceInterface` + `ServiceRunner` manage long-lived services: started in
+declaration order, stopped in reverse — guaranteed, even when startup or the
+app body crashes.
+
+```python
+# a service — sync or async, the runner handles both
+from injector import singleton
+from nexus_kit.interfaces import ServiceInterface
+
+@singleton
+class Database(ServiceInterface):
+    async def start(self) -> None: ...   # open the pool
+    async def stop(self) -> None: ...    # close the pool (must be idempotent)
+```
+
+```python
+# app/application.py — async app (uvicorn, workers)
+from nexus_kit.impl import ServiceRunner
+
+class Application(ApplicationInterface):
+    SERVICES = [Database, WebhookDispatcher, HttpApiService]  # startup order
+
+    def run(self) -> None:
+        asyncio.run(self._serve())
+
+    async def _serve(self) -> None:
+        async with ServiceRunner(self._container, self.SERVICES):
+            await self._container.get(HttpApiService).wait()
+        # leaving the block stops everything in reverse order
+```
+
+Sync apps (pygame, Qt with worker threads) use the plain context manager:
+
+```python
+    def run(self) -> None:
+        with ServiceRunner(self._container, self.SERVICES):
+            self._main_loop()
+```
+
+Guarantees:
+
+- start in order, stop in reverse — on normal exit, exception, Ctrl+C;
+- crash-safe startup: if the N-th `start()` fails, the already started N-1
+  are stopped in reverse and the error re-raises;
+- one failing `stop()` doesn't block the rest — it is logged and teardown
+  continues;
+- in the async context each `stop()` is bounded by `stop_grace` seconds
+  (default 10), then cancelled.
+
+The runner installs **no signal handlers** — who triggers the exit is your
+app's business (uvicorn's own handlers, Qt's `aboutToQuit`, or your own).
+
+## Add a service
+
+**1. Define an interface (a swappable seam):**
+
+```python
+# app/services/reporter_interface.py
+from abc import ABC, abstractmethod
+
+class ReporterInterface(ABC):
+    @abstractmethod
+    def report(self, tick: int) -> None: ...
+```
+
+**2. Implement it:**
+
+```python
+# app/services/console_reporter.py
+from injector import singleton
+from app.services.reporter_interface import ReporterInterface
+
+@singleton
+class ConsoleReporter(ReporterInterface):
+    def report(self, tick: int) -> None:
+        print(f"tick #{tick}")
+```
+
+**3. Register in DI:**
+
+```python
+# app/config/di.py
+from app.services.console_reporter import ConsoleReporter
+from app.services.reporter_interface import ReporterInterface
+
+DI_CONFIG = {
+    ReporterInterface: ConsoleReporter,
+}
+```
+
+**4. Inject it — by type, into a constructor, no string keys:**
+
+```python
+# app/services/ticker.py
+from injector import inject, singleton
+from nexus_kit.interfaces import ServiceInterface
+
+@singleton
+class Ticker(ServiceInterface):
+    @inject
+    def __init__(self, env: Environment, reporter: ReporterInterface) -> None:
+        self._interval = env.TICK_SECONDS
+        self._reporter = reporter
+```
+
+Swapping `ConsoleReporter` for a file writer, an HTTP pusher or a Qt widget
+is a one-line change in `DI_CONFIG` — nothing else moves.
+
+## What nexus provides
+
+| Symbol | Import | Description |
+|--------|--------|-------------|
+| `ApplicationInterface` | `nexus_kit.interfaces` | Bootstrap contract: `__init__(env, container)` + `run()` |
+| `ContainerInterface` | `nexus_kit.interfaces` | DI contract: `get(cls)` + `set(cls, value)` |
+| `EnvironmentInterface` | `nexus_kit.interfaces` | Typed config base (Pydantic BaseSettings) |
+| `ServiceInterface` | `nexus_kit.interfaces` | Long-lived service contract: `start()` + `stop()`, sync or async |
+| `Root` | `nexus` | Path util for dev and PyInstaller-bundled environments |
+| `ContainerInjector` | `nexus_kit.impl` | `ContainerInterface` impl via [injector](https://injector.readthedocs.io/) |
+| `ServiceRunner` | `nexus_kit.impl` | Ordered start / guaranteed reverse-order stop (`with` / `async with`) |
+| `NamedLogger` | `nexus_kit.logging` | Base for typed, DI-injectable logger channels |
+| `StdoutHandler` | `nexus_kit.logging` | Shared console handler — *where* logs go |
+| `LogFormatter` | `nexus_kit.logging` | Default log line format — *how* logs look; subclass to customize |
+
+## What nexus does NOT provide
+
+Domain logic, UI, data access — those belong in your app.
+
+## License
+
+MIT © Astislav Bozhevolnov

nexus_kit-0.4.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+nexus_kit/__init__.py,sha256=-1KM26cOcLWd5Ek3hVctw8ISWLbbCzPAeFPdJERPn-g,335
+nexus_kit/cli.py,sha256=pZ4-Zj_eh_l0c8RBXJNUWP_o0aKBwf5OH4pkN_Ov49I,10316
+nexus_kit/root.py,sha256=kwI-XvBEJkTTfEwlyqqtvG0Gn8ka2Xlv1naqAhx9B4E,1096
+nexus_kit/impl/__init__.py,sha256=3POHfUhY1BNJIX8t_Ya8JLJNCDPdwvQWl2WKBu8FYWc,170
+nexus_kit/impl/container_injector.py,sha256=-qel07QA9dwSzRTxyupNtWW7SYjEYJl1hYY271Ze_Ws,757
+nexus_kit/impl/service_runner.py,sha256=SIz9ZbYXcGuPdjk0ePjyNoMUZKY4l2qgW8gBln2Tg_I,4729
+nexus_kit/interfaces/__init__.py,sha256=sGu_V7nFWHTu5lbPswL8citGQpxKCAWxhVYvjZBDUiU,373
+nexus_kit/interfaces/application.py,sha256=Gtonr8WSf6KdvJQsMFLryzcdQbN8DKQpy2C-JwEENkA,412
+nexus_kit/interfaces/container.py,sha256=ccAHftSrWVhQiPe1mSVPogm_vHw5G7uQgAC1m0Y1GQA,284
+nexus_kit/interfaces/environment.py,sha256=VGZ_p_96OjV72hC3SNHvJl8zvyR4CCn6Hhfgkhm8gy0,489
+nexus_kit/interfaces/service.py,sha256=zQ5GmvKeSiHcbGkPoXIBaaSlI5ov3zXSBYFMZVVO58E,539
+nexus_kit/logging/__init__.py,sha256=1I8RGmoNsSG9Dhi2VA950DikkQzvHsLv5LI182n_5ZM,231
+nexus_kit/logging/log_formatter.py,sha256=bECiDsCwDmPmOCDzB6sU7MP7lemXPMQdiYcZsSzT97o,711
+nexus_kit/logging/named_logger.py,sha256=OJckDJTccokSqVH8kR20UCpVO-d6h4jILXQRb9bdDyU,1487
+nexus_kit/logging/stdout_handler.py,sha256=vAs07ERztc6l7emv-IYYXdgYdtQkkZo3Z9nwFq8Zp7A,421
+nexus_kit-0.4.0.dist-info/METADATA,sha256=OfOyuYliu0NT0JpGQPfg5PelmElm9cLF5xcO4JKl4vQ,14258
+nexus_kit-0.4.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+nexus_kit-0.4.0.dist-info/entry_points.txt,sha256=3S_rWsts3k29bGQLbGURdHe_N7ikKpZ4UhToUJYxLyc,49
+nexus_kit-0.4.0.dist-info/licenses/LICENSE,sha256=bm7WZS8juoGVn6UIVyZC3mx0lSbqoyJzt3iCLTkMpE4,1077
+nexus_kit-0.4.0.dist-info/RECORD,,

nexus_kit-0.4.0.dist-info/WHEEL

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

nexus_kit-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nexus-kit = nexus_kit.cli:main

nexus_kit-0.4.0.dist-info/licenses/LICENSE

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