yaafcli 2026.2.4.180929__py3-none-any.whl

yaaf/__init__.py

@@ -0,0 +1,23 @@
+"""yaaf package exports with lazy loading to avoid circular imports."""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+__all__ = ["App", "Request", "Response", "app"]
+
+
+def __getattr__(name: str) -> Any:
+    if name in {"App", "Request", "app"}:
+        app_module = importlib.import_module(f"{__name__}.app")
+        return getattr(app_module, name)
+    if name == "Response":
+        from .responses import Response
+
+        return Response
+    raise AttributeError(f"module {__name__} has no attribute {name}")
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

yaaf/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

yaaf/app.py

@@ -0,0 +1,109 @@
+"""Filesystem-routed ASGI app for yaaf."""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass
+from typing import Any
+
+from .di import DependencyResolver
+from .loader import discover_routes
+from .responses import Response, as_response
+from .types import ASGIScope, ASGIReceive, ASGISend, Params
+
+
+@dataclass
+class Request:
+    """Represents an HTTP request within the ASGI app."""
+    scope: ASGIScope
+    body: bytes
+    path_params: Params
+
+    @property
+    def method(self) -> str:
+        """Return the HTTP method."""
+        return self.scope.get("method", "").upper()
+
+    @property
+    def path(self) -> str:
+        """Return the request path."""
+        return self.scope.get("path", "")
+
+    @property
+    def headers(self) -> dict[str, str]:
+        """Return decoded request headers."""
+        raw = self.scope.get("headers", [])
+        return {k.decode(): v.decode() for k, v in raw}
+
+    def text(self) -> str:
+        """Return the request body as text."""
+        return self.body.decode()
+
+
+class App:
+    """Filesystem-routed ASGI interface."""
+
+    def __init__(self, consumers_dir: str = "consumers") -> None:
+        """Initialize the app by discovering filesystem routes."""
+        self._consumers_dir = consumers_dir
+        self._routes = None
+        self._registry = None
+        self._resolver = None
+
+    def _ensure_routes(self) -> None:
+        if self._routes is None or self._registry is None or self._resolver is None:
+            self._routes, self._registry = discover_routes(self._consumers_dir)
+            self._resolver = DependencyResolver(self._registry)
+
+    async def __call__(self, scope: ASGIScope, receive: ASGIReceive, send: ASGISend) -> None:
+        """ASGI entrypoint."""
+        self._ensure_routes()
+        if scope.get("type") != "http":
+            response = Response.text("Unsupported scope type", status=500)
+            await response.send(send)
+            return
+
+        method = scope.get("method", "").upper()
+        path = scope.get("path", "")
+        match = None
+        for route in self._routes or []:
+            if method not in route.handlers:
+                continue
+            result = route.pattern.match(path)
+            if result is None:
+                continue
+            match = (route, result.groups())
+            break
+
+        if match is None:
+            response = Response.text("Not Found", status=404)
+            await response.send(send)
+            return
+        route, groups = match
+
+        body = b""
+        more_body = True
+        while more_body:
+            message = await receive()
+            if message.get("type") != "http.request":
+                break
+            body += message.get("body", b"")
+            more_body = message.get("more_body", False)
+
+        path_params = dict(zip(route.param_names, groups))
+        request = Request(scope=scope, body=body, path_params=path_params)
+        handler = route.handlers[method]
+        context = {
+            "request": request,
+            "params": path_params,
+            "path_params": path_params,
+        }
+        result = self._resolver.call(handler, context)
+        if inspect.isawaitable(result):
+            result = await result
+
+        response = as_response(result)
+        await response.send(send)
+
+
+app = App()

yaaf/cli.py

