pyboot-framework 0.1.0__tar.gz

pyboot_framework-0.1.0/PKG-INFO

@@ -0,0 +1,571 @@
+Metadata-Version: 2.4
+Name: pyboot-framework
+Version: 0.1.0
+Summary: A lightweight, extensible Python framework for building applications with dependency injection and a modular plugin architecture.
+Author: Siddharth Karn
+License-Expression: MIT
+Keywords: pyboot,python-framework,dependency-injection,inversion-of-control,ioc,plugin-architecture,starlette
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# PyBoot
+
+**A lightweight, extensible Python framework for building applications with Inversion of Control, Dependency Injection, and a modular plugin architecture.**
+
+[![Python](https://img.shields.io/badge/Python-3.11%2B-blue)](https://www.python.org/)
+[![PyPI](https://img.shields.io/pypi/v/pyboot-framework)](https://pypi.org/project/pyboot-framework/)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](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?](#why-pyboot)
+- [Core Philosophy](#core-philosophy)
+- [Features](#features)
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Inversion of Control](#inversion-of-control)
+- [Dependency Injection](#dependency-injection)
+- [Component Management](#component-management)
+- [Application Lifecycle](#application-lifecycle)
+- [Plugin Architecture](#plugin-architecture)
+- [Web Integration](#web-integration)
+- [Project Structure](#project-structure)
+- [Design Philosophy](#design-philosophy)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## 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:
+
+```text
+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:
+
+```bash
+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.
+
+```python
+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.
+
+```python
+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:
+
+```python
+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:
+
+```python
+@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:
+
+```python
+@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:
+
+```text
+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.
+
+```python
+@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:
+
+```text
+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:
+
+```text
+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:
+
+```text
+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:
+
+- [x] Initial IoC container architecture
+- [x] Constructor-based dependency injection
+- [x] 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](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.**