birchrest package

Subpackages

Submodules

birchrest.core module

birchrest.version module

The package version

Module contents

This module serves as the main entry point for the BirchRest framework.

Modules imported include: - app: Contains the core BirchRest class to handle application setup. - decorators: Provides decorators like get, post, controller, and middleware helpers. - routes: Defines controllers for managing routes. - http: Handles HTTP requests, responses, and status codes. - types: Defines core types such as middleware functions and route handlers. - exceptions: Manages framework-specific errors and exceptions. - middlewares: Includes various middleware like RateLimiter, Logger, and Cors. - unittest: Includes the TestAdapter for unittesting.

class birchrest.BirchRest(log_level: str = 'debug', base_path: str = '')[source]

Bases: object

The core application class for the BirchRest framework, responsible for registering controllers, middleware, authentication, error handling, and starting the HTTP server to serve the API.

Attributes:

controllers (List[Controller]): Registered route controllers. global_middlewares (List[MiddlewareFunction]): Global middleware applied to all routes. auth_handler (Optional[AuthHandlerFunction]): Authentication handler for protected routes. error_handler (Optional[ErrorHandler]): Error handler function for handling exceptions.

auth(auth_handler: Callable[[Request, Response], Awaitable[Any]]) → None[source]

Sets the authentication handler for the application, used for protecting routes.

Args:

auth_handler (AuthHandlerFunction): A function to handle authentication logic.

error(handler: Callable[[Request, Response, Exception], Awaitable[None]]) → None[source]

Registers a global error handler for the application.

Args:

handler (ErrorHandler): A function to handle errors during request processing.

async handle_request(request: Request) → Response[source]

Handles incoming HTTP requests by matching them to routes, processing middleware, and handling exceptions asynchronously.

middleware(handler: Callable[[Request, Response, Callable[[], Awaitable[None]]], Awaitable[None]]) → None[source]

Registers a global middleware that is applied to all routes.

Args:

handler (MiddlewareFunction): A middleware function to process requests.

register(*controllers: Type[Controller]) → None[source]

Registers one or more route controllers to the application.

Args:

*controllers (Type[Controller]): One or more controller classes to register.

Raises:

InvalidControllerRegistration: If a registered controller does not inherit from Controller.

serve(host: str = '127.0.0.1', port: int = 13337) → None[source]

Starts the HTTP server to serve the API on the specified host and port.

Args:

host (str): The hostname or IP address to bind the server to. Defaults to “127.0.0.1”. port (int): The port number to listen on. Defaults to 13337.

class birchrest.Controller[source]

Bases: object

Base class for defining a collection of routes and subcontrollers for an HTTP API.

The Controller class allows organizing routes and middleware in a structured manner. It collects routes defined on its methods, handles subcontrollers, and resolves the base path for each route. Each method decorated with HTTP method decorators (like GET, POST, etc.) is treated as a route, and the controller can apply middleware or mark routes as protected.

Attributes:

_base_path (str): The base path that is prefixed to all routes in this controller. _middlewares (List[MiddlewareFunction]): The list of middleware applied to this controller. _is_protected (str): Indicates if routes in this controller require protection (e.g., authentication). routes (List[Route]): The list of routes collected from the controller’s methods. controllers (List[Controller]): The list of subcontrollers attached to this controller.

collect_routes() → Generator[Route, None, None][source]

Collect and yield all routes defined in this controller and its subcontrollers.

This method generates all routes defined in the controller, including those in any attached subcontrollers, recursively.

Yield:

The routes defined in this controller and its subcontrollers.

resolve_paths(prefix: str = '', middlewares: List[Callable[[Request, Response, Callable[[], Awaitable[None]]], Awaitable[None]]] = []) → None[source]

Resolve and apply the base paths and middleware to all routes in this controller.

This method resolves the complete path for each route in the controller by combining the provided prefix with the controller’s base path. It also ensures that any middleware applied to the controller is propagated to its routes. If the controller has subcontrollers, their routes are resolved recursively.

Parameters:

  • prefix – The URL path prefix to prepend to the controller’s base path.

  • middlewares – A list of middleware functions to apply to all routes in the controller.

class birchrest.Middleware[source]

Bases: ABC

Base class for all middlewares. All middlewares should inherit from this class. This class provides a unified interface to handle both synchronous and asynchronous middlewares.