pyboot-web 0.1.0__py3-none-any.whl

pyboot_web/ExceptionResolver.py

@@ -0,0 +1,33 @@
+from typing import Callable
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+#Exception Resolver
+class ExceptionResolver:
+    def __init__(self) -> None:
+        self.handlers: dict[
+            type[Exception], Callable[[Request, Exception], JSONResponse]
+        ] = dict()
+        return
+
+    def register(
+        self,
+        exception_type: type[Exception],
+        handler: Callable[[Request, Exception], JSONResponse],
+    ):
+        if exception_type in self.handlers:
+            raise TypeError(f"Handler already registered for {exception_type.__name__}")
+
+        self.handlers[exception_type] = handler
+        return
+
+    def resolve(self, request: Request, exception: Exception) -> JSONResponse:
+        for exception_class in type(exception).__mro__:
+            handler = self.handlers.get(exception_class)
+
+            if handler is not None:
+                return handler(request, exception)
+
+        raise exception
+

pyboot_web/WebAttr.py

@@ -0,0 +1,18 @@
+from enum import Enum
+
+class WebAttr(Enum):
+    IS_REST_CONTROLLER="__is_rest_controller__"
+    REST_CONTROLLER_PATH="__rest_controller_path__"
+
+    IS_ROUTE="__is_route__"
+    ROUTE_PATH="__route_path__"
+    ROUTE_METHOD="__route_method__"
+
+    IS_MIDDLEWARE_COMPONENT="__is_middleware_component__"
+    MIDDLEWARE_LIST="__middleware_list__"
+
+    IS_WEB_SERVICE="__is_web_service__"
+
+    IS_REST_CONTROLLER_ADVICE="__is_rest_controller_advice__"
+    IS_EXCEPTION_HANDLER_METHOD="__is_exception_handler__"
+    EXCEPTION_HANDLER_FOR="__exception_handler_for__"

pyboot_web/exception_handler.py

@@ -0,0 +1,25 @@
+from pyboot.core.types import ClassT
+
+from .WebAttr import WebAttr
+
+from .types import * 
+
+class RestControllerAdvice:
+    def __init__(self) -> None:
+        pass
+
+    def __call__(self,clazz:ClassT) -> ClassT:
+        setattr(clazz,WebAttr.IS_REST_CONTROLLER_ADVICE.value,True)
+        return clazz
+
+class ExceptionHandler:
+    def __init__(self,exception_type:type[Exception]) -> None:
+        self.exception_type:type[Exception]=exception_type
+        pass
+
+    def __call__(self,func:Callable[[Any,Request,E],JSONResponse]) -> Callable[[Any,Request,E],JSONResponse]:
+        setattr(func,WebAttr.IS_EXCEPTION_HANDLER_METHOD.value,True)
+        setattr(func,WebAttr.EXCEPTION_HANDLER_FOR.value,self.exception_type)
+
+        return func
+

pyboot_web/middlewares.py

@@ -0,0 +1,44 @@
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from typing import Callable,Awaitable,overload
+from abc import ABC,abstractmethod
+
+from .WebAttr import WebAttr
+
+from .rest_mapping import ControllerMethodT
+
+from pyboot.core.types  import ClassTBase,ClassT
+
+CallNext=Callable[[Request],JSONResponse |  Awaitable[JSONResponse]]
+
+class MiddlewareBase(ABC):
+    @abstractmethod
+    def __call__(self,request:Request,call_next:CallNext) -> JSONResponse|Awaitable[JSONResponse]:
+        pass
+
+class UseMiddleware:
+    def __init__(self,middlewares:list[type[MiddlewareBase]]) -> None:
+        self.middlewares:list[type[MiddlewareBase]]=middlewares
+        pass
+
+    @overload
+    def __call__(self,target:ClassTBase)->ClassTBase:
+        pass
+
+    @overload    
+    def __call__(self,target:ControllerMethodT)->ControllerMethodT:
+        pass
+
+    def __call__(self, target:ClassTBase|ControllerMethodT) -> ClassTBase|ControllerMethodT:
+        setattr(target,WebAttr.MIDDLEWARE_LIST.value,self.middlewares)
+        return target
+
+class MiddlewareComponent:
+    def __init__(self) -> None:
+        pass
+
+    def __call__(self,clazz:ClassT) -> ClassT:
+        setattr(clazz,WebAttr.IS_MIDDLEWARE_COMPONENT.value,True)
+        return clazz
+

pyboot_web/plugin.py

