nexus-kit 0.4.0__tar.gz

nexus_kit-0.4.0/.ai/guide.md

@@ -0,0 +1,194 @@
+# Nexus — AI Agent Guide
+
+Context for AI assistants working in projects built with nexus.
+
+## What nexus is
+
+Nexus is a minimal Python application framework. It provides:
+
+- Interfaces (abstract contracts) for bootstrapping an application
+- `ContainerInjector` — a concrete DI container implementation (thin wrapper over the `injector` library)
+- `ServiceInterface` / `ServiceRunner` — lifecycle: ordered start, guaranteed reverse-order stop of long-lived services (sync and async)
+- `Root` — a path utility that works in dev and PyInstaller-bundled environments
+- A logging base (`NamedLogger` / `StdoutHandler` / `LogFormatter`), DI-injectable
+- A scaffolding CLI: `nexus-kit new <app-name>`
+
+Nexus does NOT contain domain logic, UI code, or data access. It is infrastructure only.
+
+**Gotcha:** `@singleton`, `@inject` and `Injector` come from the third-party `injector`
+package, **not** from Nexus — import them `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.
+
+## Package layout
+
+```
+nexus_kit/
+├── interfaces/          # abstract contracts — always import from here first
+│   ├── application.py   # ApplicationInterface
+│   ├── container.py     # ContainerInterface
+│   └── environment.py   # EnvironmentInterface
+├── impl/                # concrete implementations — import explicitly
+│   └── container_injector.py
+├── logging/             # DI-injectable logging base
+│   ├── named_logger.py  # NamedLogger
+│   ├── stdout_handler.py# StdoutHandler
+│   └── log_formatter.py # LogFormatter
+├── cli.py               # `nexus-kit new` scaffolder
+└── root.py              # Root utility
+```
+
+Import conventions:
+
+```python
+from nexus_kit.interfaces import ApplicationInterface, ContainerInterface, EnvironmentInterface
+from nexus_kit.impl import ContainerInjector   # explicit — this is a concrete choice
+from nexus_kit import Root
+```
+
+## Bootstrap pattern
+
+Every nexus-based app follows this sequence in `main.py`:
+
+```python
+env = Environment(Root.external(".env"))      # 1. load config
+container = ContainerInjector(DI_CONFIG)      # 2. wire dependencies
+Application(env, container).run()             # 3. start app
+```
+
+`Environment` extends `EnvironmentInterface`, `Application` extends `ApplicationInterface`.
+`DI_CONFIG` lives in `app/config/di.py` — it is the composition root.
+
+## How to extend ApplicationInterface
+
+```python
+from nexus_kit.interfaces import ApplicationInterface, ContainerInterface, EnvironmentInterface
+
+class Application(ApplicationInterface):
+    def __init__(self, environment: EnvironmentInterface, container: ContainerInterface) -> None:
+        self._env = environment
+        self._container = container
+        # resolve top-level services here:
+        # self._service = container.get(SomeServiceInterface)
+
+    def run(self) -> None:
+        ...  # start event loop, server, CLI, etc.
+```
+
+## How to extend EnvironmentInterface
+
+```python
+from pathlib import Path
+from injector import singleton
+from nexus_kit.interfaces import EnvironmentInterface
+
+@singleton
+class Environment(EnvironmentInterface):
+    DATABASE_URL: str
+    DEBUG: bool = False
+    MAX_WORKERS: int = 4
+
+    def __init__(self, env_path: Path) -> None:
+        super().__init__(_env_file=env_path)
+```
+
+Pydantic BaseSettings rules apply: values come from environment variables and the `.env` file.
+Pass the `.env` path via `Root.external(".env")`.
+
+## How to register services in DI
+
+Composition root lives in `app/config/di.py`:
+
+```python
+from app.services.greeter import Greeter
+from app.services.greeter_interface import GreeterInterface
+
+DI_CONFIG = {
+    GreeterInterface: Greeter,
+    # Interface: ConcreteImplementation
+}
+```
+
+Mark long-lived services with `@singleton`, use `@inject` for constructor injection:
+
+```python
+from injector import inject, singleton
+from app.services.dep_interface import DepInterface
+
+@singleton
+class Greeter(GreeterInterface):
+    @inject
+    def __init__(self, dep: DepInterface) -> None:
+        self._dep = dep
+```
+
+## Logging
+
+Named logger channels are DI-injectable types, not `getLogger(str)` lookups. Subclass
+`NamedLogger`, set a class-level `name`; inject the subclass by type. Change the line
+format by rebinding `LogFormatter` in `DI_CONFIG` (independent of the destination handler).
+
+```python
+from injector import singleton
+from nexus_kit.logging import NamedLogger, LogFormatter
+
+@singleton
+class MainLogger(NamedLogger):
+    name = "app.main"
+
+class JsonFormatter(LogFormatter):
+    def format(self, record): ...   # rebind in DI_CONFIG: {LogFormatter: JsonFormatter}
+```
+
+## Lifecycle
+
+Long-lived services implement `ServiceInterface` (`start()`/`stop()`, sync or async,
+`stop()` idempotent). `Application` lists them in startup order and wraps the app body
+in a `ServiceRunner` context:
+
+```python
+from nexus_kit.impl import ServiceRunner
+
+SERVICES = [Database, WebhookDispatcher, HttpApiService]   # startup order
+
+# async app:
+async with ServiceRunner(self._container, SERVICES):
+    await self._container.get(HttpApiService).wait()
+# sync app (pygame, Qt):
+with ServiceRunner(self._container, SERVICES):
+    self._main_loop()
+```
+
+Guarantees: reverse-order stop on any exit; crash-safe startup (a failed `start()`
+rolls back the already-started services); a failing `stop()` is logged and teardown
+continues; async stops are bounded by `stop_grace` (10s default). The runner installs
+no signal handlers — exit is triggered by uvicorn, Qt `aboutToQuit`, or your own code.
+
+## What nexus does NOT provide (you hand-roll these)
+
+- No signal handling — `ServiceRunner` never grabs SIGINT/SIGTERM; wire the exit
+  trigger yourself (uvicorn's handlers, Qt `aboutToQuit`, own handler).
+- No background-service / worker base class, no scheduling.
+- No repository / persistence / DB layer.
+- No testing helpers or fixtures.
+- No HTTP/server/routing, retries, or middleware.
+- Config is stock `pydantic-settings`; logging is a stdout stream handler only.
+
+## Key conventions
+
+- Abstract contracts have the `Interface` suffix: `GreeterInterface`, `UserRepositoryInterface`
+- Implementations have no special suffix: `Greeter`, `UserRepository`
+- One class per file; file named after the class in snake_case
+- `@singleton` for long-lived managers and services
+- Dynamic objects (created at runtime) use Factories: `WidgetFactoryInterface` → `WidgetFactory`
+- Do not import concrete implementations outside of `di.py` (exceptions: tests, and
+  the `SERVICES` list in `Application` — both are part of the composition root)
+
+## What NOT to do
+
+- Do not put business logic in `Application.__init__` or `main.py`
+- Do not make `ContainerInterface` globally accessible — pass it only to `Application`
+- Do not register primitive types (str, int, bool) in DI unless they carry policy semantics
+- Do not add `@inject` to `Application.__init__` — it is constructed manually in `main.py`

nexus_kit-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: ci
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.12", "3.13", "3.14"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --python ${{ matrix.python }}
+      - run: uv run pytest -q

nexus_kit-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,18 @@
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # PyPI trusted publishing (OIDC), no tokens needed
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync
+      - run: uv run pytest -q
+      - run: uv build
+      - run: uv publish --trusted-publishing always

nexus_kit-0.4.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.pyo
+dist/
+*.egg-info/
+.eggs/
+build/
+.venv/
+.env
+.idea/
+.vscode/
+*.iml
+.DS_Store
+Thumbs.db
+.ruff_cache/
+.pytest_cache/
+uv.lock

nexus_kit-0.4.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## [0.1.1]
+
+### Added
+
+- `nexus.logging` — DI-injectable logging base (`NamedLogger`, `StdoutHandler`, `LogFormatter`). Present since the initial release but previously undocumented in this changelog.
+- `nexus new <app-name>` now scaffolds an AI-ready project: a `CLAUDE.md` pointing to `.ai/`, and `.ai/nexus.md` (a compact, self-contained Nexus API reference) so any AI assistant picks up how to build on nexus without reading the framework source.
+
+### Changed
+
+- Refreshed `.ai/guide.md` (AI Agent Guide): package layout now lists `logging/` and `cli.py`; documents the `injector`-not-nexus import gotcha, the `nexus[pydantic]` extra requirement, and what nexus deliberately does NOT provide.
+
+## [0.1.0] — 2025-07-02
+
+Initial release.
+
+### Added
+
+- `ApplicationInterface` — abstract contract for application bootstrap
+- `ContainerInterface` — abstract contract for dependency injection container
+- `EnvironmentInterface` — abstract base for typed configuration (Pydantic BaseSettings + singleton)
+- `Root` — path utility for development and PyInstaller-bundled environments
+- `ContainerInjector` — `ContainerInterface` implementation using the `injector` library
+- `nexus new <app-name>` CLI command to scaffold a minimal working application

nexus_kit-0.4.0/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.