@@ -0,0 +1,45 @@
+"""Command-line entrypoint for running the ASGI app."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import uvicorn
+
+from .gen_services import generate_services
+
+
+def main() -> None:
+    """CLI entrypoint for running a yaaf ASGI app."""
+    parser = argparse.ArgumentParser(prog="yaaf", description="Run a yaaf ASGI app")
+    subparsers = parser.add_subparsers(dest="command")
+    parser.set_defaults(command="serve")
+
+    serve_parser = subparsers.add_parser("serve", help="Run the ASGI server")
+    serve_parser.add_argument("--app", default="yaaf.app:app", help="ASGI app path, e.g. module:app")
+    serve_parser.add_argument("--host", default="127.0.0.1")
+    serve_parser.add_argument("--port", default=8000, type=int)
+    serve_parser.add_argument("--reload", action="store_true")
+    serve_parser.add_argument("--consumers-dir", default="consumers")
+    serve_parser.set_defaults(command="serve")
+
+    gen_parser = subparsers.add_parser("gen-services", help="Generate consumers/services.py")
+    gen_parser.add_argument("--consumers-dir", default="consumers")
+    gen_parser.add_argument("--output", default=None)
+    gen_parser.set_defaults(command="gen-services")
+
+    if len(sys.argv) > 1 and sys.argv[1] == "gen-services":
+        args = parser.parse_args()
+    else:
+        args = parser.parse_args(["serve", *sys.argv[1:]])
+
+    if args.command == "gen-services":
+        generate_services(consumers_dir=args.consumers_dir, output_path=args.output)
+        return
+
+    generate_services(consumers_dir=args.consumers_dir)
+    uvicorn.run(args.app, host=args.host, port=args.port, reload=args.reload)
+
+
+if __name__ == "__main__":
+    main()

yaaf/di.py

@@ -0,0 +1,65 @@
+"""Simple dependency injection for yaaf services and handlers."""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass
+from collections.abc import Mapping
+from typing import Any, Callable, TypeVar
+
+T = TypeVar("T")
+
+@dataclass
+class ServiceRegistry:
+    """Global registry for services, keyed by type and name variants."""
+    by_type: dict[type[Any], Any]
+    by_alias: dict[str, Any]
+
+    def register(self, instance: T, aliases: list[str]) -> T:
+        """Register a service instance by type and alias names."""
+        self.by_type[type(instance)] = instance
+        type_name = type(instance).__name__
+        if type_name:
+            self.by_alias[type_name] = instance
+        for alias in aliases:
+            self.by_alias[alias] = instance
+        return instance
+
+    def resolve(self, annotation: type | None) -> Any | None:
+        """Resolve a service by type annotation."""
+        if isinstance(annotation, str):
+            return self.by_alias.get(annotation)
+        if annotation and annotation in self.by_type:
+            return self.by_type[annotation]
+        if annotation is not None:
+            alias = getattr(annotation, "__name__", "")
+            if alias and alias in self.by_alias:
+                return self.by_alias[alias]
+        return None
+
+
+class DependencyResolver:
+    """Resolve function arguments from a registry and contextual values."""
+    def __init__(self, registry: ServiceRegistry) -> None:
+        """Create a resolver bound to a service registry."""
+        self.registry = registry
+
+    def call(self, func: Callable[..., Any], context: Mapping[str, Any]) -> Any:
+        """Call a function, injecting dependencies from context or registry."""
+        signature = inspect.signature(func)
+        kwargs: dict[str, Any] = {}
+        for name, param in signature.parameters.items():
+            if name in context:
+                kwargs[name] = context[name]
+                continue
+            annotation = None
+            if param.annotation is not inspect._empty:
+                annotation = param.annotation
+            resolved = self.registry.resolve(annotation)
+            if resolved is not None:
+                kwargs[name] = resolved
+                continue
+            if param.default is not inspect._empty:
+                continue
+            raise TypeError(f"Cannot resolve dependency '{name}' for {func}")
+        return func(**kwargs)

yaaf/gen_services.py

@@ -0,0 +1,80 @@
+"""Generate a consumers/services.py typing module from filesystem routes."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable, Protocol
+
+HEADER = """\
+\"\"\"Generated service type aliases for consumers.\n\nDo not edit by hand. Regenerate via `yaaf` CLI.\n\"\"\"\n\nfrom __future__ import annotations\n\nfrom typing import Any, Protocol, TYPE_CHECKING\n\n"""
+
+
+def _is_identifier(segment: str) -> bool:
+    return segment.isidentifier()
+
+
+def _camel_case(parts: Iterable[str]) -> str:
+    return "".join(part[:1].upper() + part[1:] for part in parts if part)
+
+
+def _strip_dynamic(segment: str) -> str:
+    if segment.startswith("[") and segment.endswith("]"):
+        return segment[1:-1]
+    return segment
+
+
+def _service_alias(route_parts: list[str]) -> str:
+    normalized = [_strip_dynamic(part) for part in route_parts]
+    safe_parts = [part for part in normalized if _is_identifier(part)]
+    base = _camel_case(safe_parts) or "Route"
+    return f"{base}Service"
+
+
+def generate_services(consumers_dir: str = "consumers", output_path: str | None = None) -> Path:
+    base = Path(consumers_dir)
+    out_path = Path(output_path) if output_path else base / "services.py"
+
+    if not base.exists():
+        out_path.write_text(HEADER + "\n__all__ = []\n")
+        return out_path
+
+    aliases: list[tuple[str, str]] = []
+    dynamic_aliases: list[str] = []
+    for root in base.rglob("_service.py"):
+        if "api" not in root.parts:
+            continue
+        api_index = root.parts.index("api")
+        route_parts = list(root.parts[api_index + 1 : -1])
+        if any(part.startswith("[") and part.endswith("]") for part in route_parts):
+            dynamic_aliases.append(_service_alias(route_parts))
+            continue
+        if not all(_is_identifier(part) for part in route_parts):
+            continue
+        module_path = ".".join([base.name, "api", *route_parts, "_service"])
+        alias = _service_alias(route_parts)
+        aliases.append((alias, module_path))
+
+    aliases.sort(key=lambda item: item[0].lower())
+
+    lines = [HEADER]
+    lines.append("if TYPE_CHECKING:\n")
+    if aliases:
+        for alias, module_path in aliases:
+            lines.append(f"    from {module_path} import Service as {alias}\n")
+    else:
+        lines.append("    pass\n")
+    lines.append("else:\n")
+    for alias, _ in aliases:
+        lines.append(f"    class {alias}:\n        ...\n")
+
+    for alias in dynamic_aliases:
+        lines.append(f"\nclass {alias}(Protocol):\n    ...\n")
+
+    exports = ", ".join([f"'{alias}'" for alias, _ in aliases] + [f"'{alias}'" for alias in dynamic_aliases])
+    lines.append(f"\n__all__ = [{exports}]\n")
+
+    if dynamic_aliases:
+        lines.append("\n# Dynamic routes use Protocol stubs (invalid import paths).\n")
+
+    out_path.write_text("".join(lines))
+    return out_path

