bedrock-core 0.1.0__tar.gz

bedrock_core-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: bedrock-core
+Version: 0.1.0
+Summary: A modular Python application framework with manifest-driven module loading, lifecycle management, and contrib modules.
+Keywords: framework,modular,module-system,lifecycle,sqlalchemy
+Author: maacck
+Author-email: maacck <c.mai@madainchina.com>
+License-Expression: MIT
+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: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Dist: alembic>=1.18.4
+Requires-Dist: asgiref>=3.8.1
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: orjson>=3.11.8
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pydantic-settings>=2.13.1
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: sqlalchemy>=2.0.49
+Requires-Dist: typer>=0.24.1
+Requires-Dist: redis>=4.2.0 ; extra == 'cache-redis'
+Requires-Python: >=3.12
+Project-URL: Bug Tracker, https://github.com/maacck/bedrock-py/issues
+Project-URL: Documentation, https://bedrock-py.com
+Project-URL: Homepage, https://bedrock-py.com
+Project-URL: Repository, https://github.com/maacck/bedrock-py
+Provides-Extra: cache-redis
+Description-Content-Type: text/markdown
+
+# bedrock
+
+`bedrock` is the runtime core of the Bedrock modular framework.
+
+It provides manifest-driven module loading, lifecycle management, and first-party contrib modules for common capabilities.
+
+## Status
+
+**The core runtime is fully implemented and functional.**
+
+This package contains production-ready subsystems:
+
+- Module registry with dependency resolution and lifecycle hooks
+- Dependency injection container with singleton/transient/scoped lifetimes
+- Hook system for structured call/response extension points (sync, async, robust)
+- SQLAlchemy 2.0 database layer with Alembic migrations
+- Cache system with memory and Redis backends
+- Signal/event system (blinker-derived)
+- Typer-based CLI for module and database management
+- Comprehensive utility library (lazy loading, introspection, string helpers)
+
+## Installation
+
+```bash
+# With uv (recommended)
+uv add bedrock-core
+
+# With poetry
+poetry add bedrock-core
+
+# With pip
+pip install bedrock-core
+```
+
+## Quick Start
+
+```python
+import bedrock
+
+# Initialize the runtime (discovers and loads modules)
+bedrock.setup()
+
+# Access key singletons
+from bedrock.module import apps          # ModuleRegistry
+from bedrock.database import db          # DatabaseManager
+from bedrock.contrib.cache import cache  # CacheService
+```
+
+## Key Singletons
+
+| Singleton | Class | Import |
+|-----------|-------|--------|
+| `apps` | `ModuleRegistry` | `from bedrock.module import apps` |
+| `container` | `Container` | `from bedrock.di import container` |
+| `hooks` | `HookRegistry` | `from bedrock.hooks import hooks` |
+| `db` | `DatabaseManager` | `from bedrock.database import db` |
+| `cache` | `CacheService` | `from bedrock.contrib.cache import cache` |
+
+## Module Structure
+
+```
+modules/
+└── inventory/
+    ├── __init__.py
+    ├── manifest.yaml    # Module identity and dependencies
+    ├── models.py        # SQLAlchemy models (optional)
+    ├── entities.py      # Pydantic models for validation
+    ├── service.py       # Business logic
+    ├── exc.py           # Module exceptions
+    └── bootstrap.py     # Lifecycle hooks
+```
+
+## Architecture
+
+Bedrock is framework-agnostic by design. The core runtime has no HTTP dependencies and is usable in:
+
+- API servers (FastAPI, Flask, etc.)
+- Background workers (Celery, etc.)
+- CLI tools
+- Scripts and automation
+
+For more details, see the [documentation](https://bedrock-py.com).

bedrock_core-0.1.0/README.md

@@ -0,0 +1,82 @@
+# bedrock
+
+`bedrock` is the runtime core of the Bedrock modular framework.
+
+It provides manifest-driven module loading, lifecycle management, and first-party contrib modules for common capabilities.
+
+## Status
+
+**The core runtime is fully implemented and functional.**
+
+This package contains production-ready subsystems:
+
+- Module registry with dependency resolution and lifecycle hooks
+- Dependency injection container with singleton/transient/scoped lifetimes
+- Hook system for structured call/response extension points (sync, async, robust)
+- SQLAlchemy 2.0 database layer with Alembic migrations
+- Cache system with memory and Redis backends
+- Signal/event system (blinker-derived)
+- Typer-based CLI for module and database management
+- Comprehensive utility library (lazy loading, introspection, string helpers)
+
+## Installation
+
+```bash
+# With uv (recommended)
+uv add bedrock-core
+
+# With poetry
+poetry add bedrock-core
+
+# With pip
+pip install bedrock-core
+```
+
+## Quick Start
+
+```python
+import bedrock
+
+# Initialize the runtime (discovers and loads modules)
+bedrock.setup()
+
+# Access key singletons
+from bedrock.module import apps          # ModuleRegistry
+from bedrock.database import db          # DatabaseManager
+from bedrock.contrib.cache import cache  # CacheService
+```
+
+## Key Singletons
+
+| Singleton | Class | Import |
+|-----------|-------|--------|
+| `apps` | `ModuleRegistry` | `from bedrock.module import apps` |
+| `container` | `Container` | `from bedrock.di import container` |
+| `hooks` | `HookRegistry` | `from bedrock.hooks import hooks` |
+| `db` | `DatabaseManager` | `from bedrock.database import db` |
+| `cache` | `CacheService` | `from bedrock.contrib.cache import cache` |
+
+## Module Structure
+
+```
+modules/
+└── inventory/
+    ├── __init__.py
+    ├── manifest.yaml    # Module identity and dependencies
+    ├── models.py        # SQLAlchemy models (optional)
+    ├── entities.py      # Pydantic models for validation
+    ├── service.py       # Business logic
+    ├── exc.py           # Module exceptions
+    └── bootstrap.py     # Lifecycle hooks
+```
+
+## Architecture
+
+Bedrock is framework-agnostic by design. The core runtime has no HTTP dependencies and is usable in:
+
+- API servers (FastAPI, Flask, etc.)
+- Background workers (Celery, etc.)
+- CLI tools
+- Scripts and automation
+
+For more details, see the [documentation](https://bedrock-py.com).

bedrock_core-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[project]
+name = "bedrock-core"
+version = "0.1.0"
+description = "A modular Python application framework with manifest-driven module loading, lifecycle management, and contrib modules."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "maacck", email = "c.mai@madainchina.com" }
+]
+keywords = ["framework", "modular", "module-system", "lifecycle", "sqlalchemy"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "alembic>=1.18.4",
+    "asgiref>=3.8.1",
+    "loguru>=0.7.0",
+    "orjson>=3.11.8",
+    "pydantic>=2.12.5",
+    "pydantic-settings>=2.13.1",
+    "pyyaml>=6.0.2",
+    "sqlalchemy>=2.0.49",
+    "typer>=0.24.1",
+]
+
+[project.urls]
+Homepage = "https://bedrock-py.com"
+Repository = "https://github.com/maacck/bedrock-py"
+Documentation = "https://bedrock-py.com"
+"Bug Tracker" = "https://github.com/maacck/bedrock-py/issues"
+
+[project.optional-dependencies]
+cache-redis = ["redis>=4.2.0"]
+
+[project.scripts]
+bedrock = "bedrock.cli.main:entrypoint"
+
+[build-system]
+requires = ["uv_build>=0.8.15,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = "src"
+module-name = "bedrock"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+    "pytest-asyncio>=1.2.0",
+    "coverage>=7.13.5",
+    "pytest-cov>=7.1.0",
+]

