caprail 0.1.0__tar.gz

caprail-0.1.0/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.3
+Name: caprail
+Version: 0.1.0
+Summary: A full-stack async Python web framework inspired by Laravel
+Keywords: web,framework,async,asgi,laravel
+Author: Mark Railton
+Author-email: Mark Railton <mark.railton@outlook.ie>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Dist: uvicorn[standard]>=0.34
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Requires-Dist: aiosqlite>=0.21
+Requires-Dist: asyncpg>=0.30
+Requires-Dist: aiomysql>=0.2
+Requires-Dist: jinja2>=3.1
+Requires-Dist: typer>=0.15
+Requires-Dist: python-dotenv>=1.1
+Requires-Dist: itsdangerous>=2.2
+Requires-Dist: python-multipart>=0.0.20
+Requires-Dist: aiofiles>=24.1
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13.9
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic>=2.10
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/caprail/caprail
+Project-URL: Repository, https://github.com/caprail/caprail
+Project-URL: Documentation, https://caprail.dev
+Description-Content-Type: text/markdown
+

caprail-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "caprail"
+version = "0.1.0"
+description = "A full-stack async Python web framework inspired by Laravel"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Mark Railton", email = "mark.railton@outlook.ie" }
+]
+keywords = ["web", "framework", "async", "asgi", "laravel"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+requires-python = ">=3.14"
+dependencies = [
+    "uvicorn[standard]>=0.34",
+    "sqlalchemy[asyncio]>=2.0",
+    "aiosqlite>=0.21",
+    "asyncpg>=0.30",
+    "aiomysql>=0.2",
+    "jinja2>=3.1",
+    "typer>=0.15",
+    "python-dotenv>=1.1",
+    "itsdangerous>=2.2",
+    "python-multipart>=0.0.20",
+    "aiofiles>=24.1",
+    "click>=8.1",
+    "rich>=13.9",
+    "httpx>=0.28",
+    "pydantic>=2.10",
+]
+
+[project.scripts]
+caprail = "caprail.console.kernel:main"
+
+[project.urls]
+Homepage = "https://github.com/caprail/caprail"
+Repository = "https://github.com/caprail/caprail"
+Documentation = "https://caprail.dev"
+
+[build-system]
+requires = ["uv_build>=0.10.11,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "pytest-asyncio>=0.25",
+    "pytest-cov>=6.0",
+    "httpx>=0.28",
+]
+

caprail-0.1.0/src/caprail/__init__.py

@@ -0,0 +1,54 @@
+"""
+Caprail — the Laravel-inspired Python web framework.
+
+Quick start::
+
+    from caprail import Application
+    from caprail.http import Response
+    from caprail.routing import Router
+
+    app = Application()
+
+    @app.router.get("/")
+    async def home(request):
+        return Response("Hello, Caprail!")
+
+    application = app.make_asgi()
+"""
+from caprail.application import Application
+from caprail.http.request import Request
+from caprail.http.response import Response, StreamingResponse, FileResponse
+from caprail.http.middleware import Middleware, Pipeline
+from caprail.http.exceptions import HttpException
+from caprail.foundation.container import Container, BindingResolutionError
+from caprail.foundation.service_provider import ServiceProvider
+from caprail.routing.router import Router, Route
+from caprail.view.engine import ViewEngine
+from caprail.orm.model import Model, configure_database
+from caprail.orm.migrations import Migration, Schema, Blueprint
+from caprail.auth.auth_manager import Auth
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Application",
+    "Request",
+    "Response",
+    "StreamingResponse",
+    "FileResponse",
+    "Middleware",
+    "Pipeline",
+    "HttpException",
+    "Container",
+    "BindingResolutionError",
+    "ServiceProvider",
+    "Router",
+    "Route",
+    "ViewEngine",
+    "Model",
+    "configure_database",
+    "Migration",
+    "Schema",
+    "Blueprint",
+    "Auth",
+]

caprail-0.1.0/src/caprail/application.py