@@ -0,0 +1,305 @@
+from pyboot.core.pyboot_plugin import PyBootPlugin
+from pyboot.core.pyboot_context import PyBootContext
+
+from .rest_mapping import *
+from .ExceptionResolver import ExceptionResolver
+from .middlewares import MiddlewareBase
+
+import inspect
+from typing import Callable, cast
+
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+#WebPugin
+class WebPlugin(PyBootPlugin):
+
+    def __init__(self) -> None:
+        self.exception_resolver: ExceptionResolver = ExceptionResolver()
+        return
+
+    def _register_rest_controller_advice(self, context: PyBootContext):
+
+        for clazz in context.discovered_classes:
+
+            # skip other classes
+            if not getattr(clazz, WebAttr.IS_REST_CONTROLLER_ADVICE.value, False):
+                continue
+
+            context.ioc.register_class(clazz=clazz)
+
+        pass
+
+    def _register_rest_controller_class(self, context: PyBootContext):
+
+        for clazz in context.discovered_classes:
+
+            # skip other classes
+            if not getattr(clazz, WebAttr.IS_REST_CONTROLLER.value, False):
+                continue
+
+            context.ioc.register_class(clazz=clazz)
+
+    def _register_service_class(self, context: PyBootContext):
+
+        for clazz in context.discovered_classes:
+
+            # skip other classes
+            if not getattr(clazz, WebAttr.IS_WEB_SERVICE.value, False):
+                continue
+
+            context.ioc.register_class(clazz=clazz)
+
+    def _register_middleware_component_class(self,context:PyBootContext):
+
+        for clazz in context.discovered_classes:
+
+            #skip other classes
+            if not getattr(clazz,WebAttr.IS_MIDDLEWARE_COMPONENT.value,False):
+                continue
+
+            context.ioc.register_class(clazz=clazz)
+
+    def _load_service_class(self, context: PyBootContext):
+        pass
+
+    def _load_component_class(self, context: PyBootContext):
+        pass
+
+    def _load_rest_controller_advice(self, context: PyBootContext):
+
+        for clazz in context.discovered_classes:
+
+            # skip other classes
+            if not getattr(clazz, WebAttr.IS_REST_CONTROLLER_ADVICE.value, False):
+                continue
+
+            exception_handler_bean = context.ioc.get_bean(clazz=clazz)
+
+            # load the method beans for the exception handling
+            for method_name, method in inspect.getmembers(
+                exception_handler_bean, predicate=inspect.ismethod
+            ):
+
+                # skip other methods
+                if not getattr(
+                    method, WebAttr.IS_EXCEPTION_HANDLER_METHOD.value, False
+                ):
+                    continue
+
+                #get the type for which this method of exception is required to resolve
+                exception_type = getattr(
+                    method, WebAttr.EXCEPTION_HANDLER_FOR.value, None
+                )
+
+                #exception resolver cannot resolve None type exceptions
+                if exception_type is None:
+                    raise TypeError(
+                        f"Exception type cannot have {None} in exception handler method:{method_name} from class:{clazz.__name__}"
+                    )
+
+                #make it sure to exception_type is from the Exception Base class
+                if not isinstance(exception_type, type) or not issubclass(
+                    exception_type, Exception
+                ):
+                    raise TypeError(
+                        f"Invalid exception type in handler method: {method_name} "
+                        f"from class: {clazz.__name__}"
+                    )
+
+                #register the handler in the exception resolver
+                self.exception_resolver.register(
+                    exception_type=exception_type, handler=method
+                )
+
+    def _wrap_exception_handler(self, handler: EndPointT) -> EndPointT:
+
+        if inspect.iscoroutinefunction(handler):
+            # if async function
+            async_handler = cast(Callable[[Request], Awaitable[JSONResponse]], handler)
+
+            async def async_wrapper(request: Request) -> JSONResponse:
+
+                try:
+                    return await async_handler(request)
+                except Exception as exception:
+                    return self.exception_resolver.resolve(
+                        request=request, exception=exception
+                    )
+
+            return async_wrapper
+        else:
+            sync_handler = cast(Callable[[Request], JSONResponse], handler)
+
+            def sync_wrapper(request: Request) -> JSONResponse:
+                try:
+                    return sync_handler(request)
+                except Exception as exception:
+                    return self.exception_resolver.resolve(
+                        exception=exception, request=request
+                    )
+
+            return sync_wrapper
+
+    def _wrap_middlewares(self,handler:EndPointT,middlewares:list[MiddlewareBase])->EndPointT:
+
+        for middleware in reversed(middlewares):
+            next_handler=handler
+
+            async def wrapper(
+                    request:Request,
+                    middleware:MiddlewareBase=middleware,
+                    next_handler:EndPointT=next_handler
+            )->JSONResponse:
+                async def call_next(request:Request)->JSONResponse:
+                    result=next_handler(request)
+
+                    if inspect.isawaitable(result):
+                        return await result
+
+                    return result
+
+                result=middleware(request=request,call_next=call_next)
+
+                if inspect.isawaitable(result):
+                    return await result
+
+                return result
+            handler=wrapper
+
+
+        return handler
+                
+
+    def _load_rest_controllers(self, context: PyBootContext):
+
+        app: Starlette = context.app
+
+        for clazz in context.discovered_classes:
+
+            # skip other classes
+            if not getattr(clazz, WebAttr.IS_REST_CONTROLLER.value, False):
+                continue
+
+            #base path of the rest controller class
+            base_path: str = getattr(clazz, WebAttr.REST_CONTROLLER_PATH.value, "")
+
+            #the base middleware to be used
+            base_middleware_list:list[type[MiddlewareBase]]=getattr(clazz,WebAttr.MIDDLEWARE_LIST.value,[])
+
+            controller_bean = context.ioc.get_bean(clazz=clazz)
+
+            # scan all the methods
+            for method_name, method in inspect.getmembers(
+                controller_bean, inspect.ismethod
+            ):
+
+                # skip other methods
+                if not getattr(method, WebAttr.IS_ROUTE.value, False):
+                    continue
+
+                #path annotated on this method
+                route_path: str = getattr(method, WebAttr.ROUTE_PATH.value, "")
+
+                #total path of the endpoint
+                full_path = f"{base_path.rstrip("/")}/{route_path.lstrip("/")}"
+
+                #method of this endpoint
+                route_http_method: Literal["GET", "POST", "PUT", "PATCH", "DELETE"] = (
+                    getattr(method, WebAttr.ROUTE_METHOD.value, "GET")
+                )
+
+                #middlewares annotated to be used on this route
+                route_middlewares:list[type[MiddlewareBase]]=getattr(method,WebAttr.MIDDLEWARE_LIST.value,[])
+
+                #full list of the middlewares to be applied on this route
+                full_middleware_list:list[type[MiddlewareBase]]=base_middleware_list+route_middlewares
+
+                #getting the beans of middleware from the ioc containers
+                middleware_beans:list[MiddlewareBase]=[
+                    cast(
+                        MiddlewareBase,
+                        context.ioc.get_bean(clazz=middleware_class)
+                    )
+                    for middleware_class in full_middleware_list
+                ]
+
+                #the handler method itself
+                handler: EndPointT = cast(EndPointT, method)
+
+                #wrap the endpoint in the middlewares
+                wrapped_handler=self._wrap_middlewares(
+                    handler=handler,
+                    middlewares=middleware_beans
+                )
+
+                #wrap the handler in the exception resolver
+                wrapped_handler = self._wrap_exception_handler(handler=wrapped_handler)
+
+                #register the route in the app instance
+                app.add_route(  
+                    path=full_path,
+                    methods=[route_http_method],
+                    route=wrapped_handler
+                )
+
+                print(f"Registered route: {route_http_method} {full_path} for method: {method_name} in controller: {clazz.__name__}")
+
+
+    def _load_middleware_component_class(self,context:PyBootContext):
+        pass
+
+    def after_plugins_discovery(self, context: PyBootContext) -> None:
+        return super().after_plugins_discovery(context)
+
+    def before_classes_discovery(self, context: PyBootContext) -> None:
+        return super().before_classes_discovery(context)
+
+    def after_classes_discovery(self, context: PyBootContext) -> None:
+        return super().after_classes_discovery(context)
+
+    def before_register(self, context: PyBootContext) -> None:
+        return super().before_register(context)
+
+    def on_register(self, context: PyBootContext) -> None:
+        self._register_service_class(context=context)
+
+        #register rest controller advice because its bean will be used for the exception resolver of rest controller
+        self._register_rest_controller_advice(context=context)
+
+        #register the middleware component class
+        self._register_middleware_component_class(context=context)
+
+        #register the rest controller at last
+        self._register_rest_controller_class(context=context)
+
+        return
+
+    def after_register(self, context: PyBootContext) -> None:
+        return super().after_register(context)
+
+
+    def before_load(self, context: PyBootContext) -> None:
+        return super().before_load(context)
+
+    def on_load(self, context: PyBootContext) -> None:
+        self._load_service_class(context=context)
+        self._load_component_class(context=context)
+
+        #make sure to initialize the rest controller advice class so exception resolver can register it
+        self._load_rest_controller_advice(context=context)
+
+        #load the middleware component class
+        self._load_middleware_component_class(context=context)
+
+        #configure and load the rest controllers
+        self._load_rest_controllers(context=context)
+
+        return
+
+    def after_load(self, context: PyBootContext) -> None:
+        return super().after_load(context)
+
+    def on_ready(self, context: PyBootContext) -> None:
+        print(f"WebPlugin Ready for context:{context}")

