Skip to main content

PyBoot

A lightweight, extensible Python framework for building applications with Inversion of Control, Dependency Injection, and a modular plugin architecture.

Python PyPI License

PyBoot is a Python framework designed around a simple idea: application components should focus on their responsibilities, while the framework handles object creation, dependency resolution, lifecycle management, and application infrastructure.

Inspired by the programming model of frameworks like Spring Boot, PyBoot brings a structured IoC container and dependency injection system to Python without forcing every application to depend on a large collection of built-in features.

Its architecture is designed to remain lightweight at its core while allowing developers to extend its capabilities through plugins.


Table of Contents


Why PyBoot?

Python has several excellent frameworks for building applications. However, when applications grow, managing dependencies, object creation, shared resources, and application initialization can become increasingly difficult.

Developers often end up manually constructing objects and passing dependencies throughout the application.

Consider a simple dependency chain:

UserController
      |
      v
UserService
      |
      v
UserRepository
      |
      v
DatabaseClient

Without a dependency management system, the developer is responsible for constructing every object and ensuring that the correct dependencies are passed to each constructor.

As the application grows, this responsibility becomes increasingly repetitive.

PyBoot aims to solve this problem through Inversion of Control.

Instead of manually managing application objects, developers declare their components and dependencies. PyBoot takes responsibility for discovering components, constructing objects, resolving dependencies, and managing their lifecycle.

The goal is not to introduce another collection of abstractions. It is to provide a predictable application architecture with minimal framework overhead.

Core Philosophy

PyBoot is built around four principles.

1. Inversion of Control

Application objects should not be responsible for constructing their own dependencies.

The framework manages object creation and dependency resolution through a centralized IoC container.

2. Constructor-based Dependency Injection

Dependencies should be explicitly declared through constructors.

This makes dependencies visible, improves testability, and avoids unnecessary service locators or hidden global state.

3. Lightweight Core

The core should contain only the fundamental infrastructure required to manage an application.

Features such as web routing, database integration, ORM mapping, validation, and scheduling should be provided through optional extensions.

This prevents developers from installing unnecessary dependencies when they only need the IoC container.

4. Extensibility Through Plugins

PyBoot is designed to allow developers to extend the framework without modifying its internal implementation.

Plugins can participate in application registration, initialization, and lifecycle management.


Features

PyBoot focuses on providing a foundation for structured Python applications.

Feature Description
IoC Container Centralized management of application objects
Dependency Injection Automatic constructor dependency resolution
Component Discovery Discover application components
Lifecycle Management Control object initialization and application startup
Plugin Architecture Extend framework capabilities independently
Modular Design Keep optional functionality outside the core
Python Type Hints Use Python type annotations for dependency resolution
Starlette Integration Support web application development through web integration

Some capabilities may depend on the availability of their respective extensions.


Installation

Install PyBoot using pip:

pip install pyboot-framework

PyBoot requires Python 3.11 or newer.

The core package is designed to remain lightweight. Optional integrations should be installed separately when required.


Getting Started

The following example illustrates the intended component-oriented programming model.

1. Define a component

A component is an object managed by the PyBoot IoC container.

from pyboot import Component


@Component
class UserService:

    def get_user(self, user_id: int):
        return {
            "id": user_id,
            "name": "Siddharth"
        }

By marking a class as a component, it becomes eligible for framework-managed object creation and dependency injection.

2. Declare dependencies

Components can declare their dependencies through constructor parameters.

from pyboot import Component


@Component
class UserRepository:

    def find_by_id(self, user_id: int):
        return {
            "id": user_id,
            "name": "Siddharth"
        }


@Component
class UserService:

    def __init__(self, repository: UserRepository):
        self.repository = repository

    def get_user(self, user_id: int):
        return self.repository.find_by_id(user_id)

Here, UserService does not create UserRepository itself.

Instead, PyBoot resolves the dependency and supplies the appropriate component instance.

This keeps object construction separate from application business logic.

3. Build application components