@@ -0,0 +1,206 @@
+"""
+Caprail Application — the heart of the framework.
+
+Bootstraps the IoC container, registers service providers,
+and serves as the ASGI entry point.
+"""
+from __future__ import annotations
+
+import inspect
+import os
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from caprail.foundation.container import Container
+from caprail.foundation.service_provider import ServiceProvider
+from caprail.http.request import Request
+from caprail.http.response import Response
+from caprail.routing.router import Router
+
+
+class Application(Container):
+    """
+    The Caprail application.
+
+    Extends the service container and manages the full request lifecycle.
+
+    Usage (in ``bootstrap/app.py``)::
+
+        from caprail import Application
+
+        app = Application(base_path=Path(__file__).parent.parent)
+        app.register_providers([AppServiceProvider, RouteServiceProvider])
+        application = app.make_asgi()
+    """
+
+    VERSION = "0.1.0"
+
+    def __init__(self, base_path: Path | str | None = None) -> None:
+        super().__init__()
+        self.base_path = Path(base_path) if base_path else Path.cwd()
+        self._providers: list[ServiceProvider] = []
+        self._booted = False
+        self._router = Router()
+        self._global_middleware: list[type] = []
+        self._env: dict[str, str] = {}
+
+        self.instance("app", self)
+        self.instance(Application, self)
+        self.instance("router", self._router)
+        self.instance(Router, self._router)
+
+        self._load_env()
+
+    # ------------------------------------------------------------------
+    # Paths
+    # ------------------------------------------------------------------
+
+    def path(self, *parts: str) -> Path:
+        return self.base_path.joinpath(*parts)
+
+    def app_path(self, *parts: str) -> Path:
+        return self.base_path / "app" / Path(*parts) if parts else self.base_path / "app"
+
+    def config_path(self, *parts: str) -> Path:
+        return self.base_path / "config" / Path(*parts) if parts else self.base_path / "config"
+
+    def database_path(self, *parts: str) -> Path:
+        return self.base_path / "database" / Path(*parts) if parts else self.base_path / "database"
+
+    def resources_path(self, *parts: str) -> Path:
+        return self.base_path / "resources" / Path(*parts) if parts else self.base_path / "resources"
+
+    def storage_path(self, *parts: str) -> Path:
+        return self.base_path / "storage" / Path(*parts) if parts else self.base_path / "storage"
+
+    def public_path(self, *parts: str) -> Path:
+        return self.base_path / "public" / Path(*parts) if parts else self.base_path / "public"
+
+    # ------------------------------------------------------------------
+    # Environment
+    # ------------------------------------------------------------------
+
+    def _load_env(self) -> None:
+        env_file = self.base_path / ".env"
+        if env_file.exists():
+            from dotenv import dotenv_values
+            self._env = dict(dotenv_values(str(env_file)))
+            os.environ.update({k: v for k, v in self._env.items() if v is not None})
+
+    def env(self, key: str, default: Any = None) -> Any:
+        return os.environ.get(key, self._env.get(key, default))
+
+    def is_production(self) -> bool:
+        return self.env("APP_ENV", "production") == "production"
+
+    def is_debug(self) -> bool:
+        return str(self.env("APP_DEBUG", "false")).lower() in ("true", "1", "yes")
+
+    # ------------------------------------------------------------------
+    # Providers
+    # ------------------------------------------------------------------
+
+    def register_providers(self, providers: list[type[ServiceProvider]]) -> None:
+        for cls in providers:
+            provider = cls(self)
+            provider.register()
+            self._providers.append(provider)
+
+    def boot(self) -> None:
+        if self._booted:
+            return
+        for provider in self._providers:
+            provider.boot()
+        self._booted = True
+
+    # ------------------------------------------------------------------
+    # Routing helpers
+    # ------------------------------------------------------------------
+
+    @property
+    def router(self) -> Router:
+        return self._router
+
+    def add_middleware(self, *middleware_classes: type) -> None:
+        self._global_middleware.extend(middleware_classes)
+
+    # ------------------------------------------------------------------
+    # ASGI interface
+    # ------------------------------------------------------------------
+
+    def make_asgi(self) -> Callable:
+        self.boot()
+        return self._asgi_handler
+
+    async def _asgi_handler(self, scope: dict, receive, send) -> None:
+        if scope["type"] == "lifespan":
+            await self._handle_lifespan(receive, send)
+            return
+        if scope["type"] != "http":
+            return
+        request = Request(scope, receive, send)
+        response = await self._dispatch(request)
+        if response._headers.pop("_back", None):
+            url = request.header("referer", "/")
+            response._headers["location"] = url
+        await response.send(send)
+
+    async def _dispatch(self, request: Request) -> Response:
+        from caprail.http.middleware import Pipeline
+
+        result = self._router.resolve(request.method, request.path)
+        if result is None:
+            return self._not_found(request)
+
+        route, params = result
+        request.route_params = params
+        request.route_name = route.name
+
+        route_mw_classes = [
+            self._router.middleware_aliases.get(name)
+            for name in route.middleware
+            if name in self._router.middleware_aliases
+        ]
+        all_classes = self._global_middleware + [c for c in route_mw_classes if c]
+        middleware_instances = self._resolve_middleware(all_classes)
+
+        async def call_handler(req: Request) -> Response:
+            return await self._call_handler(route.handler, req)
+
+        return await Pipeline(middleware_instances).send(request).then(call_handler)
+
+    def _resolve_middleware(self, classes: list[type]) -> list:
+        instances = []
+        for cls in classes:
+            try:
+                instances.append(self.make(cls))
+            except Exception:
+                instances.append(cls())
+        return instances
+
+    @staticmethod
+    async def _call_handler(handler: Callable, request: Request) -> Response:
+        result = await handler(request) if inspect.iscoroutinefunction(handler) else handler(request)
+        if isinstance(result, Response):
+            return result
+        if isinstance(result, str):
+            return Response(result)
+        if isinstance(result, dict):
+            return Response.json(result)
+        return Response(str(result) if result is not None else "")
+
+    @staticmethod
+    def _not_found(request: Request) -> Response:
+        if request.wants_json():
+            return Response.json({"message": "Not found."}, status=404)
+        return Response("<h1>404 — Not Found</h1>", status=404)
+
+    async def _handle_lifespan(self, receive, send) -> None:
+        while True:
+            message = await receive()
+            if message["type"] == "lifespan.startup":
+                await send({"type": "lifespan.startup.complete"})
+            elif message["type"] == "lifespan.shutdown":
+                await send({"type": "lifespan.shutdown.complete"})
+                return

