Skip to main content

PyBoot

PyBoot is a lightweight Python framework for inversion of control (IoC), constructor-based dependency injection, component discovery, and extensible plugin lifecycle management.

The core package deliberately does not create a web server or impose an application class. Optional packages, such as pyboot-web, add infrastructure through the plugin system.

Requirements

  • Python 3.11 or newer
  • pyboot-framework 0.1.x

Installation

python -m pip install pyboot-framework

For development from this repository:

python -m pip install -e .

Quick start

Application classes must be inside the package passed to bootstrap(). PyBoot imports that package and recursively scans its submodules for classes.

app/services.py:

from pyboot.core.builtins.component import Component


@Component()
class GreetingService:
    def greet(self, name: str) -> str:
        return f"Hello, {name}!"

main.py:

from pyboot import PyBoot
from app.services import GreetingService


boot = PyBoot(debug=False)
boot.bootstrap(package="app")

service = boot.get_context().ioc.get_bean(GreetingService)
print(service.greet("PyBoot"))

bootstrap() returns None. It initializes the context in place. Enable framework logging with PyBoot(debug=True).

Components and dependency injection

@Component() marks a class for registration by the built-in component plugin. Required constructor parameters must have type annotations:

from pyboot.core.builtins.component import Component


@Component()
class UserRepository:
    def find_name(self, user_id: int) -> str:
        return {1: "Ada", 2: "Grace"}.get(user_id, "Unknown")


@Component()
class UserService:
    def __init__(self, repository: UserRepository) -> None:
        self.repository = repository

    def name_for(self, user_id: int) -> str:
        return self.repository.find_name(user_id)

The container resolves dependencies recursively and caches resolved objects as singletons. Do not construct managed dependencies manually when you need their managed instance.

service = boot.get_context().ioc.get_bean(UserService)
same_service = boot.get_context().ioc.get_bean(UserService)
assert service is same_service

Optional constructor parameters with defaults are not resolved. A required parameter without a type annotation raises a dependency-resolution error. Circular dependency graphs are rejected.

Configuration and bean factories

Use @Configuration() for a class containing factory methods. Every @Bean() method must declare its return type; the return type is the IoC key.

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


class Settings:
    def __init__(self, service_name: str) -> None:
        self.service_name = service_name


@Configuration()
class ApplicationConfiguration:
    @Bean()
    def settings(self) -> Settings:
        return Settings("example-service")

Bean methods may also receive annotated dependencies:

@Configuration()
class ClientConfiguration:
    @Bean()
    def client(self, settings: Settings) -> dict[str, str]:
        return {"service": settings.service_name}

Application context

PyBootContext contains the discovered classes, IoC container, loaded plugin instances, and a resource bucket:

context = boot.get_context()
service = context.ioc.get_bean(UserService)

context.put_resource("service_name", "example-service")
assert context.exist_resource("service_name")
assert context.get_resource("service_name") == "example-service"

context.update_resource("service_name", "updated-service")

put_resource() rejects duplicate keys. update_resource() requires an existing key. Resources are useful for sharing initialized infrastructure between plugins.

Plugin architecture

PyBoot discovers plugin classes from the pyboot.plugins Python entry-point group. A plugin extends PyBootPlugin:

from pyboot import PyBootPlugin
from pyboot.core.pyboot_context import PyBootContext


class MetricsPlugin(PyBootPlugin):
    def after_plugins_discovery(self, context: PyBootContext) -> None:
        context.put_resource("metrics", {"started": True})

    def on_ready(self, context: PyBootContext) -> None:
        print("PyBoot is ready")

Register it in the plugin package's pyproject.toml:

[project.entry-points."pyboot.plugins"]
metrics = "my_metrics.plugin:MetricsPlugin"

Install the plugin into the same environment as the application. PyBoot creates one instance of each discovered plugin during bootstrap().

The lifecycle order is:

after_plugins_discovery
before_classes_discovery
after_classes_discovery
before_register
on_register
after_register
before_load
on_load
after_load
on_ready

Use on_register() to register discovered classes or bean factories. Use after_load() and on_ready() after IoC beans have been created. Plugin ordering is not guaranteed, so plugins should not depend on incidental iteration order.

Retrieve a plugin by its class:

from my_metrics.plugin import MetricsPlugin


metrics = boot.get_plugin(MetricsPlugin)

get_plugin() raises LookupError when the requested plugin was not loaded.

Built-in plugins

The core distribution registers these entry points:

Entry point Responsibility
configuration Registers @Configuration() classes and @Bean() methods
component Registers @Component() classes

Other packages can register additional entry points. For example, pyboot-web registers web controllers, services, middleware, scheduling, environment loading, and Starlette integration.

Discovery rules

Given bootstrap("app"), PyBoot:

  1. Loads installed pyboot.plugins entry points.
  2. Imports app.
  3. Walks app submodules with pkgutil.
  4. Records classes defined by those modules.
  5. Lets plugins register the classes they own.
  6. Creates registered beans.
  7. Runs the remaining lifecycle hooks.

Use normal Python packages with __init__.py files and keep application classes below the scanned package. Imported classes are ignored unless they are defined in the module currently being scanned.

Exceptions

Common core exceptions include:

  • ClassNotRegisteredForBean: a requested class has no registration.
  • DependencyResolutionException: a dependency cannot be resolved.
  • CircularDependencyException: a dependency graph contains a cycle.
  • MultipleBeanException: multiple definitions use the same bean type.
  • KeyAlreadyInResourceBucketException: a resource key already exists.

Import exceptions from pyboot.core.exceptions when application code needs to handle them explicitly.

Testing

Business logic remains ordinary Python and can be unit tested without bootstrapping:

def test_user_service() -> None:
    repository = UserRepository()
    service = UserService(repository)
    assert service.name_for(1) == "Ada"

Test wiring by bootstrapping a package and retrieving the bean from its context:

def test_user_service_is_wired() -> None:
    boot = PyBoot()
    boot.bootstrap("app")
    assert boot.get_context().ioc.get_bean(UserService).name_for(1) == "Ada"

License

PyBoot is distributed under the MIT License. See LICENSE.

Metadata

Release files for pyboot-framework 0.1.18

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-framework 0.1.18
File Size Uploaded Provenance Actions
pyboot_framework-0.1.18.tar.gz 15.1 kB Without provenance Details for pyboot_framework-0.1.18.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyboot-framework 0.1.18
File Interpreter ABI Platform Actions
pyboot_framework-0.1.18-py3-none-any.whl Python 3 none any Details for pyboot_framework-0.1.18-py3-none-any.whl

Total release size: 30.9 kB

Release files / pyboot_framework-0.1.18.tar.gz

Download URL pyboot_framework-0.1.18.tar.gz
Size 15.1 kB
Tags Source
SHA-256 checksum
How to use checksums
cd64c32d383db2d24197ddd5befb24c7acc46d100cc81cc7673726232724e0a8
BLAKE2b-256 checksum
How to use checksums
7b9f0290746a677e2a865bfced63d4e233ef8dee64f198291dd7fe63b747d3ee
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Release files / pyboot_framework-0.1.18-py3-none-any.whl

Download URL pyboot_framework-0.1.18-py3-none-any.whl
Size 15.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
580686749a4a66bf250caaff89b265fe9b542df41c5d14be7d62496bd87687e6
BLAKE2b-256 checksum
How to use checksums
fbcde9b5e06a65e85d9110bd8f3b8107345473bdab540cf87956f8313ffb078a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Security for pyboot-framework 0.1.18

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