yaaf/loader.py

@@ -0,0 +1,193 @@
+"""Filesystem route discovery and module loading."""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+from .di import DependencyResolver, ServiceRegistry
+from .types import Handler
+
+
+@dataclass
+class RouteTarget:
+    """A discovered filesystem route and its handlers/services."""
+    pattern: re.Pattern[str]
+    route_parts: list[str]
+    param_names: list[str]
+    handlers: dict[str, Handler]
+    services: ServiceRegistry
+    service: Any | None
+    static_count: int
+    segment_count: int
+
+
+def _load_module(path: Path, name_prefix: str) -> ModuleType:
+    """Load a Python module from an explicit file path."""
+    module_name = f"yaaf_{name_prefix}_{abs(hash(path))}"
+    spec = importlib.util.spec_from_file_location(module_name, path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Could not load module from {path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def _collect_services(module: ModuleType, resolver: DependencyResolver) -> Any | None:
+    """Create a service from a module, if it exposes one."""
+    if hasattr(module, "service"):
+        instance = getattr(module, "service")
+        if instance is not None:
+            if callable(instance):
+                return resolver.call(instance, {})
+            return instance
+    if hasattr(module, "get_service") and callable(module.get_service):
+        return resolver.call(module.get_service, {})
+    if hasattr(module, "Service"):
+        service_cls = module.Service
+        if callable(service_cls):
+            return resolver.call(service_cls, {})
+    return None
+
+
+def discover_routes(consumers_dir: str) -> tuple[list[RouteTarget], ServiceRegistry]:
+    """Discover route handlers and services rooted under a consumers directory."""
+    base = Path(consumers_dir)
+    if not base.exists():
+        return [], ServiceRegistry(by_type={}, by_alias={})
+
+    base_parent = str(base.parent)
+    if base_parent not in sys.path:
+        sys.path.insert(0, base_parent)
+
+    targets: list[tuple[Path, list[str], list[str], str, int, int]] = []
+    service_modules: dict[Path, ModuleType] = {}
+    server_modules: dict[Path, ModuleType] = {}
+    service_aliases: dict[Path, list[str]] = {}
+
+    for root, _dirs, files in os.walk(base):
+        if "_server.py" not in files or "_service.py" not in files:
+            continue
+
+        root_path = Path(root)
+        parts = root_path.parts
+        if "api" not in parts:
+            continue
+        api_index = parts.index("api")
+        route_parts = list(parts[api_index + 1 :])
+        pattern, param_names, static_count, segment_count = build_pattern(route_parts, prefix="api")
+        targets.append((root_path, route_parts, param_names, pattern, static_count, segment_count))
+
+        route_key = "_".join(route_parts)
+        aliases = [route_key, _service_alias(route_parts)]
+        if route_parts:
+            aliases.append(route_parts[-1])
+        service_aliases[root_path] = [alias for alias in aliases if alias]
+
+        service_modules[root_path] = _load_module(root_path / "_service.py", "service")
+        server_modules[root_path] = _load_module(root_path / "_server.py", "server")
+
+    registry = ServiceRegistry(by_type={}, by_alias={})
+    resolver = DependencyResolver(registry)
+
+    service_instances: dict[Path, Any] = {}
+    unresolved = list(service_modules.items())
+    while unresolved:
+        progress = False
+        remaining: list[tuple[Path, ModuleType]] = []
+        for path, module in unresolved:
+            try:
+                instance = _collect_services(module, resolver)
+            except TypeError:
+                instance = None
+            if instance is None:
+                remaining.append((path, module))
+                continue
+            service_instances[path] = instance
+            registry.register(instance, aliases=service_aliases.get(path, []))
+            progress = True
+        if not progress:
+            missing = [str(path) for path, _ in remaining]
+            raise RuntimeError(f"Unresolved service dependencies in: {', '.join(missing)}")
+        unresolved = remaining
+
+    routes: list[RouteTarget] = []
+    for root_path, route_parts, param_names, pattern, static_count, segment_count in targets:
+        server_module = server_modules[root_path]
+        handlers: dict[str, Handler] = {}
+        for method in ("GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"):
+            func = getattr(server_module, method.lower(), None)
+            if callable(func):
+                handlers[method] = func
+        compiled = re.compile(pattern)
+        service_instance = service_instances.get(root_path)
+        routes.append(
+            RouteTarget(
+                pattern=compiled,
+                route_parts=route_parts,
+                param_names=param_names,
+                handlers=handlers,
+        services=registry,
+        service=service_instance,
+        static_count=static_count,
+        segment_count=segment_count,
+    )
+        )
+
+    routes.sort(key=lambda route: (route.static_count, route.segment_count), reverse=True)
+
+    static_routes = [route for route in routes if not route.param_names]
+    dynamic_routes = [route for route in routes if route.param_names]
+    for dyn in dynamic_routes:
+        for stat in static_routes:
+            if dyn.segment_count != stat.segment_count:
+                continue
+            candidate = "/api/" + "/".join(stat.route_parts)
+            if dyn.pattern.match(candidate):
+                print(
+                    f"Warning: dynamic route /api/{'/'.join(dyn.route_parts)} matches "
+                    f"static route /api/{'/'.join(stat.route_parts)}"
+                )
+                break
+    return routes, registry
+
+
+def build_pattern(route_parts: list[str], prefix: str) -> tuple[str, list[str], int, int]:
+    """Build a regex pattern and metadata for a route path."""
+    if not route_parts:
+        return rf"^/{re.escape(prefix)}$", [], 0, 0
+
+    param_names: list[str] = []
+    pattern_parts: list[str] = []
+    static_count = 0
+    for part in route_parts:
+        if part.startswith("[") and part.endswith("]"):
+            name = part[1:-1]
+            if not name:
+                raise ValueError("Empty dynamic route segment")
+            param_names.append(name)
+            pattern_parts.append(r"([^/]+)")
+        else:
+            pattern_parts.append(re.escape(part))
+            static_count += 1
+
+    pattern = "^/" + re.escape(prefix) + "/" + "/".join(pattern_parts) + "$"
+    return pattern, param_names, static_count, len(route_parts)
+
+
+def _service_alias(route_parts: list[str]) -> str:
+    def strip_dynamic(segment: str) -> str:
+        if segment.startswith("[") and segment.endswith("]"):
+            return segment[1:-1]
+        return segment
+
+    parts = [strip_dynamic(part) for part in route_parts]
+    safe = [part for part in parts if part.isidentifier()]
+    base = "".join(part[:1].upper() + part[1:] for part in safe) or "Route"
+    return f"{base}Service"

yaaf/responses.py

@@ -0,0 +1,69 @@
+"""Response helpers for yaaf."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Iterable, Tuple
+
+from .types import ASGISend
+
+
+@dataclass
+class Response:
+    """A minimal HTTP response object for ASGI."""
+    body: bytes
+    status: int = 200
+    headers: list[tuple[bytes, bytes]] | None = None
+
+    @classmethod
+    def text(cls, content: str, status: int = 200, headers: Iterable[Tuple[str, str]] | None = None) -> "Response":
+        """Create a text/plain response."""
+        return cls._with_type(content.encode(), "text/plain; charset=utf-8", status, headers)
+
+    @classmethod
+    def json(cls, content: Any, status: int = 200, headers: Iterable[Tuple[str, str]] | None = None) -> "Response":
+        """Create an application/json response."""
+        payload = json.dumps(content, ensure_ascii=True).encode()
+        return cls._with_type(payload, "application/json", status, headers)
+
+    @classmethod
+    def _with_type(
+        cls,
+        body: bytes,
+        media_type: str,
+        status: int,
+        headers: Iterable[Tuple[str, str]] | None,
+    ) -> "Response":
+        """Create a response and attach content-type + length headers."""
+        base_headers = [("content-type", media_type)]
+        if headers:
+            base_headers.extend(headers)
+        encoded = [(k.encode(), v.encode()) for k, v in base_headers]
+        encoded.append((b"content-length", str(len(body)).encode()))
+        return cls(body=body, status=status, headers=encoded)
+
+    async def send(self, send: ASGISend) -> None:
+        """Send the response through an ASGI send callable."""
+        await send({"type": "http.response.start", "status": self.status, "headers": self.headers or []})
+        await send({"type": "http.response.body", "body": self.body})
+
+    def with_status(self, status: int) -> "Response":
+        """Return a new response with a different status code."""
+        return Response(body=self.body, status=status, headers=self.headers)
+
+
+def as_response(value: Any) -> Response:
+    """Normalize handler return values into a Response."""
+    if isinstance(value, Response):
+        return value
+    if isinstance(value, bytes):
+        return Response._with_type(value, "application/octet-stream", 200, None)
+    if isinstance(value, str):
+        return Response.text(value)
+    if isinstance(value, tuple) and len(value) == 2:
+        body, status = value
+        return as_response(body).with_status(int(status))
+    if isinstance(value, (dict, list)):
+        return Response.json(value)
+    return Response.text(str(value))

yaaf/types.py

@@ -0,0 +1,44 @@
+"""Shared type aliases and protocols for yaaf."""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Protocol, TYPE_CHECKING, TypeAlias, TypeVar
+
+if TYPE_CHECKING:
+    from .responses import Response
+    from .app import Request
+
+ASGIScope: TypeAlias = dict[str, Any]
+ASGIReceive: TypeAlias = Callable[[], Awaitable[dict[str, Any]]]
+ASGISend: TypeAlias = Callable[[dict[str, Any]], Awaitable[None]]
+
+Params: TypeAlias = dict[str, str]
+ResponseLike: TypeAlias = "Response | str | bytes | dict[str, Any] | list[Any] | tuple[Any, int]"
+Handler: TypeAlias = Callable[..., ResponseLike | Awaitable[ResponseLike]]
+
+
+class ServiceProtocol(Protocol):
+    """Marker protocol for services registered with yaaf."""
+
+
+ServiceT = TypeVar("ServiceT", bound=ServiceProtocol)
+
+
+class ServerHandler(Protocol):
+    """Preferred handler signature for type checking."""
+
+    def __call__(
+        self,
+        request: "Request",
+        params: Params,
+        path_params: Params,
+        service: Any | None,
+    ) -> ResponseLike | Awaitable[ResponseLike]:
+        ...
+
+
+class ServiceFactory(Protocol):
+    """Callable factory that builds a service with DI-injected args."""
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        ...

yaafcli-2026.2.4.180929.dist-info/METADATA

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: yaafcli
+Version: 2026.2.4.180929
+Summary: Minimal ASGI app scaffold
+License: MIT License
+        
+        Copyright (c) 2026
+        
+        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.
+        
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: uvicorn>=0.23
+Provides-Extra: test
+Requires-Dist: pytest>=7.4; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Dynamic: license-file
+
+# yaaf
+
+YAAF stands for "Yet Another ASGI Framework".
+
+A minimal Python ASGI app scaffold that discovers routes from the filesystem. It includes a tiny router and a CLI wrapper around `uvicorn`.
+
+## Design Goals and Opinions
+
+- **Filesystem-first routing.** Routes are inferred from the directory structure under `consumers/**/api` rather than declared with decorators. This keeps routing discoverable by looking at the tree.
+- **Explicit endpoint files.** Each route has `_server.py` and `_service.py` to separate request handling from domain logic.
+- **Dependency injection without wiring.** Services are registered automatically and injected by name/type, so handlers and services focus on behavior, not setup.
+- **Static-first routing precedence.** Static routes always win over dynamic segments, with warnings when a dynamic route would overlap a static route.
+- **Minimal core.** The framework is intentionally small and opinionated, leaving room for you to add auth, middleware, validation, etc.
+
+## Quickstart
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+
+# Run the built-in example routes
+yaaf --reload
+```
+
+Example routes:
+
+- `GET /api/hello`
+- `GET /api/<name>` (dynamic segment)
+
+## Routing Model
+
+Routes are inferred from the directory structure under any `consumers/**/api` directory.
+
+- Every route directory must contain `_server.py` and `_service.py`.
+- The route path is `/api/...` plus the sub-path after `api/`.
+- Dynamic segments use `[param]` directory names and are exposed as `params`/`path_params`.
+
+Example layout:
+
+```text
+consumers/
+  api/
+    users/
+      _server.py
+      _service.py
+    hello/
+      _server.py
+      _service.py
+    [name]/
+      _server.py
+      _service.py
+```
+
+## Handlers and Services
+
+In `_server.py`, export functions named after HTTP methods (lowercase): `get`, `post`, etc. The function signature is resolved via dependency injection:
+
+- `request` gives you the `yaaf.Request` object.
+- `params` or `path_params` provides dynamic route parameters.
+- Services are injected by type annotations.
+
+Example `_server.py`:
+
+```python
+from consumers.services import HelloService
+from yaaf import Request
+from yaaf.types import Params
+
+
+async def get(request: Request, service: HelloService, params: Params):
+    return {"message": service.message(), "path": request.path, "params": params}
+```
+
+In `_service.py`, expose a module-level `service` instance (or a callable like `Service` or `get_service`). Services are registered and can be injected into other services or handlers:
+
+```python
+from consumers.services import UsersService
+
+
+class Service:
+    def __init__(self, users: UsersService) -> None:
+        self._users = users
+
+    def message(self) -> str:
+        user = self._users.get_user("1")
+        return f"Hello from yaaf, {user['name']}"
+
+service = Service
+```
+
+## Service-to-Service Injection
+
+Services can depend on other services via type annotations. Example layout:
+
+```text
+consumers/
+  api/
+    users/
+      _service.py
+      _server.py
+    hello/
+      _service.py
+      _server.py
+```
+
+`consumers/api/users/_service.py`
+```python
+class Service:
+    def get_user(self, user_id: str) -> dict:
+        return {"id": user_id, "name": "Austin"}
+
+service = Service()
+```
+
+`consumers/api/hello/_service.py`
+```python
+from yaaf.services import UsersService
+
+
+class Service:
+    def __init__(self, users: UsersService) -> None:
+        self._users = users
+
+    def message(self) -> str:
+        user = self._users.get_user("1")
+        return f"Hello from yaaf, {user['name']}"
+
+service = Service
+```
+
+`consumers/api/hello/_server.py`
+```python
+from consumers.services import HelloService
+from yaaf import Request
+
+
+async def get(request: Request, service: HelloService):
+    return {"message": service.message(), "path": request.path}
+```
+
+## Running Another App
+
+```bash
+yaaf --app your_package.app:app
+```
+
+## Versioning
+
+This project uses calendar-based versions with a timestamp (UTC). To bump the version:
+
+```bash
+python scripts/bump_version.py
+```
+
+## Service Type Generation
+
+Every `yaaf` command regenerates `consumers/services.py` for type-checking. You can also run it explicitly:
+
+```bash
+yaaf gen-services
+```
+
+Dynamic route segments like `[name]` get Protocol stubs in the generated file since they are not valid import paths.

yaafcli-2026.2.4.180929.dist-info/RECORD

@@ -0,0 +1,16 @@
+yaaf/__init__.py,sha256=mH1F6chTA4kRIaYK-yA1E7pBMOyReKi3rbrMiqKTxUY,602
+yaaf/__main__.py,sha256=MSmt_5Xg84uHqzTN38JwgseJK8rsJn_11A8WD99VtEo,61
+yaaf/app.py,sha256=7YrPl2_OZ-8NUy1RvUEBAbSntcqlP_in-2TLrKmGooE,3339
+yaaf/cli.py,sha256=X8YmeozhWjNtbEiyg_wTK75f_d-5LPKYkQmkU6v8dm0,1672
+yaaf/di.py,sha256=ZrGNBswJT4a3shYLgqd6hhqWii1UmiVmZ93B-G2sHWE,2448
+yaaf/gen_services.py,sha256=Gov7IlSLMG5Oo8RoRGHCbxHSsb_qecoh7IBZPWZKEe8,2869
+yaaf/loader.py,sha256=OzN2J5xl_sWGyNEaPz2LcuSEGfRPWHAGAs7QoK2JUdY,7215
+yaaf/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+yaaf/responses.py,sha256=iXZ0vDYfGO-BEUBBsobCR4JfWLRx8zhwYD9taQ8Sat4,2616
+yaaf/types.py,sha256=BAD3Wkjqi4NKxNz2bT1xggPx0jU5Sz_hOvsHXmGszig,1262
+yaafcli-2026.2.4.180929.dist-info/licenses/LICENSE,sha256=ESYyLizI0WWtxMeS7rGVcX3ivMezm-HOd5WdeOh-9oU,1056
+yaafcli-2026.2.4.180929.dist-info/METADATA,sha256=weCYQZBxNrbDD9H7gKcP0nGkBW2F84DN3aIiwpQ43iQ,6248
+yaafcli-2026.2.4.180929.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+yaafcli-2026.2.4.180929.dist-info/entry_points.txt,sha256=dh9ijq3gnFIr46RFjPjGR48PHQMUxwHopj3b9JipCRQ,39
+yaafcli-2026.2.4.180929.dist-info/top_level.txt,sha256=6WqEmcTdZROTeK4-7HzkB5h9JMBgs51otonH6vnjcAc,5
+yaafcli-2026.2.4.180929.dist-info/RECORD,,

yaafcli-2026.2.4.180929.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

yaafcli-2026.2.4.180929.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+yaaf = yaaf.cli:main

yaafcli-2026.2.4.180929.dist-info/licenses/LICENSE

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

yaafcli-2026.2.4.180929.dist-info/top_level.txt

@@ -0,0 +1 @@
+yaaf