The framework discovers registered components and manages their dependencies through its IoC container.

The exact bootstrap API depends on the application integration being used.


Inversion of Control

Inversion of Control is the foundation of PyBoot.

Traditionally, application code controls object creation:

class UserRepository:
    pass


class UserService:

    def __init__(self):
        self.repository = UserRepository()

This creates a direct dependency between UserService and the construction of UserRepository.

With PyBoot, object creation is delegated to the framework:

@Component
class UserRepository:
    pass


@Component
class UserService:

    def __init__(self, repository: UserRepository):
        self.repository = repository

The framework takes responsibility for:

  1. Discovering registered component classes.
  2. Identifying their constructor dependencies.
  3. Resolving dependencies from the IoC container.
  4. Creating component instances.
  5. Managing the resulting instances.

This provides a centralized mechanism for managing application objects.

Dependency Resolution

PyBoot uses Python type annotations to identify constructor dependencies.

For example:

@Component
class DatabaseClient:
    pass


@Component
class UserRepository:

    def __init__(self, database: DatabaseClient):
        self.database = database


@Component
class UserService:

    def __init__(self, repository: UserRepository):
        self.repository = repository

The dependency graph is:

UserService
    |
    v
UserRepository
    |
    v
DatabaseClient

The IoC container resolves the dependency chain when constructing the application components.


Component Management

Components are the fundamental building blocks of a PyBoot application.

A component is a class whose instance is managed by the framework.

@Component
class EmailService:

    def send(self, recipient: str, message: str):
        print(f"Sending email to {recipient}")

Components allow application developers to organize functionality into independent units.

A component can depend on other components, allowing PyBoot to construct complex dependency graphs automatically.

Component Responsibilities

Components should:

  • Encapsulate a specific responsibility.
  • Declare dependencies explicitly.
  • Avoid manually constructing framework-managed dependencies.
  • Keep business logic independent of application bootstrap logic.

Application Lifecycle

Application initialization is an important responsibility of a framework.

PyBoot is designed around a controlled initialization process rather than requiring every extension to independently initialize itself.

The conceptual lifecycle consists of:

Application Bootstrap
        |
        v
Plugin Registration
        |
        v
Component Discovery
        |
        v
Dependency Resolution
        |
        v
Bean Creation
        |
        v
Plugin Initialization
        |
        v
Application Ready

This separation allows plugins to register their capabilities before application initialization and perform setup after the required application objects are available.


Plugin Architecture

One of PyBoot's primary design goals is extensibility.

Rather than putting every framework feature into the core package, PyBoot provides a plugin architecture through which optional capabilities can be introduced.

For example:

Plugin Responsibility
Web HTTP routing, controllers, middleware
ORM Object-relational mapping and entity management
Database Database connectivity and repositories
Validation Request and data validation
Scheduling Scheduled task execution
Configuration External configuration management

These are examples of potential extensions, not a claim that every plugin is currently available.

Why Plugins?

Consider an application that only needs dependency injection.

It should not need to install an ORM, web server, validation engine, or scheduling system.

Similarly, an application that needs HTTP routing should be able to install the web integration without forcing database dependencies into its environment.

This keeps the core independent of optional infrastructure.

Developing Plugins

PyBoot is intended to provide extension points for plugin developers.

A plugin should be able to participate in framework registration and application initialization without requiring modifications to the core.

The plugin lifecycle is designed around two important phases:

Registration phase

Used to register metadata, components, integrations, and other framework capabilities.

Loading phase

Used to perform initialization that requires framework-managed objects to exist.

This separation helps avoid initialization-order problems and allows plugins to integrate with the application lifecycle.

Plugin API documentation will be expanded as the extension interfaces stabilize.


Web Integration

PyBoot is designed to support web application development through Starlette-based integration.

The intention is to combine Starlette's lightweight ASGI infrastructure with PyBoot's IoC container and component management.

A typical web application can be organized into:

Application
    |
    +-- Controllers
    |
    +-- Services
    |
    +-- Repositories
    |
    +-- Infrastructure