pyboot_web/rest_mapping.py

@@ -0,0 +1,57 @@
+from .types import *
+
+from typing import Literal
+
+from .WebAttr import *
+from pyboot.core.types import ClassT
+
+class RestController:
+    def __init__(self,path:str) -> None:
+        self.path:str=path
+        return
+
+    def __call__(self, clazz:ClassT) -> ClassT:
+        setattr(clazz,WebAttr.IS_REST_CONTROLLER.value,True)
+        setattr(clazz,WebAttr.REST_CONTROLLER_PATH.value,self.path)
+
+        return clazz
+
+class RequestMapping:
+    def __init__(self,path:str,method:Literal["GET","POST","PUT","PATCH","DELETE"]) -> None:
+        self.path:str=path
+        self.method:str=method
+        return
+
+    def __call__(self,func:ControllerMethodT) ->ControllerMethodT:
+        setattr(func,WebAttr.IS_ROUTE.value,True)
+        setattr(func,WebAttr.ROUTE_PATH.value,self.path)
+        setattr(func,WebAttr.ROUTE_METHOD.value,self.method)
+
+        return func
+
+class GetMapping(RequestMapping):
+    def __init__(self, path: str) -> None:
+        super().__init__(path=path,method="GET")
+
+
+class PostMapping(RequestMapping):
+    def __init__(self,path:str)->None:
+        super().__init__(path=path,method="POST")
+
+
+class PutMapping(RequestMapping):
+    def __init__(self,path:str)->None:
+        super().__init__(path=path,method="PUT")
+
+
+class PatchMapping(RequestMapping):
+    def __init__(self,path:str)->None:
+        super().__init__(path=path,method="PATCH")
+
+
+class DeleteMapping(RequestMapping):
+    def __init__(self,path:str)->None:
+        super().__init__(path=path,method="DELETE")
+
+
+

