nexus-framework 0.1.0__py3-none-any.whl

nexus/__init__.py

@@ -0,0 +1,169 @@
+"""Nexus Framework.
+
+Ultimate Simplicity, Uncompromising Power.
+"""
+
+from nexus.cli import main as cli_main
+from nexus.core.entities import (
+    FileResponse,
+    HTMLResponse,
+    HTTPMethod,
+    JSONResponse,
+    NexusRequest,
+    NexusResponse,
+    PlainTextResponse,
+    RedirectResponse,
+    StreamingResponse,
+)
+from nexus.data import (
+    DataFrame,
+    Pipeline,
+    PipelineTestClient,
+    PipelineTestResult,
+    load,
+    pipeline_registry,
+    save,
+    stream_csv,
+)
+from nexus.db import Field, Model, Relationship, db
+from nexus.deployment import (
+    GracefulShutdownManager,
+    generate_dockerfile,
+    generate_env_documentation,
+    run_app,
+)
+from nexus.magic.injector import (
+    CircularDependencyError,
+    DIContainer,
+    ProviderNotFoundError,
+    ScopeType,
+)
+from nexus.observability import (
+    Counter,
+    Gauge,
+    HealthCheckManager,
+    Histogram,
+    MetricsRegistry,
+    ObservabilityMiddleware,
+    Span,
+    Tracer,
+    health_manager,
+    metrics,
+    tracer,
+)
+from nexus.testing import TestClient, TestResponse
+from nexus.web.app import Nexus, NexusApp
+from nexus.web.background import BackgroundTask, BackgroundTasks
+from nexus.web.idempotency import IdempotencyMiddleware
+from nexus.web.middlewares import (
+    CORSMiddleware,
+    CSRFMiddleware,
+    GZipMiddleware,
+    RateLimitMiddleware,
+    RequestIdMiddleware,
+    SecurityHeadersMiddleware,
+    TimingMiddleware,
+    TrustedHostMiddleware,
+)
+from nexus.web.openapi import OpenAPIGenerator, get_redoc_html, get_swagger_ui_html
+from nexus.web.pagination import Page, paginate
+from nexus.web.router import Blueprint
+from nexus.web.security import (
+    constant_time_compare,
+    generate_hmac_signature,
+    generate_secure_token,
+    verify_hmac_signature,
+)
+from nexus.web.session import (
+    MemorySessionBackend,
+    SessionBackend,
+    SessionMiddleware,
+)
+from nexus.web.sse import EventSourceResponse, ServerSentEvent
+from nexus.web.staticfiles import StaticFiles
+from nexus.web.template.engine import NXEngine
+from nexus.web.upload import UploadFile
+from nexus.web.websocket import WebSocket, WebSocketDisconnect, WebSocketGroup
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BackgroundTask",
+    "BackgroundTasks",
+    "Blueprint",
+    "CORSMiddleware",
+    "CSRFMiddleware",
+    "CircularDependencyError",
+    "Counter",
+    "DIContainer",
+    "DataFrame",
+    "EventSourceResponse",
+    "Field",
+    "FileResponse",
+    "GZipMiddleware",
+    "Gauge",
+    "GracefulShutdownManager",
+    "HTMLResponse",
+    "HTTPMethod",
+    "HealthCheckManager",
+    "Histogram",
+    "IdempotencyMiddleware",
+    "JSONResponse",
+    "MemorySessionBackend",
+    "MetricsRegistry",
+    "Model",
+    "NXEngine",
+    "Nexus",
+    "NexusApp",
+    "NexusRequest",
+    "NexusResponse",
+    "ObservabilityMiddleware",
+    "OpenAPIGenerator",
+    "Page",
+    "Pipeline",
+    "PipelineTestClient",
+    "PipelineTestResult",
+    "PlainTextResponse",
+    "ProviderNotFoundError",
+    "RateLimitMiddleware",
+    "RedirectResponse",
+    "Relationship",
+    "RequestIdMiddleware",
+    "ScopeType",
+    "SecurityHeadersMiddleware",
+    "ServerSentEvent",
+    "SessionBackend",
+    "SessionMiddleware",
+    "Span",
+    "StaticFiles",
+    "StreamingResponse",
+    "TestClient",
+    "TestResponse",
+    "TimingMiddleware",
+    "Tracer",
+    "TrustedHostMiddleware",
+    "UploadFile",
+    "WebSocket",
+    "WebSocketDisconnect",
+    "WebSocketGroup",
+    "__version__",
+    "cli_main",
+    "constant_time_compare",
+    "db",
+    "generate_dockerfile",
+    "generate_env_documentation",
+    "generate_hmac_signature",
+    "generate_secure_token",
+    "get_redoc_html",
+    "get_swagger_ui_html",
+    "health_manager",
+    "load",
+    "metrics",
+    "paginate",
+    "pipeline_registry",
+    "run_app",
+    "save",
+    "stream_csv",
+    "tracer",
+    "verify_hmac_signature",
+]