bedrock_core-0.1.0/src/bedrock/__init__.py

@@ -0,0 +1,67 @@
+from .conf import SettingsProxy
+from .entities import BedrockEntity
+from .logging import get_logger
+from .module import ModuleRegistry, apps
+
+__all__ = [
+    "ModuleRegistry",
+    "apps",
+    "BedrockEntity",
+    "setup",
+    "get_logger",
+    "SettingsProxy",
+]
+
+
+def setup(app: str | None = None) -> None:
+    """Bootstrap the Bedrock application registry.
+
+    Reads the target app from the ``app`` argument, falling back to the
+    ``BEDROCK_APP`` environment variable (via :attr:`bedrock.settings.settings`).
+    Calls :meth:`~bedrock.module.ModuleRegistry.populate` on the global
+    :data:`apps` registry, which installs modules and fires lifecycle hooks.
+
+    This function is idempotent: if the registry is already ready it returns
+    immediately without re-populating.
+
+    Args:
+        app: Dotted import path of the root application module to install,
+            e.g. ``"myproject.app"``.  When *None* the value is read from
+            ``BEDROCK_APP`` in the environment.
+
+    Raises:
+        ImproperlyConfigured: When no app name can be resolved.
+
+    Example — ASGI entry-point (``myproject/asgi.py``)::
+
+        import bedrock
+
+        bedrock.setup()
+
+        from myproject.api import create_app
+
+        application = create_app()
+
+    Example — Celery entry-point (``myproject/celery.py``)::
+
+        import bedrock
+
+        bedrock.setup()
+
+        from celery import Celery
+
+        app = Celery("myproject")
+    """
+    if apps.ready:
+        return
+
+    from bedrock.exc import ImproperlyConfigured
+    from bedrock.settings import settings
+
+    app_name = app or settings.APP
+    if app_name is None:
+        raise ImproperlyConfigured(
+            "No app specified. Pass an app name to setup() or set the BEDROCK_APP environment variable."
+        )
+
+    apps.populate([app_name])