pyboot_web/service.py

@@ -0,0 +1,11 @@
+from pyboot.core.types import ClassT
+
+from .WebAttr import WebAttr
+
+class Service:
+    def __init__(self) -> None:
+        pass
+
+    def __call__(self,clazz:ClassT) -> ClassT:
+        setattr(clazz,WebAttr.IS_WEB_SERVICE.value,True)
+        return clazz

pyboot_web/types.py

@@ -0,0 +1,16 @@
+from typing import TypeVar,TypeAlias,Callable,Any,Awaitable
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+E=TypeVar("E",bound=Exception)
+
+ControllerMethodT: TypeAlias = (
+    Callable[[Any, Request], JSONResponse]
+    | Callable[[Any, Request], Awaitable[JSONResponse]]
+)
+
+EndPointT: TypeAlias = (
+    Callable[[Request], JSONResponse]
+    | Callable[[Request], Awaitable[JSONResponse]]
+)

pyboot_web/value.py

@@ -0,0 +1,63 @@
+import os
+from typing import Any
+from dotenv import load_dotenv,find_dotenv
+
+from pyboot import PyBootContext
+from pyboot.core.pyboot_plugin import PyBootPlugin
+
+
+def Value(key:str,default:Any):
+    """
+    This function retrieves the value of an environment variable specified by the key. It first checks if the environment variable is set; if not, it falls back to the provided default value. If neither is available, it raises a MissingValueException. This function is useful for accessing configuration values that may be defined in a .env file or as system environment variables.
+    """
+    from_env = os.getenv(key=key) if os.getenv(key=key) is not None else default
+
+    if from_env is None:
+        raise MissingValueException(f"Missing value for key:{key}.Got Value {from_env}")
+
+    return from_env
+
+class MissingValueException(Exception):
+    """
+    This exception is raised when a required value is missing. It is used in the Value function to indicate that an expected environment variable or default value was not provided, signaling a configuration issue that needs to be addressed.
+    """
+    def __init__(self,message:str) -> None:
+        self.message:str=message
+        return
+
+#ValuePlugin class implements the PyBootPlugin interface and provides lifecycle hooks for managing environment variable loading. It uses the dotenv library to load environment variables from a .env file before class discovery, ensuring that configuration values are available throughout the application lifecycle.
+class ValuePlugin(PyBootPlugin):
+    """
+    This is the plugin class for managing environment variable loading in a PyBoot application. It implements the PyBootPlugin interface and provides lifecycle hooks that are called at various stages of the application startup process. The primary purpose of this plugin is to load environment variables from a .env file before class discovery, ensuring that configuration values are available for use throughout the application.
+    """
+
+    def after_plugins_discovery(self, context: PyBootContext) -> None:
+        pass
+
+    def before_classes_discovery(self, context: PyBootContext) -> None:
+        load_dotenv(find_dotenv(usecwd=True),override=True)
+        return
+
+    def after_classes_discovery(self, context: PyBootContext) -> None:
+        pass
+
+    def before_register(self, context: PyBootContext) -> None:
+        pass
+
+    def on_register(self, context: PyBootContext) -> None:
+        pass
+
+    def after_register(self, context: PyBootContext) -> None:
+        pass
+
+    def before_load(self, context: PyBootContext) -> None:
+        pass
+
+    def on_load(self, context: PyBootContext) -> None:
+        pass
+
+    def after_load(self, context: PyBootContext) -> None:
+        pass
+
+    def on_ready(self, context: PyBootContext) -> None:
+        pass

