simple-module-core 0.0.1__tar.gz

simple_module_core-0.0.1/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+
+# UV
+uv.lock
+
+# Node
+node_modules/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+
+# Database
+*.db
+*.sqlite3
+
+# Module-managed runtime state (e.g. uploaded dataset files,
+# default storage_dir for SM_DATASETS_STORAGE_DIR).
+var/
+
+# file_storage filesystem backend default root (override via SM_FILE_STORAGE_FS_ROOT_PATH).
+uploads/
+
+# Vite
+host/static/dist/
+
+# Auto-generated frontend module manifest (regenerated by the host at boot
+# or via `make gen-pages`).
+host/client_app/modules.manifest.json
+host/client_app/modules.generated.ts
+host/client_app/modules.generated.css
+
+# Worktrees
+.worktrees/
+
+# Performance profiles
+.memray/
+.benchmarks/
+
+# OS
+.DS_Store
+Thumbs.db
+
+.playwright-cli/*
+.playwright-mcp/*
+host/client_app/.playwright-cli/*
+.superpowers/

simple_module_core-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anto Subash
+
+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.

simple_module_core-0.0.1/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: simple_module_core
+Version: 0.0.1
+Summary: Module-system primitives for the simple_module framework — ModuleBase, discovery, diagnostics, events
+Project-URL: Homepage, https://github.com/antosubash/simple_module_python
+Project-URL: Repository, https://github.com/antosubash/simple_module_python
+Project-URL: Issues, https://github.com/antosubash/simple_module_python/issues
+Project-URL: Changelog, https://github.com/antosubash/simple_module_python/blob/main/CHANGELOG.md
+Author-email: Anto Subash <antosubash@live.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fastapi,modular-monolith,module-discovery,plugin-system,simple-module
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: babel>=2.14
+Requires-Dist: fastapi>=0.115
+Requires-Dist: packaging>=23.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyee>=12.0
+Description-Content-Type: text/markdown
+
+# simple_module_core
+
+Module-system primitives for the [simple_module](https://github.com/antosubash/simple_module_python) framework — a modular-monolith for Python/FastAPI where each feature is a plugin package discovered at boot.
+
+This package defines `ModuleBase`, the `ModuleMeta` descriptor, the `discover_modules()` entry-point loader, topological dependency sorting, event bus primitives, and the diagnostic codes (`SM001`–`SM017`) used by `make doctor`.
+
+## Install
+
+```bash
+pip install simple_module_core
+```
+
+You usually don't install this directly — it's pulled in by `simple_module_hosting` and every `simple_module_*` module.
+
+## What it provides
+
+- `ModuleBase` — the subclass every module extends to opt into lifecycle hooks.
+- `ModuleMeta` — required `meta = ModuleMeta(name=..., depends_on=...)` attribute on each module.
+- `discover_modules()` — loads all `[project.entry-points.simple_module]` modules, topologically sorts by `depends_on`.
+- Diagnostic registry — `SM001` missing meta, `SM003` orphan page, `SM008` duplicate name, `SM009` framework→plugin coupling violation, and ~ten others.
+- Tiny event-bus (`pyee`) for decoupled module-to-module communication.
+
+## Usage
+
+```python
+# modules/orders/orders/module.py
+from simple_module_core import ModuleBase, ModuleMeta
+
+
+class OrdersModule(ModuleBase):
+    meta = ModuleMeta(name="orders", depends_on=["users"])
+
+    def register_routes(self, api_router, view_router):
+        from .endpoints import api, views
+        api_router.include_router(api.router)
+        view_router.include_router(views.router)
+```
+
+And in `pyproject.toml`:
+
+```toml
+[project.entry-points.simple_module]
+orders = "orders.module:OrdersModule"
+```
+
+The host's `discover_modules()` call picks this up automatically at boot.
+
+## Depends on
+
+- `fastapi`, `pydantic`, `pydantic-settings`, `pyee`, `babel`, `packaging`
+
+## License
+
+MIT — see [LICENSE](https://github.com/antosubash/simple_module_python/blob/main/LICENSE).

simple_module_core-0.0.1/README.md

@@ -0,0 +1,54 @@
+# simple_module_core
+
+Module-system primitives for the [simple_module](https://github.com/antosubash/simple_module_python) framework — a modular-monolith for Python/FastAPI where each feature is a plugin package discovered at boot.
+
+This package defines `ModuleBase`, the `ModuleMeta` descriptor, the `discover_modules()` entry-point loader, topological dependency sorting, event bus primitives, and the diagnostic codes (`SM001`–`SM017`) used by `make doctor`.
+
+## Install
+
+```bash
+pip install simple_module_core
+```
+
+You usually don't install this directly — it's pulled in by `simple_module_hosting` and every `simple_module_*` module.
+
+## What it provides
+
+- `ModuleBase` — the subclass every module extends to opt into lifecycle hooks.
+- `ModuleMeta` — required `meta = ModuleMeta(name=..., depends_on=...)` attribute on each module.
+- `discover_modules()` — loads all `[project.entry-points.simple_module]` modules, topologically sorts by `depends_on`.
+- Diagnostic registry — `SM001` missing meta, `SM003` orphan page, `SM008` duplicate name, `SM009` framework→plugin coupling violation, and ~ten others.
+- Tiny event-bus (`pyee`) for decoupled module-to-module communication.
+
+## Usage
+
+```python
+# modules/orders/orders/module.py
+from simple_module_core import ModuleBase, ModuleMeta
+
+
+class OrdersModule(ModuleBase):
+    meta = ModuleMeta(name="orders", depends_on=["users"])
+
+    def register_routes(self, api_router, view_router):
+        from .endpoints import api, views
+        api_router.include_router(api.router)
+        view_router.include_router(views.router)
+```
+
+And in `pyproject.toml`:
+
+```toml
+[project.entry-points.simple_module]
+orders = "orders.module:OrdersModule"
+```
+
+The host's `discover_modules()` call picks this up automatically at boot.
+
+## Depends on
+
+- `fastapi`, `pydantic`, `pydantic-settings`, `pyee`, `babel`, `packaging`
+
+## License
+
+MIT — see [LICENSE](https://github.com/antosubash/simple_module_python/blob/main/LICENSE).

simple_module_core-0.0.1/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "simple_module_core"
+version = "0.0.1"
+description = "Module-system primitives for the simple_module framework — ModuleBase, discovery, diagnostics, events"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+authors = [{ name = "Anto Subash", email = "antosubash@live.com" }]
+keywords = ["simple-module", "fastapi", "modular-monolith", "plugin-system", "module-discovery"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+dependencies = [
+    "babel>=2.14",
+    "fastapi>=0.115",
+    "packaging>=23.0",
+    "pydantic>=2.0",
+    "pydantic-settings>=2.0",
+    "pyee>=12.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/antosubash/simple_module_python"
+Repository = "https://github.com/antosubash/simple_module_python"
+Issues = "https://github.com/antosubash/simple_module_python/issues"
+Changelog = "https://github.com/antosubash/simple_module_python/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

simple_module_core-0.0.1/simple_module_core/__init__.py

@@ -0,0 +1,76 @@
+"""SimpleModule Core - Module system, menu, permissions, events, and diagnostics."""
+
+from simple_module_core.diagnostics import (
+    DiagnosticLevel,
+    MigrationDiagnostics,
+    print_diagnostics,
+    run_diagnostics,
+)
+from simple_module_core.discovery import (
+    discover_modules,
+    get_module_package_name,
+    topological_sort,
+)
+from simple_module_core.events import Event, EventBus
+from simple_module_core.exceptions import (
+    CircularDependencyError,
+    FrameworkVersionError,
+    InvalidModuleError,
+    ModuleError,
+    NotFoundError,
+    ValidationError,
+)
+from simple_module_core.feature_flags import (
+    FeatureFlagDefinition,
+    FeatureFlagRegistry,
+    feature_flag,
+    flag_enabled,
+    is_flag_enabled,
+    require_flag,
+)
+from simple_module_core.health import HealthCheck, HealthCheckResult, HealthRegistry, HealthStatus
+from simple_module_core.i18n import I18nRegistry, Translator
+from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
+from simple_module_core.module import ModuleBase, ModuleMeta
+from simple_module_core.permissions import PermissionRegistry
+from simple_module_core.services import Services
+from simple_module_core.versioning import FRAMEWORK_API_VERSION, check_framework_compatibility
+
+__all__ = [
+    "FRAMEWORK_API_VERSION",
+    "CircularDependencyError",
+    "DiagnosticLevel",
+    "Event",
+    "EventBus",
+    "FeatureFlagDefinition",
+    "FeatureFlagRegistry",
+    "FrameworkVersionError",
+    "HealthCheck",
+    "HealthCheckResult",
+    "HealthRegistry",
+    "HealthStatus",
+    "I18nRegistry",
+    "InvalidModuleError",
+    "MenuItem",
+    "MenuRegistry",
+    "MenuSection",
+    "MigrationDiagnostics",
+    "ModuleBase",
+    "ModuleError",
+    "ModuleMeta",
+    "NotFoundError",
+    "PermissionRegistry",
+    "Services",
+    "Translator",
+    "ValidationError",
+    "check_framework_compatibility",
+    "discover_modules",
+    "feature_flag",
+    "flag_enabled",
+    "get_module_package_name",
+    "is_flag_enabled",
+    "print_diagnostics",
+    "require_flag",
+    "run_diagnostics",
+    "topological_sort",
+]

simple_module_core-0.0.1/simple_module_core/__main__.py

@@ -0,0 +1,96 @@
+"""Run module diagnostics from the command line.
+
+Usage::
+
+    python -m simple_module_core        # discover modules, run diagnostics
+    make doctor                         # same thing, wrapped
+
+Exits with status 1 if any ERROR-level diagnostics are reported.
+
+i18n checks are included when ``SM_I18N_SUPPORTED_LOCALES`` is set in env
+(or ``.env``). Host-level ``host/locales/`` and shared ``packages/ui/locales/``
+are picked up relative to ``SM_PROJECT_ROOT`` (or the current working dir).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+from simple_module_core.diagnostics import (
+    DiagnosticLevel,
+    print_diagnostics,
+    run_diagnostics,
+)
+from simple_module_core.discovery import discover_modules, topological_sort
+from simple_module_core.dotenv import parse_dotenv
+
+
+def _load_i18n_settings_from_env() -> tuple[list[str], str] | tuple[None, None]:
+    """Return ``(supported_locales, default_locale)`` or ``(None, None)`` if unset.
+
+    Reads env vars directly to avoid a dependency on ``simple_module_hosting``.
+    Honors ``.env`` by merging it into ``os.environ`` if present (pydantic-
+    settings isn't imported here).
+    """
+    for key, value in parse_dotenv().items():
+        os.environ.setdefault(key, value)
+
+    supported_raw = os.environ.get("SM_I18N_SUPPORTED_LOCALES")
+    if not supported_raw:
+        return None, None
+
+    try:
+        supported = json.loads(supported_raw)
+    except json.JSONDecodeError:
+        # Also accept comma-separated (e.g. "en,es,de").
+        supported = [s.strip() for s in supported_raw.split(",") if s.strip()]
+
+    if not isinstance(supported, list) or not supported:
+        return None, None
+
+    default = os.environ.get("SM_I18N_DEFAULT_LOCALE", "en")
+    return supported, default
+
+
+def _discover_extra_locale_sources() -> list[tuple[str, str, Path]]:
+    """Return ``[(reporter, namespace, path), ...]`` for host + ui locale dirs."""
+    root = Path(os.environ.get("SM_PROJECT_ROOT") or Path.cwd())
+    out: list[tuple[str, str, Path]] = []
+    host_locales = root / "host" / "locales"
+    if host_locales.is_dir():
+        out.append(("host", "host", host_locales))
+    ui_locales = root / "packages" / "ui" / "locales"
+    if ui_locales.is_dir():
+        out.append(("packages/ui", "ui", ui_locales))
+    return out
+
+
+def main() -> int:
+    modules = discover_modules()
+    if not modules:
+        print("No modules discovered. Is the project installed (`uv sync --all-packages`)?")
+        return 0
+
+    # Topological sort surfaces CircularDependencyError early.
+    modules = topological_sort(modules)
+
+    supported, default = _load_i18n_settings_from_env()
+    extra = _discover_extra_locale_sources()
+
+    diagnostics = run_diagnostics(
+        modules,
+        i18n_supported_locales=supported,
+        i18n_default_locale=default,
+        i18n_extra_sources=extra,
+    )
+    print_diagnostics(diagnostics)
+
+    errors = [d for d in diagnostics if d.level == DiagnosticLevel.ERROR]
+    return 1 if errors else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

simple_module_core-0.0.1/simple_module_core/diagnostics/__init__.py

@@ -0,0 +1,24 @@
+"""Module diagnostics — validates structure and patterns at startup or via CLI.
+
+This is the public surface re-exported from the submodules below.
+Callers import from ``simple_module_core.diagnostics`` and should not
+need to reach into ``._module`` or ``._migration`` directly.
+"""
+
+from __future__ import annotations
+
+from simple_module_core.diagnostics._i18n import I18nDiagnostics
+from simple_module_core.diagnostics._migration import MigrationDiagnostics
+from simple_module_core.diagnostics._module import ModuleDiagnostics
+from simple_module_core.diagnostics._runner import print_diagnostics, run_diagnostics
+from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
+
+__all__ = [
+    "Diagnostic",
+    "DiagnosticLevel",
+    "I18nDiagnostics",
+    "MigrationDiagnostics",
+    "ModuleDiagnostics",
+    "print_diagnostics",
+    "run_diagnostics",
+]

simple_module_core-0.0.1/simple_module_core/diagnostics/_coupling.py

@@ -0,0 +1,81 @@
+"""SM009: detect framework packages that import from plugin module packages."""
+
+from __future__ import annotations
+
+import ast
+import importlib.util
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
+
+if TYPE_CHECKING:
+    from simple_module_core.module import ModuleBase
+
+FRAMEWORK_PACKAGES = ("simple_module_core", "simple_module_hosting", "simple_module_db")
+
+
+def _find_package_dir(package_name: str) -> Path | None:
+    spec = importlib.util.find_spec(package_name)
+    if spec and spec.submodule_search_locations:
+        locations = list(spec.submodule_search_locations)
+        if locations:
+            return Path(locations[0])
+    return None
+
+
+def _imported_plugin_pkg(node: ast.AST, module_packages: dict[str, str]) -> str | None:
+    if isinstance(node, ast.Import):
+        for alias in node.names:
+            top = alias.name.split(".")[0]
+            if top in module_packages:
+                return top
+    elif isinstance(node, ast.ImportFrom) and node.module:
+        top = node.module.split(".")[0]
+        if top in module_packages:
+            return top
+    return None
+
+
+def check_framework_module_coupling(modules: list[ModuleBase]) -> list[Diagnostic]:
+    """The framework (core, hosting, db) must never import from a plugin module."""
+    module_packages: dict[str, str] = {
+        type(mod).__module__.split(".")[0]: mod.meta.name for mod in modules
+    }
+    if not module_packages:
+        return []
+
+    framework_dirs: list[tuple[str, Path]] = []
+    for fw_pkg in FRAMEWORK_PACKAGES:
+        fw_dir = _find_package_dir(fw_pkg)
+        if fw_dir:
+            framework_dirs.append((fw_pkg, fw_dir))
+
+    diags: list[Diagnostic] = []
+    for fw_pkg, fw_dir in framework_dirs:
+        for py_file in fw_dir.rglob("*.py"):
+            try:
+                tree = ast.parse(py_file.read_text(), filename=str(py_file))
+            except SyntaxError:
+                continue
+            for node in ast.walk(tree):
+                imported_pkg = _imported_plugin_pkg(node, module_packages)
+                if imported_pkg:
+                    diags.append(
+                        Diagnostic(
+                            level=DiagnosticLevel.ERROR,
+                            code="SM009",
+                            message=(
+                                f"Framework package '{fw_pkg}' directly imports "
+                                f"from module package '{imported_pkg}'"
+                            ),
+                            module_name=module_packages[imported_pkg],
+                            file=str(py_file),
+                            suggestion=(
+                                "Use a ModuleBase lifecycle hook "
+                                "(register_middleware, register_routes, etc.) "
+                                "instead of importing module code from the framework"
+                            ),
+                        )
+                    )
+    return diags

simple_module_core-0.0.1/simple_module_core/diagnostics/_i18n.py

@@ -0,0 +1,121 @@
+"""Diagnostics that validate i18n locale file coverage and consistency."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from simple_module_core.diagnostics._types import Diagnostic, DiagnosticLevel
+from simple_module_core.i18n import flatten_messages
+
+if TYPE_CHECKING:
+    from simple_module_core.module import ModuleBase
+
+
+class I18nDiagnostics:
+    """Validates locale file coverage per module.
+
+    Codes:
+    - SM013: missing locale file for a supported locale.
+    - SM014: non-default locale is missing keys present in the default.
+    - SM015: non-default locale has keys not present in the default.
+    - SM016: locale JSON fails to parse or has non-string leaves.
+    """
+
+    def __init__(
+        self,
+        supported_locales: list[str],
+        default_locale: str,
+        extra_sources: list[tuple[str, str, Path]] | None = None,
+    ) -> None:
+        """Build the diagnostic.
+
+        ``extra_sources`` is an optional list of ``(reporter_name, namespace,
+        locale_dir)`` triples for locale directories that aren't owned by any
+        ``ModuleBase`` instance — notably the host's ``host/locales/`` and
+        the shared ``packages/ui/locales/``. ``reporter_name`` is used as the
+        ``module_name`` field on findings for display purposes.
+        """
+        self.supported_locales = list(supported_locales)
+        self.default_locale = default_locale
+        self.extra_sources = list(extra_sources or [])
+
+    def run(self, modules: list[ModuleBase]) -> list[Diagnostic]:
+        findings: list[Diagnostic] = []
+        for mod in modules:
+            for namespace, locale_dir in mod.locale_dirs().items():
+                findings.extend(self._check_namespace(mod.meta.name, namespace, Path(locale_dir)))
+        for reporter_name, namespace, locale_dir in self.extra_sources:
+            findings.extend(self._check_namespace(reporter_name, namespace, Path(locale_dir)))
+        return findings
+
+    def _check_namespace(
+        self, module_name: str, namespace: str, locale_dir: Path
+    ) -> list[Diagnostic]:
+        findings: list[Diagnostic] = []
+        per_locale_keys: dict[str, set[str]] = {}
+
+        for locale in self.supported_locales:
+            path = locale_dir / f"{locale}.json"
+            if not path.is_file():
+                findings.append(
+                    Diagnostic(
+                        level=DiagnosticLevel.WARNING,
+                        code="SM013",
+                        message=(f"Missing locale file {locale}.json for namespace '{namespace}'"),
+                        module_name=module_name,
+                        file=str(path),
+                        suggestion=f"Create {path} (even if empty: '{{}}')",
+                    )
+                )
+                continue
+            try:
+                raw = json.loads(path.read_text(encoding="utf-8"))
+                if not isinstance(raw, dict):
+                    raise ValueError("top-level JSON must be an object")
+                flat = flatten_messages(raw)
+            except (json.JSONDecodeError, ValueError) as exc:
+                findings.append(
+                    Diagnostic(
+                        level=DiagnosticLevel.ERROR,
+                        code="SM016",
+                        message=f"Invalid locale JSON in {path}: {exc}",
+                        module_name=module_name,
+                        file=str(path),
+                    )
+                )
+                continue
+            per_locale_keys[locale] = set(flat.keys())
+
+        default_keys = per_locale_keys.get(self.default_locale, set())
+        for locale, keys in per_locale_keys.items():
+            if locale == self.default_locale:
+                continue
+            missing = default_keys - keys
+            extra = keys - default_keys
+            if missing:
+                findings.append(
+                    Diagnostic(
+                        level=DiagnosticLevel.WARNING,
+                        code="SM014",
+                        message=(
+                            f"Locale '{locale}' in namespace '{namespace}' is missing keys: "
+                            f"{', '.join(sorted(missing))}"
+                        ),
+                        module_name=module_name,
+                    )
+                )
+            if extra:
+                findings.append(
+                    Diagnostic(
+                        level=DiagnosticLevel.WARNING,
+                        code="SM015",
+                        message=(
+                            f"Locale '{locale}' in namespace '{namespace}' has keys not in "
+                            f"default: {', '.join(sorted(extra))}"
+                        ),
+                        module_name=module_name,
+                    )
+                )
+        return findings