nexus/cli.py

@@ -0,0 +1,194 @@
+"""Nexus Command Line Interface (CLI).
+
+Provides commands:
+- `nexus run [app]`
+- `nexus pipeline list`
+- `nexus pipeline run <name>`
+- `nexus db check`
+- `nexus dockerfile`
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+from typing import Any
+
+from nexus.data.pipeline import pipeline_registry
+
+
+def _handle_pipeline_list(
+    _args: argparse.Namespace, stdout: Any = sys.stdout, **_kwargs: Any
+) -> int:
+    pipelines = pipeline_registry.list_all()
+    if not pipelines:
+        print("No pipelines registered in current session.", file=stdout)
+        return 0
+
+    print(f"\nRegistered Data Pipelines ({len(pipelines)}):", file=stdout)
+    print("-" * 65, file=stdout)
+    print(f"{'NAME':<25} {'SCHEDULE':<15} {'LAST STATUS':<12} {'RUNS'}", file=stdout)
+    print("-" * 65, file=stdout)
+    for p in pipelines:
+        name = p.get("name", "unnamed")
+        schedule = p.get("schedule") or "manual"
+        last = p.get("last_run") or {}
+        last_status = last.get("status", "never_run")
+        total_runs = p.get("total_runs", 0)
+        print(f"{name:<25} {schedule:<15} {last_status:<12} {total_runs}", file=stdout)
+    print("-" * 65, file=stdout)
+    return 0
+
+
+def _handle_pipeline_run(
+    args: argparse.Namespace, stdout: Any = sys.stdout, stderr: Any = sys.stderr, **_kwargs: Any
+) -> int:
+    name: str = args.name
+    pipe = pipeline_registry.get(name)
+    if pipe is None:
+        print(f"Error: Pipeline '{name}' not found.", file=stderr)
+        return 1
+
+    print(f"Executing pipeline: {name} ...", file=stdout)
+    try:
+        res = asyncio.run(pipe.run())
+        count = len(res) if hasattr(res, "__len__") else 0
+        print(f"Success: Pipeline '{name}' completed. Processed {count} records.", file=stdout)
+        return 0
+    except Exception as exc:
+        print(f"Failure: Pipeline '{name}' failed with error: {exc}", file=stderr)
+        return 1
+
+
+def _handle_dockerfile(args: argparse.Namespace, stdout: Any = sys.stdout, **_kwargs: Any) -> int:
+    from pathlib import Path
+
+    from nexus.deployment import generate_dockerfile
+
+    out_path = args.output or "Dockerfile"
+    generate_dockerfile(output_path=out_path)
+    print(f"Generated Dockerfile at {out_path}", file=stdout)
+    if not args.output:
+        print(Path(out_path).read_text(encoding="utf-8"), file=stdout)
+    return 0
+
+
+def _handle_init(args: argparse.Namespace, stdout: Any = sys.stdout, **_kwargs: Any) -> int:
+    from pathlib import Path
+
+    project_name = args.name or "my_nexus_app"
+    target_dir = Path(project_name).resolve()
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    app_py_code = '''"""Entrypoint for {project_name} application."""
+
+from nexus import NexusApp, JSONResponse, Model, Field
+from nexus.db import configure_db
+
+app = NexusApp(title="{project_name}")
+
+class Item(Model):
+    name: str = Field(index=True)
+    description: str = Field(default="")
+
+    class Meta:
+        table_name = "items"
+
+@app.lifespan.on_startup
+async def startup() -> None:
+    configure_db("sqlite+aiosqlite:///app.db")
+    await Item.create_table()
+
+@app.get("/")
+def home() -> JSONResponse:
+    return JSONResponse({{
+        "app": "{project_name}",
+        "message": "Welcome to your new Nexus web application!",
+        "docs": "/docs",
+        "health": "/health"
+    }})
+
+@app.get("/items")
+async def list_items() -> JSONResponse:
+    items = await Item.where().all()
+    return JSONResponse([item.to_dict() for item in items])
+
+if __name__ == "__main__":
+    from nexus.deployment import run_app
+    run_app(app, host="127.0.0.1", port=8000)
+'''
+
+    env_code = """APP_NAME={project_name}
+APP_ENV=development
+APP_DEBUG=true
+APP_HOST=127.0.0.1
+APP_PORT=8000
+DATABASE_URL=sqlite+aiosqlite:///app.db
+SECRET_KEY=nexus-insecure-dev-secret-key-change-in-production
+"""
+
+    app_file = target_dir / "app.py"
+    app_file.write_text(app_py_code.format(project_name=project_name), encoding="utf-8")
+    env_file = target_dir / ".env"
+    env_file.write_text(env_code.format(project_name=project_name), encoding="utf-8")
+
+    print(f"\n🎉 Successfully created Nexus project template: {project_name}/", file=stdout)
+    print(f"   ├── {project_name}/app.py", file=stdout)
+    print(f"   └── {project_name}/.env\n", file=stdout)
+    print("Next steps to run your app:", file=stdout)
+    print(f"   cd {project_name}", file=stdout)
+    print("   python app.py\n", file=stdout)
+    print("Open http://127.0.0.1:8000 in your browser (or /docs for Swagger UI)!", file=stdout)
+    return 0
+
+
+def main(
+    argv: list[str] | None = None,
+    stdout: Any = sys.stdout,
+    stderr: Any = sys.stderr,
+) -> int:
+    """Main CLI entrypoint for Nexus."""
+    parser = argparse.ArgumentParser(
+        prog="nexus",
+        description="Nexus Next-Gen Python Framework CLI",
+    )
+    subparsers = parser.add_subparsers(dest="subcommand", help="Available subcommands")
+
+    # Project Initializer (like django-admin startproject)
+    init_p = subparsers.add_parser("init", help="Scaffold a new production-ready Nexus project")
+    init_p.add_argument("name", nargs="?", default="my_nexus_app", help="Project directory name")
+    init_p.set_defaults(handler=_handle_init)
+
+    # Pipeline commands
+    pipe_parser = subparsers.add_parser("pipeline", help="Manage data pipelines")
+    pipe_sub = pipe_parser.add_subparsers(dest="pipe_action", help="Pipeline action")
+
+    list_p = pipe_sub.add_parser("list", help="List all registered data pipelines")
+    list_p.set_defaults(handler=_handle_pipeline_list)
+
+    run_p = pipe_sub.add_parser("run", help="Trigger a pipeline execution")
+    run_p.add_argument("name", help="Name of the pipeline to execute")
+    run_p.set_defaults(handler=_handle_pipeline_run)
+
+    # Dockerfile generator
+    doc_p = subparsers.add_parser("dockerfile", help="Generate production Dockerfile")
+    doc_p.add_argument("--port", type=int, default=8000, help="Container port (default: 8000)")
+    doc_p.add_argument(
+        "--workers", type=int, default=4, help="Number of worker processes (default: 4)"
+    )
+    doc_p.add_argument("--python-version", default="3.12-slim", help="Base Python Docker image tag")
+    doc_p.add_argument("-o", "--output", help="Output file path (e.g. Dockerfile)")
+    doc_p.set_defaults(handler=_handle_dockerfile)
+
+    args = parser.parse_args(argv)
+    handler: Any = getattr(args, "handler", None)
+    if handler is not None:
+        return int(handler(args, stdout=stdout, stderr=stderr))
+
+    parser.print_help(stdout)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

nexus/config/__init__.py

@@ -0,0 +1,5 @@
+"""Nexus Configuration package."""
+
+from nexus.config.settings import Environment, NexusSettings, get_settings
+
+__all__ = ["Environment", "NexusSettings", "get_settings"]

nexus/config/settings.py

@@ -0,0 +1,98 @@
+"""Nexus Configuration System.
+
+Built on pydantic-settings with strong validation, environment variable loading,
+and hierarchical override support.
+"""
+
+from enum import StrEnum
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Environment(StrEnum):
+    """Application runtime environments."""
+
+    DEVELOPMENT = "development"
+    TESTING = "testing"
+    STAGING = "staging"
+    PRODUCTION = "production"
+
+
+class NexusSettings(BaseSettings):
+    """Base application settings for any Nexus service.
+
+    Reads automatically from environment variables and `.env` file.
+    """
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        env_prefix="NEXUS_",
+        extra="ignore",
+    )
+
+    # Core Application Settings
+    app_name: str = Field(default="Nexus Application", description="Application name")
+    env: Environment = Field(default=Environment.DEVELOPMENT, description="Runtime environment")
+    debug: bool = Field(default=True, description="Enable debug mode")
+    secret_key: str = Field(
+        default="nexus-insecure-secret-key-change-in-production",
+        description="Cryptographic secret key for tokens and sessions",
+    )
+
+    # Server Network & Performance Settings
+    host: str = Field(default="127.0.0.1", description="Host address to bind server")
+    port: int = Field(default=8000, description="Port number to bind server")
+    workers: int = Field(default=1, description="Worker processes for server")
+    max_body_size: int = Field(
+        default=10 * 1024 * 1024,
+        description="Maximum allowed request body size in bytes (default: 10MB)",
+    )
+    slow_request_threshold_ms: float = Field(
+        default=1000.0,
+        description="Threshold in milliseconds above which a request is logged as slow",
+    )
+
+    # Logging Settings
+    log_level: str = Field(default="INFO", description="Log level: DEBUG, INFO, WARNING, ERROR")
+    log_format: str = Field(
+        default="console", description="Logging output format: 'console' or 'json'"
+    )
+
+    # Database Settings (Placeholder for Phase 5)
+    database_url: str | None = Field(default=None, description="Database connection URL")
+
+    # Redis Settings
+    redis_url: str | None = Field(default=None, description="Redis connection URL")
+
+    # Security & CORS Settings (Auto-configured in Middlewares)
+    allowed_hosts: list[str] = Field(
+        default=["*"], description="Allowed hosts for TrustedHostMiddleware"
+    )
+    cors_origins: list[str] = Field(default=["*"], description="Allowed CORS origins")
+
+    @property
+    def is_production(self) -> bool:
+        """Helper to quickly check if running in production."""
+        return self.env == Environment.PRODUCTION
+
+    @property
+    def is_development(self) -> bool:
+        """Helper to check if running in local development."""
+        return self.env == Environment.DEVELOPMENT
+
+
+# Global helper function for default settings
+def get_settings(env_file: Path | str | None = None) -> NexusSettings:
+    """Instantiate and retrieve Nexus application settings with env file discovery."""
+    if env_file:
+        return NexusSettings(_env_file=env_file)  # type: ignore[call-arg]
+
+    # Auto-detect environment-specific file: .env.development or .env.production
+    for candidate in (".env.development", ".env.production", ".env"):
+        if Path(candidate).is_file():
+            return NexusSettings(_env_file=candidate)  # type: ignore[call-arg]
+
+    return NexusSettings()

nexus/core/__init__.py

@@ -0,0 +1 @@
+"""Nexus core module containing protocols, entities, and base exceptions."""