Skip to main content

pyboot-web

pyboot-web is the Starlette web plugin for PyBoot. It adds decorator-based HTTP controllers, route mappings, services, request middleware, centralized exception handlers, and .env configuration loading to a PyBoot application.

The plugin is intentionally small: PyBoot remains responsible for class discovery, dependency injection, bean creation, and lifecycle orchestration; this package translates annotated classes and methods into Starlette routes.

Documentation

  • Examples - runnable snippets for routing, services, middleware, exception advice, and configuration.
  • Production starter - a recommended project layout, bootstrap implementation, deployment checklist, and testing approach.
  • License - MIT license terms.

Features

Capability API
HTTP controller RestController
HTTP routes GetMapping, PostMapping, PutMapping, PatchMapping, DeleteMapping
Application services Service
PyBoot-managed components Component
Bean factories Configuration, Bean
Middleware MiddlewareBase, MiddlewareComponent, UseMiddleware
Exception advice RestControllerAdvice, ExceptionHandler
Environment configuration Value, ValuePlugin
PyBoot integration WebPlugin, registered as the web PyBoot plugin

The package supports Python 3.11 and newer and uses Starlette for routing and request/response types.

Installation

Install PyBoot and this plugin in the same environment:

python -m pip install pyboot-framework pyboot-web
python -m pip install python-dotenv uvicorn

For a source checkout, from the repository root:

python -m pip install -e pyboot
python -m pip install -e plugins/pyboot_web
python -m pip install python-dotenv uvicorn

The package metadata declares starlette. python-dotenv is required by the ValuePlugin implementation.

Verify that PyBoot can discover the plugin entry points:

python -c "from importlib.metadata import entry_points; print([e.name for e in entry_points(group='pyboot.plugins')])"

The output should include web. It may also include value and other installed plugins.

Minimal bootstrap contract

Create a Starlette application, pass it to PyBoot, bootstrap the package that contains the application classes, and expose the original Starlette object:

from starlette.applications import Starlette
from pyboot.core.application import PyBoot


app = Starlette(debug=False)
PyBoot(app_instance=app, debug=False).bootstrap(package="app")

Run it with an ASGI server:

python -m uvicorn main:app --host 127.0.0.1 --port 8000

PyBoot.bootstrap() returns None; it mutates the supplied Starlette application by registering routes. Do not assign the return value to app.

API reference

pyboot_web.rest_mapping

  • RestController(path: str) marks a class as an HTTP controller.
  • GetMapping(path), PostMapping(path), PutMapping(path), PatchMapping(path), and DeleteMapping(path) provide method-specific route decorators for methods declared inside a RestController class.

Route decorators are intended for controller methods, following the class-oriented style used by Spring Boot:

@RestController("/api")
class HealthController:
    @GetMapping("/health")
    async def health(self, request: Request) -> JSONResponse:
        ...

Supported methods are GET, POST, PUT, PATCH, and DELETE. A standalone function decorated as a route is not discovered by WebPlugin.

pyboot_web.service

  • Service() marks a class for web-plugin registration and IoC construction.

Use Service for web-layer services. Use PyBoot's built-in Component for general application dependencies that should be managed by the core IoC container:

from pyboot.core.builtins.component import Component


@Component()
class AuditService:
    ...

Component classes can be injected into Service classes and controllers when their constructor parameters have type annotations.

PyBoot built-in bean management

Component is the general-purpose PyBoot IoC decorator. For factory-created objects, use a configuration class with methods annotated by Bean:

from pyboot.core.builtins.configuration import Bean, Configuration


class Clock:
    ...


@Configuration()
class ApplicationConfiguration:
    @Bean()
    def clock(self) -> Clock:
        return Clock()

The @Bean method must have a return annotation. PyBoot registers that return type as a bean factory, resolves any annotated method dependencies, and creates the bean through the IoC container. Component, Configuration, and Bean are core PyBoot features, not web-specific decorators.

pyboot_web.middlewares

  • MiddlewareBase defines the callable middleware contract.
  • MiddlewareComponent() marks a middleware class for IoC registration.
  • UseMiddleware(middlewares) attaches middleware classes to a controller or route method.

Pass middleware classes, not instances. The plugin obtains instances from PyBoot's IoC container.

pyboot_web.exception_handler

  • RestControllerAdvice() marks an exception advice class.
  • ExceptionHandler(exception_type) maps an exception type to a handler method.

Handlers receive (request, exception) after self and should return a Starlette response. A matching base-class handler can handle subclasses. Duplicate registrations for the same exception type are rejected. Unhandled exceptions are re-raised.

pyboot_web.value

  • Value(key, default) returns an environment value or the supplied default.
  • MissingValueException is raised when both are None.
  • ValuePlugin loads a discovered .env file before class discovery.

Environment values are strings and should be converted explicitly at the configuration boundary. ValuePlugin uses override=True, so .env values can replace values already present in the process environment.

pyboot_web.plugin

  • WebPlugin registers web beans, resolves exception advice, wraps routes with middleware and exception handling, and adds routes to the supplied Starlette application.

Discovery and lifecycle

PyBoot loads installed pyboot.plugins entry points, imports the package passed to bootstrap(), and scans its submodules for classes defined there. The web plugin then:

  1. Registers Service, Component, MiddlewareComponent, RestControllerAdvice, and RestController classes with the IoC container.
  2. Lets PyBoot create registered beans.
  3. Registers exception advice handlers.
  4. Combines controller and route middleware.
  5. Adds annotated controller methods as Starlette routes.

Keep application classes inside the scanned package and keep module-level side effects small and deterministic. Directories intended as packages should contain __init__.py.

Compatibility and scope

  • This package targets Starlette and does not provide Flask or Django adapters.
  • It adds routes to a supplied Starlette application; it does not create one.
  • Services and middleware depend on PyBoot IoC registration and constructor resolution.
  • The package root does not re-export the decorators; import them from their defining modules.

License

This project is distributed under the MIT License. See LICENSE.

Metadata

Release files for pyboot-web 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyboot-web 0.1.0
File Size Uploaded Provenance Actions
pyboot_web-0.1.0.tar.gz 12.4 kB Without provenance Details for pyboot_web-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyboot-web 0.1.0
File Interpreter ABI Platform Actions
pyboot_web-0.1.0-py3-none-any.whl Python 3 none any Details for pyboot_web-0.1.0-py3-none-any.whl

Total release size: 24.7 kB

Release files / pyboot_web-0.1.0.tar.gz

Download URL pyboot_web-0.1.0.tar.gz
Size 12.4 kB
Tags Source
SHA-256 checksum
How to use checksums
ed123e02417072b8c1a3b9fcc55f4570c4d525b1dc173028dfa4f2fd7ae118f3
BLAKE2b-256 checksum
How to use checksums
e20e3aadf93b3e67e73650f66290aaa9eb6be2de2d5ba4fc2457845735cf070a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Release files / pyboot_web-0.1.0-py3-none-any.whl

Download URL pyboot_web-0.1.0-py3-none-any.whl
Size 12.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c1dab4fa96004ef9557d4afac458405492cb671ec9c401e9a90dc62145966c2c
BLAKE2b-256 checksum
How to use checksums
9bf0ab415b486bec0c20ee4708f728d51e16d118f253d0a34f99b3f59d001d4e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Security for pyboot-web 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page