Exceptions¶

This reference documents the custom exception classes provided by pico-fastapi. These exceptions signal failures during application startup, and they allow you to handle these conditions explicitly in your code.

Overview¶

• PicoFastAPIError is the common base class for all custom errors in pico-fastapi.
• NoControllersFoundError is raised when the controller discovery process completes without finding any controllers.

Catching the base class lets you handle all pico-fastapi-specific errors in one place.

Typical import:

from pico_fastapi.exceptions import (
    PicoFastAPIError,
    NoControllersFoundError,
)

PicoFastAPIError¶

Base class for all pico-fastapi exceptions.

• Use this to catch any pico-fastapi-specific error without matching a concrete subclass.
• When writing library or application code on top of pico-fastapi, prefer catching PicoFastAPIError instead of broad exceptions like Exception, to avoid masking unrelated errors.

Example:

try:
    bootstrap_app()
except PicoFastAPIError as exc:
    # Handle configuration or discovery errors uniformly
    logger.error(f"pico_fastapi startup failed: {exc}")
    raise

NoControllersFoundError¶

Raised when the system cannot find any controllers during discovery.

Exact message:

No controllers were registered. Ensure your controller modules are scanned.

Constructor signature: - NoControllersFoundError() (takes no arguments)

When raised: - By register_controllers() after scanning the container for controllers and finding none.

Example usage during discovery:

from pico_fastapi.exceptions import NoControllersFoundError

try:
    register_controllers(app, container)
except NoControllersFoundError:
    logger.warning("No controllers found; the API will expose no endpoints.")

Removed Exceptions¶

InvalidConfigurerError (removed in v0.2.2)¶

InvalidConfigurerError was removed in v0.2.2. Invalid configurers are now logged as a warning and silently discarded. See the Migration Guide for details.

Recommendations¶

• Catch PicoFastAPIError at application boundaries (e.g., startup) to handle all pico-fastapi-specific failures in a single place.
• Do not rely on the exact exception message in code paths; match on the exception class to make your code resilient to message changes.

Auto-generated API¶

try:
    app = container.get(FastAPI)
except PicoFastAPIError as exc:
    logger.error("pico-fastapi startup failed: %s", exc)
    raise

 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

class PicoFastAPIError(Exception):
    """Base exception for all pico-fastapi errors.

    Catch this at startup boundaries to handle any pico-fastapi failure
    without matching individual subclasses.

    Example:
        .. code-block:: python

            try:
                app = container.get(FastAPI)
            except PicoFastAPIError as exc:
                logger.error("pico-fastapi startup failed: %s", exc)
                raise
    """

try:
    register_controllers(app, container)
except NoControllersFoundError:
    logger.warning("No controllers found; API has no endpoints.")

25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

class NoControllersFoundError(PicoFastAPIError):
    """Raised when no ``@controller``-decorated classes are found at startup.

    This error is raised by ``register_controllers()`` when the pico-ioc
    container does not contain any classes marked with the ``@controller``
    decorator.

    Causes:
        - Controller modules were not included in ``init(modules=[...])``.
        - Controller classes are missing the ``@controller`` decorator.
        - Import errors prevented controller modules from loading.

    Example:
        .. code-block:: python

            try:
                register_controllers(app, container)
            except NoControllersFoundError:
                logger.warning("No controllers found; API has no endpoints.")
    """

    def __init__(self):
        super().__init__("No controllers were registered. Ensure your controller modules are scanned.")