pz-cli 5.0.0__py3-none-any.whl

pz_foundation/routing/declarations.py

@@ -0,0 +1,843 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from itertools import product
+import inspect
+from typing import Any, Callable, get_type_hints
+
+from fastapi import APIRouter
+
+from .exports import IncludedUrls, create_lazy_mount_router
+from .loaders import DeclaredUrlSpec
+from .utils import _join_path_prefix
+
+
+RoutePathProjectionProvider = Callable[[Any], Iterable[Mapping[str, Any]]]
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeRouteBinding:
+    path: str | Callable[[Any], str]
+    handler_attr: str
+    methods: tuple[str, ...] = ("GET",)
+    response_class: object | None = None
+    name: str | None = None
+    include_in_schema: bool = True
+    enabled_when: str | None = None
+    enumerate_params: tuple[tuple[str, Any], ...] | dict[str, Any] = ()
+    path_projections: RoutePathProjectionProvider | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class DeclaredEndpointBinding:
+    path: str
+    endpoint: Callable[..., Any]
+    methods: tuple[str, ...] = ("GET",)
+    response_class: object | None = None
+    name: str | None = None
+    include_in_schema: bool = True
+
+
+@dataclass(frozen=True, slots=True)
+class LazyMountUrlBinding:
+    namespace: str
+    path: str
+    app_factory: Callable[[], Any]
+    name: str | None = None
+    dependencies: tuple[object, ...] = ()
+    replace_target: str = ""
+    route_hints: tuple[str, ...] = ()
+    conflict_policy: str = "fail"
+
+
+@dataclass(frozen=True, slots=True)
+class UrlPathPattern:
+    path: str
+    view: Callable[..., Any]
+    methods: tuple[str, ...] = ("GET",)
+    response_class: object | None = None
+    name: str | None = None
+    include_in_schema: bool = True
+    enabled_when: str | Callable[..., object] | None = None
+    dependencies: tuple[object, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class MountedUrlPattern:
+    path: str
+    app: Callable[[], Any]
+    namespace: str
+    name: str | None = None
+    dependencies: tuple[object, ...] = ()
+    replace_target: str = ""
+    route_hints: tuple[str, ...] = ()
+    conflict_policy: str = "fail"
+
+
+def path(
+    path_value: str,
+    view: Callable[..., Any] | IncludedUrls,
+    *,
+    methods: tuple[str, ...] = ("GET",),
+    response_class: object | None = None,
+    name: str | None = None,
+    include_in_schema: bool = True,
+    enabled_when: str | Callable[..., object] | None = None,
+    dependencies: tuple[object, ...] = (),
+) -> UrlPathPattern | IncludedUrls:
+    if isinstance(view, IncludedUrls):
+        normalized_path_value = str(path_value or "").strip()
+        if normalized_path_value == "/":
+            normalized_path_value = ""
+        if normalized_path_value:
+            return IncludedUrls(
+                module_name=view.module_name,
+                path_prefix=normalized_path_value,
+                namespace=view.namespace,
+            )
+        return view
+    if not callable(view):
+        raise RuntimeError("path(...) requires a callable view function; string handler names are no longer supported.")
+    return UrlPathPattern(
+        path=str(path_value),
+        view=view,
+        methods=tuple(methods or ("GET",)),
+        response_class=response_class,
+        name=name,
+        include_in_schema=bool(include_in_schema),
+        enabled_when=enabled_when if callable(enabled_when) else (str(enabled_when or "").strip() or None),
+        dependencies=tuple(dependencies or ()),
+    )
+
+
+def mount(
+    path_value: str,
+    *,
+    app: Callable[[], Any],
+    namespace: str,
+    name: str | None = None,
+    dependencies: tuple[object, ...] = (),
+    replace_target: str = "",
+    route_hints: tuple[str, ...] = (),
+    conflict_policy: str = "fail",
+) -> MountedUrlPattern:
+    return MountedUrlPattern(
+        path=str(path_value),
+        app=app,
+        namespace=str(namespace),
+        name=name,
+        dependencies=tuple(dependencies or ()),
+        replace_target=str(replace_target or ""),
+        route_hints=tuple(route_hints or ()),
+        conflict_policy=str(conflict_policy or "fail"),
+    )
+
+
+def create_runtime_route_bindings(
+    definitions: tuple[RuntimeRouteBinding | dict[str, Any], ...] | list[RuntimeRouteBinding | dict[str, Any]],
+) -> tuple[RuntimeRouteBinding, ...]:
+    bindings: list[RuntimeRouteBinding] = []
+    for item in definitions:
+        if isinstance(item, RuntimeRouteBinding):
+            bindings.append(item)
+            continue
+        bindings.append(RuntimeRouteBinding(**dict(item)))
+    return tuple(bindings)
+
+
+def create_lazy_mount_url_bindings(
+    definitions: tuple[LazyMountUrlBinding | dict[str, Any], ...] | list[LazyMountUrlBinding | dict[str, Any]],
+) -> tuple[LazyMountUrlBinding, ...]:
+    bindings: list[LazyMountUrlBinding] = []
+    for item in definitions:
+        if isinstance(item, LazyMountUrlBinding):
+            bindings.append(item)
+            continue
+        bindings.append(LazyMountUrlBinding(**dict(item)))
+    return tuple(bindings)
+
+
+def _resolve_binding_path(binding: RuntimeRouteBinding, runtime: Any) -> str:
+    if callable(binding.path):
+        path = binding.path(runtime)
+    else:
+        path = binding.path
+    return str(path)
+
+
+def _resolve_binding_endpoint(binding: RuntimeRouteBinding, runtime: Any) -> Any:
+    handlers = getattr(runtime, "handlers", None)
+    if handlers is None or not hasattr(handlers, binding.handler_attr):
+        raise RuntimeError(f"runtime.handlers must expose {binding.handler_attr!r}.")
+    return getattr(handlers, binding.handler_attr)
+
+
+def _parse_template_path_param(segment: str) -> tuple[str, str] | None:
+    if not segment.startswith("{") or not segment.endswith("}"):
+        return None
+    body = segment[1:-1].strip()
+    if not body:
+        return None
+    if ":" in body:
+        name, convertor = body.split(":", 1)
+    else:
+        name, convertor = body, ""
+    name = name.strip()
+    if not name:
+        return None
+    return name, convertor.strip()
+
+
+def _path_param_names(path_value: str) -> tuple[str, ...]:
+    names: list[str] = []
+    for segment in (item for item in str(path_value or "").strip("/").split("/") if item):
+        parsed = _parse_template_path_param(segment)
+        if parsed is not None:
+            names.append(parsed[0])
+    return tuple(names)
+
+
+def _iter_enumerate_param_specs(binding: RuntimeRouteBinding) -> tuple[tuple[str, Any], ...]:
+    raw = binding.enumerate_params
+    if isinstance(raw, dict):
+        return tuple((str(name), values) for name, values in raw.items())
+    return tuple((str(name), values) for name, values in tuple(raw or ()))
+
+
+def _resolve_enumerated_param_values(name: str, values: Any, runtime: Any) -> tuple[str, ...]:
+    raw_values = values(runtime) if callable(values) else values
+    if isinstance(raw_values, str):
+        raw_values = (raw_values,)
+    normalized: list[str] = []
+    seen: set[str] = set()
+    for item in tuple(raw_values or ()):
+        value = str(item or "").strip()
+        if not value or value in seen:
+            continue
+        if "/" in value or "{" in value or "}" in value:
+            raise RuntimeError(f"enumerated route param {name!r} contains an invalid path segment {value!r}.")
+        seen.add(value)
+        normalized.append(value)
+    if not normalized:
+        raise RuntimeError(f"enumerated route param {name!r} requires at least one value.")
+    return tuple(normalized)
+
+
+def _normalize_path_projection_path(path_value: Any, *, index: int) -> str:
+    path_text = str(path_value or "").strip()
+    if not path_text:
+        raise RuntimeError(f"runtime route path projection #{index} requires a non-empty path.")
+    if not path_text.startswith("/"):
+        raise RuntimeError(f"runtime route path projection #{index} path must start with '/': {path_text!r}.")
+    stripped = path_text.strip("/")
+    if not stripped:
+        return path_text
+    for segment in stripped.split("/"):
+        if not segment:
+            raise RuntimeError(
+                f"runtime route path projection #{index} contains an empty path segment: {path_text!r}."
+            )
+        parsed = _parse_template_path_param(segment)
+        if ("{" in segment or "}" in segment) and parsed is None:
+            raise RuntimeError(
+                f"runtime route path projection #{index} contains an invalid path parameter segment {segment!r}."
+            )
+    return path_text
+
+
+def _normalize_path_projection_constants(constants_value: Any, *, index: int) -> dict[str, Any]:
+    if not isinstance(constants_value, Mapping):
+        raise RuntimeError(f"runtime route path projection #{index} constants must be a mapping.")
+    constants: dict[str, Any] = {}
+    for raw_name, value in constants_value.items():
+        name = str(raw_name or "").strip()
+        if not name:
+            raise RuntimeError(f"runtime route path projection #{index} constants must declare non-empty names.")
+        if name in constants:
+            raise RuntimeError(f"runtime route path projection #{index} declares duplicate constant {name!r}.")
+        constants[name] = value
+    return constants
+
+
+def _iter_path_projection_specs(
+    *,
+    binding: RuntimeRouteBinding,
+    runtime: Any,
+    path_value: str,
+) -> tuple[tuple[str, dict[str, Any]], ...]:
+    provider = binding.path_projections
+    if provider is None:
+        return ((str(path_value), {}),)
+    if not callable(provider):
+        raise RuntimeError("RuntimeRouteBinding.path_projections must be callable.")
+
+    raw_projections = provider(runtime)
+    if raw_projections is None:
+        raw_items: tuple[Any, ...] = ()
+    elif isinstance(raw_projections, Mapping):
+        raise RuntimeError("RuntimeRouteBinding.path_projections must return an iterable of projection mappings.")
+    else:
+        try:
+            raw_items = tuple(raw_projections)
+        except TypeError as exc:
+            raise RuntimeError(
+                "RuntimeRouteBinding.path_projections must return an iterable of projection mappings."
+            ) from exc
+
+    projections: list[tuple[str, dict[str, Any]]] = []
+    for index, projection in enumerate(raw_items, start=1):
+        if not isinstance(projection, Mapping):
+            raise RuntimeError(f"runtime route path projection #{index} must be a mapping.")
+        if "path" not in projection:
+            raise RuntimeError(f"runtime route path projection #{index} must declare a path.")
+        if "constants" not in projection:
+            raise RuntimeError(f"runtime route path projection #{index} must declare constants.")
+
+        projected_path = _normalize_path_projection_path(projection["path"], index=index)
+        constants = _normalize_path_projection_constants(projection["constants"], index=index)
+        path_constant_names = set(_path_param_names(projected_path)).intersection(constants)
+        if path_constant_names:
+            formatted_names = ", ".join(sorted(path_constant_names))
+            raise RuntimeError(
+                "runtime route path projection constants must not overlap dynamic path params: "
+                f"{formatted_names}."
+            )
+        projections.append((projected_path, constants))
+
+    if not projections:
+        raise RuntimeError("RuntimeRouteBinding.path_projections requires at least one projection.")
+    return tuple(projections)
+
+
+def _materialize_enumerated_path(path_value: str, constants: dict[str, str]) -> str:
+    path_text = str(path_value or "")
+    if path_text == "/":
+        return "/"
+    trailing_slash = path_text.endswith("/")
+    segments: list[str] = []
+    for segment in (item for item in path_text.strip("/").split("/") if item):
+        parsed = _parse_template_path_param(segment)
+        if parsed is not None and parsed[0] in constants:
+            segments.append(constants[parsed[0]])
+            continue
+        segments.append(segment)
+    materialized = "/" + "/".join(segments)
+    if trailing_slash and materialized != "/":
+        materialized += "/"
+    return materialized
+
+
+def _bind_enumerated_endpoint(endpoint: Any, constants: Mapping[str, Any]) -> Any:
+    if not constants:
+        return endpoint
+
+    async def _endpoint(**kwargs):
+        call_kwargs = dict(kwargs)
+        call_kwargs.update(constants)
+        result = endpoint(**call_kwargs)
+        if inspect.isawaitable(result):
+            return await result
+        return result
+
+    _endpoint.__name__ = str(getattr(endpoint, "__name__", "_runtime_route_endpoint") or "_runtime_route_endpoint")
+    _endpoint.__module__ = str(getattr(endpoint, "__module__", __name__) or __name__)
+    try:
+        signature = inspect.signature(endpoint)
+        try:
+            type_hints = get_type_hints(endpoint)
+        except Exception:
+            type_hints = {}
+        parameters = [
+            parameter.replace(annotation=type_hints.get(parameter.name, parameter.annotation))
+            for parameter in signature.parameters.values()
+            if parameter.name not in constants
+        ]
+        _endpoint.__signature__ = signature.replace(
+            parameters=parameters,
+            return_annotation=type_hints.get("return", signature.return_annotation),
+        )
+    except (TypeError, ValueError):
+        pass
+    return _endpoint
+
+
+def _iter_materialized_projected_runtime_bindings(
+    *,
+    path_value: str,
+    endpoint: Any,
+    binding: RuntimeRouteBinding,
+    runtime: Any,
+    projection_constants: Mapping[str, Any],
+) -> tuple[tuple[str, Any], ...]:
+    enum_specs = _iter_enumerate_param_specs(binding)
+    if not enum_specs:
+        return ((str(path_value), _bind_enumerated_endpoint(endpoint, projection_constants)),)
+
+    path_param_names = set(_path_param_names(path_value))
+    resolved_specs: list[tuple[str, tuple[str, ...]]] = []
+    for name, values in enum_specs:
+        if not name:
+            raise RuntimeError("enumerated route params must declare non-empty names.")
+        if name not in path_param_names:
+            raise RuntimeError(f"enumerated route param {name!r} is not present in route path {path_value!r}.")
+        resolved_specs.append((name, _resolve_enumerated_param_values(name, values, runtime)))
+
+    materialized: list[tuple[str, Any]] = []
+    names = tuple(name for name, _values in resolved_specs)
+    value_sets = tuple(values for _name, values in resolved_specs)
+    for values in product(*value_sets):
+        enumerated_constants = dict(zip(names, values, strict=True))
+        duplicated_names = set(projection_constants).intersection(enumerated_constants)
+        if duplicated_names:
+            formatted_names = ", ".join(sorted(duplicated_names))
+            raise RuntimeError(f"runtime route constants are declared more than once: {formatted_names}.")
+        constants = dict(projection_constants)
+        constants.update(enumerated_constants)
+        materialized.append(
+            (
+                _materialize_enumerated_path(path_value, enumerated_constants),
+                _bind_enumerated_endpoint(endpoint, constants),
+            )
+        )
+    return tuple(materialized)
+
+
+def _iter_materialized_runtime_bindings(
+    *,
+    path_value: str,
+    endpoint: Any,
+    binding: RuntimeRouteBinding,
+    runtime: Any,
+) -> tuple[tuple[str, Any], ...]:
+    materialized: list[tuple[str, Any]] = []
+    seen_paths: set[str] = set()
+    for projected_path, projection_constants in _iter_path_projection_specs(
+        binding=binding,
+        runtime=runtime,
+        path_value=path_value,
+    ):
+        for materialized_path, materialized_endpoint in _iter_materialized_projected_runtime_bindings(
+            path_value=projected_path,
+            endpoint=endpoint,
+            binding=binding,
+            runtime=runtime,
+            projection_constants=projection_constants,
+        ):
+            if materialized_path in seen_paths:
+                raise RuntimeError(f"runtime route path projection produced duplicate path {materialized_path!r}.")
+            seen_paths.add(materialized_path)
+            materialized.append((materialized_path, materialized_endpoint))
+    return tuple(materialized)
+
+
+def _resolve_pattern_path(pattern: UrlPathPattern, runtime: Any | None) -> str:
+    return str(pattern.path)
+
+
+def _resolve_pattern_endpoint(pattern: UrlPathPattern, runtime: Any | None) -> Any:
+    if runtime is not None:
+        handlers = getattr(runtime, "handlers", None)
+        handler_name = str(getattr(pattern.view, "__name__", "") or "").strip()
+        if handlers is not None and handler_name and hasattr(handlers, handler_name):
+            return getattr(handlers, handler_name)
+    return pattern.view
+
+
+def _resolve_enabled_when(enabled_when: str | Callable[..., object] | None, runtime: Any | None) -> bool:
+    if enabled_when is None:
+        return True
+    if callable(enabled_when):
+        try:
+            return bool(enabled_when(runtime))
+        except TypeError:
+            return bool(enabled_when())
+    return bool(getattr(runtime, enabled_when, False))
+
+
+def _binding_route_kwargs(
+    *,
+    methods: tuple[str, ...],
+    response_class: object | None,
+    name: str | None,
+    include_in_schema: bool,
+    dependencies: tuple[object, ...] = (),
+) -> dict[str, Any]:
+    kwargs: dict[str, Any] = {
+        "methods": list(methods),
+        "name": name,
+        "include_in_schema": include_in_schema,
+    }
+    if dependencies:
+        kwargs["dependencies"] = list(dependencies)
+    if response_class is not None:
+        kwargs["response_class"] = response_class
+    return kwargs
+
+
+def build_runtime_router(
+    *,
+    runtime_factory: Callable[[], Any | None],
+    bindings: tuple[RuntimeRouteBinding, ...],
+) -> APIRouter:
+    router = APIRouter()
+    runtime = runtime_factory()
+    if runtime is None:
+        return router
+    for binding in bindings:
+        if binding.enabled_when and not bool(getattr(runtime, binding.enabled_when, False)):
+            continue
+        path_value = _resolve_binding_path(binding, runtime)
+        endpoint = _resolve_binding_endpoint(binding, runtime)
+        for materialized_path, materialized_endpoint in _iter_materialized_runtime_bindings(
+            path_value=path_value,
+            endpoint=endpoint,
+            binding=binding,
+            runtime=runtime,
+        ):
+            router.add_api_route(
+                materialized_path,
+                materialized_endpoint,
+                **_binding_route_kwargs(
+                    methods=binding.methods,
+                    response_class=binding.response_class,
+                    name=binding.name,
+                    include_in_schema=binding.include_in_schema,
+                ),
+            )
+    return router
+
+
+def build_router_from_urlpatterns(
+    *,
+    urlpatterns: tuple[UrlPathPattern | IncludedUrls | MountedUrlPattern, ...],
+    runtime_factory: Callable[[], Any | None] | None = None,
+) -> APIRouter:
+    router = APIRouter()
+    runtime_required = any(
+        isinstance(item, UrlPathPattern) and isinstance(item.enabled_when, str)
+        for item in urlpatterns
+    )
+    runtime = None
+    if runtime_factory is not None:
+        runtime = runtime_factory()
+        if runtime is None:
+            return router
+    elif runtime_required:
+        raise RuntimeError("urlpatterns with conditional flags must declare runtime_factory.")
+    for item in urlpatterns:
+        if not isinstance(item, UrlPathPattern):
+            continue
+        if not _resolve_enabled_when(item.enabled_when, runtime):
+            continue
+        router.add_api_route(
+            _resolve_pattern_path(item, runtime),
+            _resolve_pattern_endpoint(item, runtime),
+            **_binding_route_kwargs(
+                methods=item.methods,
+                response_class=item.response_class,
+                name=item.name,
+                include_in_schema=item.include_in_schema,
+                dependencies=item.dependencies,
+            ),
+        )
+    return router
+
+
+def build_declared_router(
+    *,
+    bindings: tuple[DeclaredEndpointBinding, ...],
+) -> APIRouter:
+    router = APIRouter()
+    for binding in bindings:
+        router.add_api_route(
+            str(binding.path),
+            binding.endpoint,
+            **_binding_route_kwargs(
+                methods=binding.methods,
+                response_class=binding.response_class,
+                name=binding.name,
+                include_in_schema=binding.include_in_schema,
+            ),
+        )
+    return router
+
+
+def create_declared_router_url_spec(
+    *,
+    namespace: str,
+    bindings: tuple[DeclaredEndpointBinding, ...],
+    path_prefix: str = "",
+    dependencies: tuple[object, ...] = (),
+    replace_target: str = "",
+    route_hints: tuple[str, ...] = (),
+    conflict_policy: str = "fail",
+) -> DeclaredUrlSpec:
+    return DeclaredUrlSpec(
+        router=build_declared_router(bindings=bindings),
+        path_prefix=path_prefix,
+        namespace=namespace,
+        dependencies=dependencies,
+        replace_target=replace_target,
+        route_hints=route_hints,
+        conflict_policy=conflict_policy,
+    )
+
+
+def create_runtime_router_url_spec(
+    *,
+    namespace: str,
+    runtime_factory: Callable[[], Any | None],
+    bindings: tuple[RuntimeRouteBinding, ...],
+    path_prefix: str = "",
+    dependencies: tuple[object, ...] = (),
+    replace_target: str = "",
+    route_hints: tuple[str, ...] = (),
+    conflict_policy: str = "fail",
+) -> DeclaredUrlSpec:
+    return DeclaredUrlSpec(
+        router=build_runtime_router(
+            runtime_factory=runtime_factory,
+            bindings=bindings,
+        ),
+        path_prefix=path_prefix,
+        namespace=namespace,
+        dependencies=dependencies,
+        replace_target=replace_target,
+        route_hints=route_hints,
+        conflict_policy=conflict_policy,
+    )
+
+
+def build_runtime_router_from_spec(
+    *,
+    runtime_factory: Callable[[], Any | None],
+    bindings: tuple[RuntimeRouteBinding, ...],
+) -> APIRouter:
+    return build_runtime_router(
+        runtime_factory=runtime_factory,
+        bindings=bindings,
+    )
+
+
+def create_lazy_mount_url_spec(
+    *,
+    namespace: str,
+    path: str,
+    app_factory: Callable[[], Any],
+    name: str | None = None,
+    dependencies: tuple[object, ...] = (),
+    replace_target: str = "",
+    route_hints: tuple[str, ...] = (),
+    conflict_policy: str = "fail",
+) -> DeclaredUrlSpec:
+    return DeclaredUrlSpec(
+        router=create_lazy_mount_router(
+            path_prefix=path,
+            app_factory=app_factory,
+            name=name,
+        ),
+        namespace=namespace,
+        dependencies=dependencies,
+        replace_target=replace_target,
+        route_hints=route_hints,
+        conflict_policy=conflict_policy,
+    )
+
+
+def create_lazy_mount_url_specs(
+    bindings: tuple[LazyMountUrlBinding, ...] | list[LazyMountUrlBinding],
+) -> tuple[DeclaredUrlSpec, ...]:
+    return tuple(
+        create_lazy_mount_url_spec(
+            namespace=binding.namespace,
+            path=binding.path,
+            app_factory=binding.app_factory,
+            name=binding.name,
+            dependencies=tuple(binding.dependencies),
+            replace_target=binding.replace_target,
+            route_hints=tuple(binding.route_hints),
+            conflict_policy=binding.conflict_policy,
+        )
+        for binding in bindings
+    )
+
+
+def _clone_declared_url_spec_with_prefix(
+    spec: DeclaredUrlSpec,
+    *,
+    path_prefix: str = "",
+    namespace_prefix: str = "",
+) -> DeclaredUrlSpec:
+    return DeclaredUrlSpec(
+        router=spec.router,
+        path_prefix=_join_path_prefix(path_prefix, spec.path_prefix),
+        namespace=f"{namespace_prefix}.{spec.namespace}" if namespace_prefix else spec.namespace,
+        dependencies=tuple(spec.dependencies),
+        replace_target=spec.replace_target,
+        route_hints=tuple(spec.route_hints),
+        conflict_policy=spec.conflict_policy,
+    )
+
+
+def _coerce_declared_url_spec(item: object) -> DeclaredUrlSpec | None:
+    if isinstance(item, DeclaredUrlSpec):
+        return item
+    router = getattr(item, "router", None)
+    if not isinstance(router, APIRouter):
+        return None
+    if not hasattr(item, "namespace"):
+        return None
+    return DeclaredUrlSpec(
+        router=router,
+        path_prefix=getattr(item, "path_prefix", ""),
+        namespace=getattr(item, "namespace", ""),
+        dependencies=tuple(getattr(item, "dependencies", ()) or ()),
+        replace_target=getattr(item, "replace_target", ""),
+        route_hints=tuple(getattr(item, "route_hints", ()) or ()),
+        conflict_policy=getattr(item, "conflict_policy", "fail"),
+    )
+
+
+def _coerce_url_path_pattern(item: object) -> UrlPathPattern | None:
+    if isinstance(item, UrlPathPattern):
+        return item
+    if not hasattr(item, "view") or not hasattr(item, "path"):
+        return None
+    return UrlPathPattern(
+        path=getattr(item, "path"),
+        view=getattr(item, "view"),
+        methods=tuple(getattr(item, "methods", ("GET",)) or ("GET",)),
+        response_class=getattr(item, "response_class", None),
+        name=getattr(item, "name", None),
+        include_in_schema=bool(getattr(item, "include_in_schema", True)),
+        enabled_when=getattr(item, "enabled_when", None),
+        dependencies=tuple(getattr(item, "dependencies", ()) or ()),
+    )
+
+
+def _coerce_mounted_url_pattern(item: object) -> MountedUrlPattern | None:
+    if isinstance(item, MountedUrlPattern):
+        return item
+    if not hasattr(item, "app") or not hasattr(item, "path") or not hasattr(item, "namespace"):
+        return None
+    return MountedUrlPattern(
+        path=getattr(item, "path"),
+        app=getattr(item, "app"),
+        namespace=getattr(item, "namespace"),
+        name=getattr(item, "name", None),
+        dependencies=tuple(getattr(item, "dependencies", ()) or ()),
+        replace_target=getattr(item, "replace_target", ""),
+        route_hints=tuple(getattr(item, "route_hints", ()) or ()),
+        conflict_policy=getattr(item, "conflict_policy", "fail"),
+    )
+
+
+def _coerce_included_urls(item: object) -> IncludedUrls | None:
+    if isinstance(item, IncludedUrls):
+        return item
+    if not hasattr(item, "module_name"):
+        return None
+    return IncludedUrls(
+        module_name=getattr(item, "module_name"),
+        path_prefix=getattr(item, "path_prefix", ""),
+        namespace=getattr(item, "namespace", ""),
+    )
+
+
+def compile_urlpatterns(
+    *,
+    urlpatterns: tuple[DeclaredUrlSpec | UrlPathPattern | MountedUrlPattern | IncludedUrls, ...]
+    | list[DeclaredUrlSpec | UrlPathPattern | MountedUrlPattern | IncludedUrls],
+    app_name: str = "",
+    runtime_factory: Callable[[], Any | None] | None = None,
+    route_hints: tuple[str, ...] = (),
+) -> tuple[DeclaredUrlSpec, ...]:
+    specs: list[DeclaredUrlSpec] = []
+    pending_path_patterns: list[UrlPathPattern] = []
+
+    def _flush_path_patterns() -> None:
+        nonlocal pending_path_patterns
+        if not pending_path_patterns:
+            return
+        if not str(app_name or "").strip():
+            raise RuntimeError("urlpatterns with path(...) entries must declare app_name.")
+        specs.append(
+            DeclaredUrlSpec(
+                router=build_router_from_urlpatterns(
+                    urlpatterns=tuple(pending_path_patterns),
+                    runtime_factory=runtime_factory,
+                ),
+                namespace=str(app_name),
+                route_hints=tuple(route_hints or ()),
+            ),
+        )
+        pending_path_patterns = []
+
+    for item in urlpatterns:
+        declared_spec = _coerce_declared_url_spec(item)
+        if declared_spec is not None:
+            _flush_path_patterns()
+            specs.append(declared_spec)
+            continue
+        url_path_pattern = _coerce_url_path_pattern(item)
+        if url_path_pattern is not None:
+            pending_path_patterns.append(url_path_pattern)
+            continue
+        mounted_url_pattern = _coerce_mounted_url_pattern(item)
+        if mounted_url_pattern is not None:
+            _flush_path_patterns()
+            specs.append(
+                create_lazy_mount_url_spec(
+                    namespace=mounted_url_pattern.namespace,
+                    path=mounted_url_pattern.path,
+                    app_factory=mounted_url_pattern.app,
+                    name=mounted_url_pattern.name,
+                    dependencies=tuple(mounted_url_pattern.dependencies),
+                    replace_target=mounted_url_pattern.replace_target,
+                    route_hints=tuple(mounted_url_pattern.route_hints),
+                    conflict_policy=mounted_url_pattern.conflict_policy,
+                )
+            )
+            continue
+        included_urls = _coerce_included_urls(item)
+        if included_urls is not None:
+            _flush_path_patterns()
+            from .loaders import load_url_module_specs
+
+            for spec in load_url_module_specs(included_urls.module_name):
+                specs.append(
+                    _clone_declared_url_spec_with_prefix(
+                        spec,
+                        path_prefix=included_urls.path_prefix,
+                        namespace_prefix=included_urls.namespace,
+                    )
+                )
+            continue
+        raise RuntimeError(
+            "urlpatterns must contain only path(...), mount(...), include(...), or DeclaredUrlSpec entries."
+        )
+    _flush_path_patterns()
+    return tuple(specs)
+
+
+__all__ = [
+    "DeclaredEndpointBinding",
+    "MountedUrlPattern",
+    "LazyMountUrlBinding",
+    "build_declared_router",
+    "build_router_from_urlpatterns",
+    "create_lazy_mount_url_bindings",
+    "create_declared_router_url_spec",
+    "compile_urlpatterns",
+    "mount",
+    "path",
+    "RuntimeRouteBinding",
+    "build_runtime_router",
+    "build_runtime_router_from_spec",
+    "create_runtime_route_bindings",
+    "create_lazy_mount_url_spec",
+    "create_lazy_mount_url_specs",
+    "create_runtime_router_url_spec",
+    "UrlPathPattern",
+]