caprail-0.1.0/src/caprail/auth/__init__.py

@@ -0,0 +1,3 @@
+from caprail.auth.auth_manager import Auth
+
+__all__ = ["Auth"]

caprail-0.1.0/src/caprail/auth/auth_manager.py

@@ -0,0 +1,106 @@
+"""
+Caprail Auth Manager.
+
+Session and token-based authentication manager.
+
+Usage::
+
+    # In a controller:
+    success = await Auth.attempt(request, email="user@example.com", password="secret")
+    user = Auth.user(request)
+    Auth.logout(request)
+    is_logged_in = Auth.check(request)
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from caprail.http.request import Request
+
+
+class Auth:
+    """Static authentication helper."""
+
+    _user_model: type | None = None
+    _password_field: str = "password"
+
+    @classmethod
+    def configure(cls, user_model: type, password_field: str = "password") -> None:
+        cls._user_model = user_model
+        cls._password_field = password_field
+
+    @classmethod
+    async def attempt(cls, request: "Request", **credentials) -> bool:
+        """
+        Attempt to authenticate with the given credentials.
+
+        Stores the user in the session on success.
+        """
+        if cls._user_model is None:
+            raise RuntimeError("Auth not configured. Call Auth.configure(UserModel).")
+
+        password = credentials.pop("password", None)
+        query = cls._user_model.query()
+        for field, value in credentials.items():
+            query = query.where(field, value)
+        user = await query.first()
+
+        if user is None:
+            return False
+
+        stored = getattr(user, cls._password_field, None)
+        if not stored or not cls._check_password(password or "", stored):
+            return False
+
+        request.session["_auth_id"] = getattr(user, user.primary_key)
+        request.user = user
+        return True
+
+    @classmethod
+    async def login(cls, request: "Request", user: Any) -> None:
+        """Log in the given user directly (no credential check)."""
+        request.session["_auth_id"] = getattr(user, user.primary_key)
+        request.user = user
+
+    @classmethod
+    def logout(cls, request: "Request") -> None:
+        request.session.pop("_auth_id", None)
+        request.user = None
+
+    @classmethod
+    def check(cls, request: "Request") -> bool:
+        return "_auth_id" in request.session or request.user is not None
+
+    @classmethod
+    def user(cls, request: "Request") -> Any | None:
+        return request.user
+
+    @classmethod
+    def id(cls, request: "Request") -> Any | None:
+        return request.session.get("_auth_id")
+
+    # ------------------------------------------------------------------
+    # Password hashing
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def hash_password(password: str) -> str:
+        import hashlib, os
+        salt = os.urandom(16).hex()
+        digest = hashlib.pbkdf2_hmac("sha256", password.encode(), salt.encode(), 260000).hex()
+        return f"pbkdf2:sha256:260000:{salt}:{digest}"
+
+    @staticmethod
+    def _check_password(plain: str, hashed: str) -> bool:
+        if hashed.startswith("pbkdf2:sha256:"):
+            parts = hashed.split(":")
+            _, _, iterations, salt, stored_digest = parts
+            digest = hashlib.pbkdf2_hmac(
+                "sha256", plain.encode(), salt.encode(), int(iterations)
+            ).hex()
+            return hmac.compare_digest(digest, stored_digest)
+        # Fallback plain text (dev only)
+        return plain == hashed

caprail-0.1.0/src/caprail/console/commands/__init__.py

@@ -0,0 +1,33 @@
+from caprail.console.commands import (
+    make_controller,
+    make_model,
+    make_migration,
+    make_middleware,
+    make_provider,
+    make_request,
+    migrate_cmd,
+    migrate_rollback,
+    migrate_fresh,
+    migrate_status,
+    serve_cmd,
+    route_list,
+    key_generate,
+    new_project,
+)
+
+__all__ = [
+    "make_controller",
+    "make_model",
+    "make_migration",
+    "make_middleware",
+    "make_provider",
+    "make_request",
+    "migrate_cmd",
+    "migrate_rollback",
+    "migrate_fresh",
+    "migrate_status",
+    "serve_cmd",
+    "route_list",
+    "key_generate",
+    "new_project",
+]

caprail-0.1.0/src/caprail/console/commands/key_generate.py

@@ -0,0 +1,31 @@
+"""caprail key:generate"""
+from __future__ import annotations
+import os
+import secrets
+from pathlib import Path
+import typer
+from rich.console import Console
+
+console = Console()
+
+def command(
+    show: bool = typer.Option(False, "--show", help="Print the key instead of writing to .env"),
+) -> None:
+    """Generate a new application key."""
+    key = "base64:" + secrets.token_urlsafe(32)
+    if show:
+        console.print(f"[cyan]{key}[/]")
+        return
+
+    env_file = Path.cwd() / ".env"
+    if env_file.exists():
+        content = env_file.read_text()
+        if "APP_KEY=" in content:
+            import re
+            content = re.sub(r"APP_KEY=.*", f"APP_KEY={key}", content)
+        else:
+            content += f"\nAPP_KEY={key}\n"
+        env_file.write_text(content)
+        console.print(f"[green]Application key set:[/] {key}")
+    else:
+        console.print(f"[yellow].env not found. Key:[/] {key}")

caprail-0.1.0/src/caprail/console/commands/make_controller.py

@@ -0,0 +1,60 @@
+"""caprail make controller <Name>"""
+from __future__ import annotations
+from pathlib import Path
+import typer
+from rich.console import Console
+
+console = Console()
+
+TEMPLATE = '''"""
+{name} controller.
+"""
+from __future__ import annotations
+
+from caprail.http.request import Request
+from caprail.http.response import Response
+
+
+class {name}:
+
+    async def index(self, request: Request) -> Response:
+        return Response.json({{"message": "Hello from {name}.index"}})
+
+    async def create(self, request: Request) -> Response:
+        return Response("Create form")
+
+    async def store(self, request: Request) -> Response:
+        data = await request.all()
+        return Response.json(data, status=201)
+
+    async def show(self, request: Request) -> Response:
+        return Response.json({{"id": request.route("id")}})
+
+    async def edit(self, request: Request) -> Response:
+        return Response("Edit form")
+
+    async def update(self, request: Request) -> Response:
+        data = await request.all()
+        return Response.json(data)
+
+    async def destroy(self, request: Request) -> Response:
+        return Response.no_content()
+'''
+
+RESOURCE_TEMPLATE = TEMPLATE  # same for now
+
+def command(
+    name: str = typer.Argument(..., help="Controller class name"),
+    resource: bool = typer.Option(False, "--resource", "-r", help="Generate a resource controller"),
+) -> None:
+    """Generate a new HTTP controller."""
+    if not name.endswith("Controller"):
+        name = name + "Controller"
+    dest = Path.cwd() / "app" / "Http" / "Controllers" / f"{name}.py"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    if dest.exists():
+        console.print(f"[yellow]Controller already exists:[/] {dest}")
+        raise typer.Exit(1)
+    tpl = RESOURCE_TEMPLATE if resource else TEMPLATE
+    dest.write_text(tpl.format(name=name))
+    console.print(f"[green]Controller created:[/] {dest}")

caprail-0.1.0/src/caprail/console/commands/make_middleware.py

@@ -0,0 +1,37 @@
+"""caprail make middleware <Name>"""
+from __future__ import annotations
+from pathlib import Path
+import typer
+from rich.console import Console
+
+console = Console()
+
+TEMPLATE = '''"""
+{name} middleware.
+"""
+from __future__ import annotations
+
+from caprail.http.middleware import Middleware, NextCallable
+from caprail.http.request import Request
+from caprail.http.response import Response
+
+
+class {name}(Middleware):
+
+    async def handle(self, request: Request, next: NextCallable) -> Response:
+        # Add your middleware logic here
+        response = await next(request)
+        return response
+'''
+
+def command(name: str = typer.Argument(..., help="Middleware class name")) -> None:
+    """Generate a new middleware class."""
+    if not name.endswith("Middleware"):
+        name += "Middleware"
+    dest = Path.cwd() / "app" / "Http" / "Middleware" / f"{name}.py"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    if dest.exists():
+        console.print(f"[yellow]Middleware already exists:[/] {dest}")
+        raise typer.Exit(1)
+    dest.write_text(TEMPLATE.format(name=name))
+    console.print(f"[green]Middleware created:[/] {dest}")

caprail-0.1.0/src/caprail/console/commands/make_migration.py

@@ -0,0 +1,51 @@
+"""caprail make migration <name>"""
+from __future__ import annotations
+from datetime import datetime
+from pathlib import Path
+import typer
+from rich.console import Console
+
+console = Console()
+
+TEMPLATE = '''"""
+{class_name} migration.
+"""
+from __future__ import annotations
+
+from caprail.orm.migrations import Migration, Schema
+
+
+class {class_name}(Migration):
+
+    async def up(self, schema: Schema) -> None:
+        await schema.create("{table}", lambda table: [
+            table.id(),
+            table.timestamps(),
+        ])
+
+    async def down(self, schema: Schema) -> None:
+        await schema.drop_if_exists("{table}")
+'''
+
+def _class_name(name: str) -> str:
+    return "".join(part.capitalize() for part in name.split("_"))
+
+def _table_from_name(name: str) -> str:
+    name = name.removeprefix("create_").removesuffix("_table")
+    return name
+
+def _create(name: str) -> None:
+    ts = datetime.utcnow().strftime("%Y_%m_%d_%H%M%S")
+    filename = f"{ts}_{name}.py"
+    dest = Path.cwd() / "database" / "migrations" / filename
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    cls = _class_name(name)
+    table = _table_from_name(name)
+    dest.write_text(TEMPLATE.format(class_name=cls, table=table))
+    console.print(f"[green]Migration created:[/] {dest}")
+
+def command(
+    name: str = typer.Argument(..., help="Migration name (snake_case)"),
+) -> None:
+    """Generate a new database migration."""
+    _create(name)