bedrock_core-0.1.0/src/bedrock/cli/apps.py

@@ -0,0 +1,290 @@
+"""Application inspection and management commands for Bedrock modules."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from importlib.util import find_spec
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from bedrock.utils import inspect_func
+
+from ..module.exc import InvalidManifestError, InvalidModuleCallableError, ModuleError
+from ..module.manifest import build_app_config, load_manifest
+from ..utils.lazyload import load_optional_callable
+
+apps = typer.Typer(
+    rich_markup_mode="rich",
+    help="Manage Bedrock applications and modules.",
+)
+
+
+@dataclass
+class InspectResult:
+    """Result of a basic module inspection."""
+
+    import_path: str
+    manifest_valid: bool = False
+    module_loads: bool = False
+    has_bootstrap: bool = False
+    has_models: bool = False
+    installation_valid: bool = False
+    errors: list[str] = field(default_factory=list)
+
+
+def _status_icon(passed: bool, *, optional: bool = False) -> str:
+    """Return a colored status icon for Rich table display."""
+    if passed:
+        return "[bold green]✓[/bold green]"
+    return "[dim]-[/dim]" if optional else "[bold red]✗[/bold red]"
+
+
+def _check_installation_hooks(func: Callable):
+    if not inspect_func.func_accepts_kwargs(func):
+        raise InvalidModuleCallableError(
+            f"Installation hook '{func.__module__}.{func.__name__}' must accept **kwargs for future extensibility."
+        )
+
+
+def _run_basic_inspect(import_path: str, console: Console) -> InspectResult:
+    """Validate manifest, loadability, submodules, and installation hooks with console output."""
+    result = InspectResult(import_path=import_path)
+
+    try:
+        load_manifest(import_path)
+        result.manifest_valid = True
+        console.print(f"[bold green]✓[/bold green] Manifest for ''[bold]{import_path}[/bold]'' is valid.")
+    except InvalidManifestError as exc:
+        result.errors.append(f"Manifest validation failed: {exc}")
+        console.print(f"[bold red]✗[/bold red] Manifest validation failed: {exc}")
+        return result
+
+    try:
+        app_config = build_app_config(import_path)
+        result.module_loads = True
+        console.print(f"[bold green]✓[/bold green] Module ''[bold]{import_path}[/bold]'' loads successfully.")
+
+        if app_config.bootstrap_module:
+            result.has_bootstrap = True
+            console.print("[bold green]✓[/bold green] Bootstrap submodule is available.")
+        else:
+            console.print("[bold yellow]![/bold yellow] No bootstrap submodule found.")
+
+        if app_config.models_module:
+            result.has_models = True
+            console.print("[bold green]✓[/bold green] Models submodule is available.")
+        else:
+            console.print("[bold yellow]![/bold yellow] No models submodule found.")
+    except ModuleError as exc:
+        result.errors.append(f"Module load failed: {exc}")
+        console.print(f"[bold red]✗[/bold red] Module load failed: {exc}")
+        return result
+
+    try:
+        installation = load_optional_callable(f"{app_config.name}.installation:install")
+        if not installation:
+            result.errors.append(f"No 'install' function found in installation.py for {app_config.name}.")
+            console.print(
+                f"[bold red]✗[/bold red] No 'install' function found in installation.py for {app_config.name}."
+            )
+            return result
+        _check_installation_hooks(installation)
+        pre_install = load_optional_callable(f"{app_config.name}.installation:pre_install")
+        if pre_install:
+            _check_installation_hooks(pre_install)
+        installation()
+        post_install = load_optional_callable(f"{app_config.name}.installation:post_install")
+        if post_install:
+            _check_installation_hooks(post_install)
+        result.installation_valid = True
+        console.print(
+            f"[bold green]✓[/bold green] Installation hooks for '{app_config.name}' are valid and executable."
+        )
+    except (InvalidModuleCallableError, ModuleError) as exc:
+        result.errors.append(f"Installation hook check failed: {exc}")
+        console.print(f"[bold red]✗[/bold red] Installation hook check failed: {exc}")
+
+    return result
+
+
+def _inspect_dependency(dep_path: str) -> InspectResult:
+    """Run all inspection checks on a dependency without console output."""
+    result = InspectResult(import_path=dep_path)
+
+    spec = find_spec(dep_path)
+    if spec is None:
+        result.errors.append(f"Cannot import: package '{dep_path}' not found in Python path.")
+        return result
+
+    try:
+        load_manifest(dep_path)
+        result.manifest_valid = True
+    except InvalidManifestError as exc:
+        result.errors.append(f"Manifest: {exc}")
+        return result
+
+    try:
+        app_config = build_app_config(dep_path)
+        result.module_loads = True
+        result.has_bootstrap = app_config.bootstrap_module is not None
+        result.has_models = app_config.models_module is not None
+    except ModuleError as exc:
+        result.errors.append(f"Load: {exc}")
+        return result
+
+    try:
+        installation = load_optional_callable(f"{app_config.name}.installation:install")
+        if not installation:
+            result.errors.append(f"No 'install' function in installation.py for {app_config.name}.")
+            return result
+        _check_installation_hooks(installation)
+        pre_install = load_optional_callable(f"{app_config.name}.installation:pre_install")
+        if pre_install:
+            _check_installation_hooks(pre_install)
+        installation()
+        post_install = load_optional_callable(f"{app_config.name}.installation:post_install")
+        if post_install:
+            _check_installation_hooks(post_install)
+        result.installation_valid = True
+    except (InvalidModuleCallableError, ModuleError) as exc:
+        result.errors.append(f"Installation: {exc}")
+
+    return result
+
+
+@apps.command()
+def inspect(
+    import_path: str = typer.Argument(..., help="Python import path of the module, e.g., ''bedrock.contrib.cache''."),
+) -> None:
+    """Inspect a module''s manifest format and loadability.
+
+    Validates the manifest.yaml structure, checks bootstrap and models
+    submodules, installation hooks, and verifies that all declared
+    dependencies (depends_on) are importable and pass basic checks.
+
+    Args:
+        import_path: Python import path of the module.
+
+    Raises:
+        typer.Exit: If the manifest or module fails to load.
+    """
+    console = Console()
+
+    result = _run_basic_inspect(import_path, console)
+    if result.errors:
+        raise typer.Exit(1)
+
+    manifest = load_manifest(import_path)
+    if not manifest.depends_on:
+        console.print("\n[dim]No dependencies declared in depends_on.[/dim]")
+        return
+
+    console.print(f"\n[bold]Checking dependencies ({len(manifest.depends_on)})...[/bold]\n")
+
+    dep_results: list[InspectResult] = []
+    for dep_path in manifest.depends_on:
+        dep_results.append(_inspect_dependency(dep_path))
+
+    table = Table(title="Dependency Inspection", show_lines=True)
+    table.add_column("Module", style="bold cyan", no_wrap=True)
+    table.add_column("Importable", justify="center")
+    table.add_column("Manifest", justify="center")
+    table.add_column("Loads", justify="center")
+    table.add_column("Bootstrap", justify="center")
+    table.add_column("Models", justify="center")
+    table.add_column("Installation", justify="center")
+    table.add_column("Errors", style="red")
+
+    has_failures = False
+    for dep_result in dep_results:
+        importable = find_spec(dep_result.import_path) is not None
+        if not importable or dep_result.errors:
+            has_failures = True
+
+        table.add_row(
+            dep_result.import_path,
+            _status_icon(importable),
+            _status_icon(dep_result.manifest_valid),
+            _status_icon(dep_result.module_loads),
+            _status_icon(dep_result.has_bootstrap, optional=True),
+            _status_icon(dep_result.has_models, optional=True),
+            _status_icon(dep_result.installation_valid),
+            "; ".join(dep_result.errors) if dep_result.errors else "",
+        )
+
+    console.print(table)
+
+    if has_failures:
+        console.print("\n[bold red]✗[/bold red] Some dependencies failed inspection.")
+        raise typer.Exit(1)
+    else:
+        console.print("\n[bold green]✓[/bold green] All dependencies pass inspection.")
+
+
+@apps.command()
+def info(
+    import_path: str = typer.Argument(..., help="Python import path of the module, e.g., ''bedrock.contrib.cache''."),
+) -> None:
+    """Display rich information about a Bedrock module.
+
+    Shows the module title, description, version, dependencies, bootstrap
+    and models status, and configured commands.
+
+    Args:
+        import_path: Python import path of the module.
+
+    Raises:
+        typer.Exit: If the module cannot be loaded.
+    """
+    console = Console()
+
+    try:
+        app_config = build_app_config(import_path)
+        manifest = app_config.manifest
+    except (InvalidManifestError, ModuleError) as exc:
+        console.print(f"[bold red]Error:[/bold red] {exc}")
+        raise typer.Exit(1) from exc
+
+    table = Table(show_header=False, box=None, padding=(0, 1))
+    table.add_column("Property", style="bold cyan", no_wrap=True)
+    table.add_column("Value", style="white")
+
+    table.add_row("Title", manifest.title)
+    table.add_row("Description", manifest.description or "N/A")
+    table.add_row("Version", manifest.version)
+    table.add_row("Import Path", import_path)
+
+    if manifest.depends_on:
+        table.add_row("Dependencies", "\n".join(manifest.depends_on))
+    else:
+        table.add_row("Dependencies", "None")
+
+    table.add_row("Bootstrap", "Yes" if app_config.bootstrap_module else "No")
+    table.add_row("Models", "Yes" if app_config.models_module else "No")
+
+    if manifest.commands:
+        table.add_row("Commands", manifest.commands)
+
+    console.print(table)
+
+
+@apps.command()
+def install(
+    import_path: str = typer.Argument(..., help="Python import path of the module, e.g., ''bedrock.contrib.cache''."),
+) -> None:
+    """Install a Bedrock module.
+
+    This command is a skeleton placeholder and is not yet implemented.
+
+    Args:
+        import_path: Python import path of the module.
+    """
+    console = Console()
+    console.print("[bold yellow]⚠[/bold yellow] Install command is not yet implemented.")
+    console.print(f"[dim]Module: {import_path}[/dim]")
+
+
+__all__ = ["apps"]