The web integration is responsible for HTTP-specific functionality, while the core remains focused on application object management.

This separation means that web-specific dependencies do not need to become mandatory dependencies of the core package.


Project Structure

A typical application using PyBoot could follow this structure:

my-application/
│
├── app/
│   │
│   ├── controllers/
│   │   └── user_controller.py
│   │
│   ├── services/
│   │   └── user_service.py
│   │
│   ├── repositories/
│   │   └── user_repository.py
│   │
│   ├── infrastructure/
│   │   └── database.py
│   │
│   └── main.py
│
├── tests/
│
├── requirements.txt
└── README.md

This structure is only a recommendation. PyBoot aims to avoid enforcing a particular application directory structure.

Developers should be able to organize their applications according to their requirements.


Design Philosophy

PyBoot is not intended to replace every Python framework.

Its purpose is to provide a structured foundation for building applications with centralized object management and extensible infrastructure.

A few important design decisions guide its development:

Explicit dependencies over hidden dependencies

Constructor injection makes the dependency graph visible and easier to understand.

Composition over inheritance

Application functionality should be assembled through components and plugins rather than requiring developers to inherit from large framework classes.

Optional integrations over mandatory dependencies

The core should not require developers to install functionality they do not use.

Centralized lifecycle management

Application initialization should follow a predictable lifecycle instead of depending on arbitrary plugin initialization order.

Extensibility without unnecessary complexity

Plugins should extend the framework through well-defined interfaces rather than modifying its internal implementation.


Roadmap

PyBoot is currently under active development.

The following areas represent its development direction:

  • Initial IoC container architecture
  • Constructor-based dependency injection
  • Component metadata and discovery
  • Stable application lifecycle API
  • Stable plugin development API
  • Configuration management
  • Bean scopes and lifecycle controls
  • Web integration
  • Controller and routing support
  • Middleware integration
  • Global exception handling
  • ORM integration
  • Repository abstraction
  • Validation integration
  • Comprehensive documentation
  • Testing and performance benchmarks

Roadmap items should be updated as features are implemented and released.


Contributing

Contributions, suggestions, bug reports, and discussions are welcome.

If you want to contribute:

  1. Fork the repository.
  2. Clone your fork.
  3. Create a feature branch.
  4. Implement your changes.
  5. Add or update tests.
  6. Submit a pull request.

For substantial architectural changes, open an issue first to discuss the proposed design.

Please keep contributions consistent with PyBoot's core philosophy: lightweight infrastructure, clear abstractions, and extensibility without unnecessary complexity.


License

PyBoot is licensed under the MIT License.

See the LICENSE file for details.


Author

Developed by Siddharth Karn.

If you are interested in contributing, improving the architecture, or building extensions for PyBoot, contributions are welcome.

PyBoot — A lightweight foundation for structured Python applications.

Metadata

Release files for pyboot-framework 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-framework 0.1.0
File Size Uploaded Provenance Actions
pyboot_framework-0.1.0.tar.gz 17.4 kB Without provenance Details for pyboot_framework-0.1.0.tar.gz

Built distribution (wheel)

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

Total release size: 32.3 kB

Release files / pyboot_framework-0.1.0.tar.gz

Download URL pyboot_framework-0.1.0.tar.gz
Size 17.4 kB
Tags Source
SHA-256 checksum
How to use checksums
f4604a3a69762fa504e3836d82215017acb4f95ab4b6f8d1d8622aeb483253ae
BLAKE2b-256 checksum
How to use checksums
fc3aaad5571d9b736e0aaa6907510c0975c705c89792bc3ddff939f86692a6c7
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.0-py3-none-any.whl

Download URL pyboot_framework-0.1.0-py3-none-any.whl
Size 14.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
10caeee317122437f91d360a4760e60433288bb31faa7b05c766cca35b7d00fa
BLAKE2b-256 checksum
How to use checksums
8bf2ef35759e0e593e4606d7620c1177cd13fbe171703833aa5753c86089c3b2
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.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