pyboot_web-0.1.0.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: pyboot-web
+Version: 0.1.0
+Summary: Starlette web plugin for PyBoot
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyboot-framework>=0.1.0
+Requires-Dist: starlette>=0.40.0
+Requires-Dist: pydantic>=2.0
+Dynamic: license-file
+
+# pyboot-web
+
+`pyboot-web` is the Starlette web plugin for [PyBoot](../../pyboot/README.md).
+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](./EXAMPLES.md) - runnable snippets for routing, services,
+  middleware, exception advice, and configuration.
+- [Production starter](./STARTER.md) - a recommended project layout,
+  bootstrap implementation, deployment checklist, and testing approach.
+- [License](./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:
+
+```bash
+python -m pip install pyboot-framework pyboot-web
+python -m pip install python-dotenv uvicorn
+```
+
+For a source checkout, from the repository root:
+
+```bash
+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:
+
+```bash
+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:
+
+```python
+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:
+
+```bash
+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:
+
+```python
+@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:
+
+```python
+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`:
+
+```python
+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](./LICENSE).

pyboot_web-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+pyboot_web/ExceptionResolver.py,sha256=Oy88bUSAO7ngDPtsiAW9o7lQyQF7dX5RBen2YymUBMo,1009
+pyboot_web/WebAttr.py,sha256=AFDjiNVj8ik0ggk-B3YySy00f5OQ6mqkRakwsWJyWFE,575
+pyboot_web/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyboot_web/exception_handler.py,sha256=N3ykGEXa8z8iasti9VbETprpCmqZgjtse50a1sFyNU8,766
+pyboot_web/middlewares.py,sha256=g2fclsMJ_N0CucUsasBT-bbgIh9zp-i19UjfOXcxeVI,1314
+pyboot_web/plugin.py,sha256=cwupIrhhZld5UZMv1mSfYjWThM6IbR_MqTFZ2Sx1FSM,11191
+pyboot_web/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyboot_web/rest_mapping.py,sha256=wgLooK3w0YlQFtYngAqTTgWqF3ion4nttrACVPicjEg,1557
+pyboot_web/service.py,sha256=CAtxlHjiprQH5-42vThpfCHwp-Gv7D6AOsaeRtdjw34,263
+pyboot_web/types.py,sha256=tjCyId9IxPFkqkUV6xZNkMgv8gkhXvUIjWCsvzyF59g,443
+pyboot_web/value.py,sha256=NFUZBLwrkTkKB4a3MX2KZQT2ofWtc4bqCEU_YjWLDTo,2883
+pyboot_web-0.1.0.dist-info/licenses/LICENSE,sha256=MaPMFkS6sDLwCqmK7QNFZRB8EJng3h8TLkrFQcByH7s,1097
+pyboot_web-0.1.0.dist-info/METADATA,sha256=-YX-brKti0ub9J6EvcaFg7_cA14UczO_XpQDsA5dPOM,8000
+pyboot_web-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pyboot_web-0.1.0.dist-info/entry_points.txt,sha256=NRI3Ju3uBCLJIUaxMHHoRh5ont2dHkY4gtCzf0DCIBw,88
+pyboot_web-0.1.0.dist-info/top_level.txt,sha256=hbEdvPKJgVkiL2-eWC3IJBd2ESzyBiZHmsDIxqNxvd4,11
+pyboot_web-0.1.0.dist-info/RECORD,,

pyboot_web-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyboot_web-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[pyboot.plugins]
+value = pyboot_web.value:ValuePlugin
+web = pyboot_web.plugin:WebPlugin

pyboot_web-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pyboot contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyboot_web-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyboot_web