API Reference¶

def controller(
    cls: Optional[Type[Any]] = None, *, scope: str = "request", **kwargs: Any
) -> Callable[[Type[Any]], Type[Any]] | Type[Any]:
    """Mark a class as a pico-fastapi controller with DI and auto-routing.

    The decorated class is registered as a pico-ioc ``@component`` and its
    methods decorated with ``@get``, ``@post``, etc. are automatically
    registered as FastAPI routes at startup.

    Can be used with or without arguments::

        @controller
        class A: ...

        @controller(prefix="/api", tags=["Items"], scope="request")
        class B: ...

    Args:
        cls: The class being decorated (passed implicitly when used without
            parentheses).
        scope: pico-ioc scope for the controller instance.  Typical values
            are ``"request"`` (default) and ``"websocket"``.
        **kwargs: Additional metadata forwarded to the ``APIRouter``
            constructor.  Common keys: ``prefix``, ``tags``,
            ``dependencies``, ``responses``.

    Returns:
        The decorated class (registered as a pico-ioc component), or a
        decorator function if called with arguments.

    Example:
        .. code-block:: python

            @controller(prefix="/users", tags=["Users"])
            class UserController:
                def __init__(self, service: UserService):
                    self.service = service

                @get("/")
                async def list_users(self):
                    return self.service.list_all()
    """

    def decorate(c: Type[Any]) -> Type[Any]:
        setattr(c, PICO_CONTROLLER_META, kwargs)
        setattr(c, IS_CONTROLLER_ATTR, True)
        return component(c, scope=scope)

    return decorate if cls is None else decorate(cls)

def delete(path: str, **kwargs: Any) -> Callable[[Callable[P, R]], Callable[P, R]]:
    """Define a DELETE endpoint on a controller method.

    Args:
        path: URL path for the route.
        **kwargs: Additional FastAPI route parameters.

    Returns:
        A decorator that attaches DELETE route metadata to the method.

    Example:
        .. code-block:: python

            @delete("/items/{id}", status_code=204)
            async def delete_item(self, id: int):
                pass
    """
    return _create_route_decorator("DELETE", path, **kwargs)

def get(path: str, **kwargs: Any) -> Callable[[Callable[P, R]], Callable[P, R]]:
    """Define a GET endpoint on a controller method.

    Args:
        path: URL path for the route (e.g. ``"/"``, ``"/{id}"``).
        **kwargs: Additional FastAPI route parameters such as
            ``response_model``, ``status_code``, ``tags``, ``summary``.

    Returns:
        A decorator that attaches GET route metadata to the method.

    Example:
        .. code-block:: python

            @get("/items", response_model=list[Item])
            async def list_items(self):
                return self.service.get_all()
    """
    return _create_route_decorator("GET", path, **kwargs)

def patch(path: str, **kwargs: Any) -> Callable[[Callable[P, R]], Callable[P, R]]:
    """Define a PATCH endpoint on a controller method.

    Args:
        path: URL path for the route.
        **kwargs: Additional FastAPI route parameters.

    Returns:
        A decorator that attaches PATCH route metadata to the method.

    Example:
        .. code-block:: python

            @patch("/items/{id}")
            async def patch_item(self, id: int, data: ItemPatch):
                return self.service.patch(id, data)
    """
    return _create_route_decorator("PATCH", path, **kwargs)

def post(path: str, **kwargs: Any) -> Callable[[Callable[P, R]], Callable[P, R]]:
    """Define a POST endpoint on a controller method.

    Args:
        path: URL path for the route.
        **kwargs: Additional FastAPI route parameters such as
            ``response_model``, ``status_code``.

    Returns:
        A decorator that attaches POST route metadata to the method.

    Example:
        .. code-block:: python

            @post("/items", status_code=201)
            async def create_item(self, data: ItemCreate):
                return self.service.create(data)
    """
    return _create_route_decorator("POST", path, **kwargs)

def put(path: str, **kwargs: Any) -> Callable[[Callable[P, R]], Callable[P, R]]:
    """Define a PUT endpoint on a controller method.

    Args:
        path: URL path for the route.
        **kwargs: Additional FastAPI route parameters.

    Returns:
        A decorator that attaches PUT route metadata to the method.

    Example:
        .. code-block:: python

            @put("/items/{id}")
            async def update_item(self, id: int, data: ItemUpdate):
                return self.service.update(id, data)
    """
    return _create_route_decorator("PUT", path, **kwargs)

def websocket(path: str, **kwargs: Any) -> Callable[[Callable[P, R]], Callable[P, R]]:
    """Define a WebSocket endpoint on a controller method.

    The WebSocket parameter is detected by type annotation
    (``ws: WebSocket``), not by argument name.

    Args:
        path: WebSocket route path (e.g. ``"/ws/chat"``).
        **kwargs: Additional FastAPI WebSocket route parameters.

    Returns:
        A decorator that attaches WebSocket route metadata to the method.

    Example:
        .. code-block:: python

            from fastapi import WebSocket

            @controller(scope="websocket")
            class ChatController:
                @websocket("/ws/chat")
                async def chat(self, ws: WebSocket):
                    await ws.accept()
                    data = await ws.receive_text()
                    await ws.send_text(f"Echo: {data}")
    """
    return _create_route_decorator("WEBSOCKET", path, **kwargs)