pyboot-framework 0.1.0__py3-none-any.whl

pyboot/__init__.py

@@ -0,0 +1,6 @@
+from pyboot.core.application import *
+from pyboot.core.types import *
+from pyboot.core.pyboot_plugin import *
+from pyboot.core.pyboot_context import *
+from pyboot.core.ioc import *
+from pyboot.core.exceptions import *

pyboot/core/application.py

@@ -0,0 +1,162 @@
+from .pyboot_context import PyBootContext
+from .pyboot_plugin import PyBootPlugin
+from .types import *
+from .plugin_loader import PluginLoader
+from .exceptions import *
+
+import importlib
+import pkgutil
+import inspect
+
+from typing import TypeVar,Generic
+
+from loguru import logger
+
+T = TypeVar("T")
+
+#PyBoot Application Class
+class PyBoot(Generic[T]):
+    """
+    This class represents the core of the PyBoot framework. It is responsible for bootstrapping the application, discovering classes and plugins, and managing the application context.It is the main entry point for initializing and running a PyBoot application. It provides methods to scan for classes in a specified package, load plugins, and execute the lifecycle hooks defined by the plugins.
+    """
+
+    def __init__(self,app_instance:T,debug:bool=False) -> None:
+        self.plugin_loader:PluginLoader=PluginLoader()
+        self.context:PyBootContext=PyBootContext(app=app_instance)
+        
+        if debug:
+            logger.enable("pyboot")
+        else:
+            logger.disable("pyboot")
+        
+        return
+
+    def get_app(self)->T:
+        """
+        Returns the application instance.This is useful for accessing the main application object from within plugins or other components of the framework.Instance of the application can be retrieved using this method, allowing for interaction with the application's state and behavior.
+        """
+        return self.context.app
+
+    #scan all global level classes in the package
+    def scan_classes(self, package_name: str):
+        """
+        Scans the specified package for all classes defined within it. This method uses Python's importlib and pkgutil modules to dynamically discover and import modules within the given package, and then inspects each module to find classes. It returns a set of all discovered classes.
+        """
+        logger.debug(f"Scanning package:{package_name} for classes...")
+
+        classes:set[ClassTBase]=set()
+
+        logger.info(f"Importing package:{package_name}...")
+        package = importlib.import_module(name=package_name)
+        logger.info(f"Package:{package_name} imported successfully.")
+    
+        for module_info in pkgutil.walk_packages(
+                path=package.__path__, prefix=f"{package.__name__}."
+        ):
+
+            logger.debug(f"Importing module:{module_info.name}...")
+            module = importlib.import_module(module_info.name)
+            logger.debug(f"Module:{module_info.name} imported successfully.")
+    
+            for _, clazz in inspect.getmembers(module, predicate=inspect.isclass):
+    
+                # skip imported modules
+                if clazz.__module__ != module.__name__:
+                    continue
+
+                logger.debug(f"Discovered class:{clazz.__name__} in module:{module_info.name}.")
+                classes.add(clazz)
+                logger.info(f"Class:{clazz.__name__} added to discovered classes.")
+
+
+        return classes
+
+    #boot strap the application
+    def bootstrap(self,package:str)->None:
+        """
+        This method orchestrates the bootstrapping process of the application. It performs several key steps:
+        1. Loads plugins using the PluginLoader.
+        2. Executes lifecycle hooks defined by the plugins at various stages of the bootstrapping process.
+        3. Scans the specified package for classes and registers them in the application context.
+        4. Creates class-level beans for all discovered classes.
+        5. Executes additional lifecycle hooks after class discovery and bean creation.
+        6. Finally, it signals that the application is ready by calling the on_ready hook of each plugin.
+        """
+
+        logger.info("Bootstrapping the application...")
+
+        logger.info(f"Scanning package:{package} for classes and plugins...")
+        #Discover and load the plugin objects
+        self.plugins:set[PyBootPlugin]=self.plugin_loader.load_plugins()
+        logger.debug(f"Discovered Plugins:{self.plugins}")
+        logger.info("Running the after_plugin_discovery...")
+        #after_plugins_discovery
+        for plugin in self.plugins:
+            plugin.after_plugins_discovery(context=self.context)
+        logger.info("Plugin lifecycle complete!!!")
+
+        logger.info("Running the before_classes_discovery...")
+        #before_classes_discovery
+        for plugin in self.plugins:
+            plugin.before_classes_discovery(context=self.context)
+        logger.info("Discovering classes...")
+        #discover
+        self.context.discovered_classes=self.scan_classes(package_name=package)
+        logger.info(f"Discovered classes:{self.context.discovered_classes}")
+        logger.info("Running the after_classes_discovery...")
+        #after_classes_discovery
+        for plugin in self.plugins:
+            plugin.after_classes_discovery(context=self.context)
+        logger.info("Class discovery lifecycle complete!!!")
+
+        logger.info("Running the before_register...")
+        #before_register
+        for plugin in self.plugins:
+            plugin.before_register(context=self.context)
+        logger.info("before_register lifecycle complete!!!")
+
+        logger.info("Running the on_register...")
+        #on_register
+        for plugin in self.plugins:
+            plugin.on_register(context=self.context)
+        logger.info("on_register lifecycle complete!!!")
+
+        logger.info("Running the after_register...")
+        #after_register
+        for plugin in self.plugins:
+            plugin.after_register(context=self.context)
+        logger.info("after_register lifecycle complete!!!")
+
+        logger.info("Creating class level beans...")
+        #create class level beans only beans
+        for clazz in self.context.ioc.definitions:
+            self.context.ioc.get_bean(clazz=clazz)
+        logger.info("Class level beans created successfully!!!")
+
+        logger.info("Running the before_load...")
+        #before_load
+        for plugin in self.plugins:
+            plugin.before_load(context=self.context)
+        logger.info("before_load lifecycle complete!!!")
+
+        logger.info("Running the on_load...")
+        #on_load
+        for plugin in self.plugins:
+            plugin.on_load(context=self.context)
+        logger.info("on_load lifecycle complete!!!")
+
+        logger.info("Running the after_load...")
+        #after_load
+        for plugin in self.plugins:
+            plugin.after_load(context=self.context)
+        logger.info("after_load lifecycle complete!!!")
+
+        logger.info("Running the on_ready...")
+        #on_ready
+        for plugin in self.plugins:
+            plugin.on_ready(context=self.context)
+        logger.info("on_ready lifecycle complete!!!")
+
+        return None
+
+    

pyboot/core/builtins/BuiltInAttr.py

@@ -0,0 +1,8 @@
+from enum import Enum
+
+class BuiltInAttr(Enum):
+    IS_PYBOOT_COMPONENT_CLASS="__is_pyboot_component_class__"
+
+    IS_PYBOOT_CONFIGURATION_CLASS="__is_pyboot_configuration_class__"
+
+    IS_PYBOOT_BEAN_FACTORY="__is_pyboot_bean_factory__"

pyboot/core/builtins/component.py

@@ -0,0 +1,58 @@
+from pyboot.core.pyboot_context import PyBootContext
+
+from .BuiltInAttr import BuiltInAttr
+from ..types import *
+from ..pyboot_plugin import PyBootPlugin
+
+
+class Component:
+    def __init__(self) -> None:
+        pass
+
+    def __call__(self, clazz: ClassT) -> ClassT:
+        setattr(clazz, BuiltInAttr.IS_PYBOOT_COMPONENT_CLASS.value, True)
+        return clazz
+
+
+class ComponentPlugin(PyBootPlugin):
+
+    def __init__(self) -> None:
+        pass
+
+    def after_plugins_discovery(self, context: PyBootContext) -> None:
+        pass
+
+    def before_classes_discovery(self, context: PyBootContext) -> None:
+        pass
+
+    def after_classes_discovery(self, context: PyBootContext) -> None:
+        pass
+
+    def before_register(self, context: PyBootContext) -> None:
+        pass
+
+    def on_register(self, context: PyBootContext) -> None:
+        for clazz in context.discovered_classes:
+
+            #skip other classes
+            if not getattr(clazz,BuiltInAttr.IS_PYBOOT_COMPONENT_CLASS.value,False):
+                continue
+
+            context.ioc.register_class(clazz=clazz)
+
+        return
+
+    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/core/builtins/configuration.py

@@ -0,0 +1,97 @@
+from ..pyboot_context import PyBootContext
+from .BuiltInAttr import BuiltInAttr
+from ..pyboot_plugin import PyBootPlugin
+from ..types import *
+
+import inspect
+from typing import Any, get_type_hints
+
+class InvalidBeanFactoryDefinitionException(Exception):
+    def __init__(self,message:str) -> None:
+        self.message:str=message
+        return
+
+
+class Configuration:
+    def __init__(self) -> None:
+        pass
+
+    def __call__(self,clazz:ClassT) -> ClassT:
+        setattr(clazz,BuiltInAttr.IS_PYBOOT_CONFIGURATION_CLASS.value,True)
+        return clazz
+
+class Bean:
+    def __init__(self) -> None:
+        pass
+
+    def __call__(self,method:Callable[...,Any]) ->Callable[...,Any]:
+        setattr(method,BuiltInAttr.IS_PYBOOT_BEAN_FACTORY.value,True)
+        return method
+
+class ConfigurationPlugin(PyBootPlugin):
+    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)
+
+    # A Configuration class is a class that contains bean factory methods that produce beans for the application context.Its main responsibility is to define and configure beans that can be used throughout the application.So it must not wait for the application context to be fully initialized before it can register its beans. Instead, it should register its beans during the configuration phase of the application context initialization process.
+    def on_register(self, context: PyBootContext) -> None:
+
+        for clazz in context.discovered_classes:
+
+            # skip other classes
+            if not getattr(clazz, BuiltInAttr.IS_PYBOOT_CONFIGURATION_CLASS.value, False):
+                continue
+
+            #register the class
+            context.ioc.register_class(clazz=clazz)
+
+            #immediately get the bean
+            config_bean = context.ioc.get_bean(clazz=clazz)
+
+            for method_name, method in inspect.getmembers(
+                config_bean, predicate=inspect.ismethod
+            ):
+
+                # skip other methods
+                if not getattr(
+                    method,
+                    BuiltInAttr.IS_PYBOOT_BEAN_FACTORY.value,
+                    False,
+                ):
+                    continue
+
+                # get return type of the bean factory what the factory is producing
+                return_type = get_type_hints(method).get("return")
+
+                # if the factory is producing None , then it is invalid
+                if return_type is None:
+                    raise InvalidBeanFactoryDefinitionException(
+                        f"@Bean method '{method_name}' must have a return annotation"
+                    )
+
+                # register the bean factory
+                context.ioc.register_bean_factory(clazz=return_type, method=method)
+
+    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:
+        return super().on_load(context)
+
+    def after_load(self, context: PyBootContext) -> None:
+        return super().after_load(context)
+
+
+    def on_ready(self, context: PyBootContext) -> None:
+        return super().on_ready(context)

pyboot/core/exceptions.py

@@ -0,0 +1,72 @@
+#exceptions
+class MultipleBeanException(Exception):
+    def __init__(self, message: str) -> None:
+        super()
+        self.message: str = message
+        return
+
+
+class ClassNotRegisteredForBean(Exception):
+    def __init__(self, message: str) -> None:
+        super()
+        self.message: str = message
+        return
+
+
+class DependencyResolutionException(Exception):
+    def __init__(self, message: str) -> None:
+        super()
+        self.message: str = message
+        return
+
+
+class CircularDependencyException(Exception):
+    def __init__(self, message: str) -> None:
+        super()
+        self.message: str = message
+        return
+
+
+class MethodNameExpectedToHaveMethodTypeException(Exception):
+    def __init__(self, message: str) -> None:
+        super()
+        self.message: str = message
+        return
+
+
+class NoHttpMethodDefinedForRoute(Exception):
+    def __init__(self, message: str) -> None:
+        super()
+        self.message: str = message
+        return
+
+class NoHttpRoutePathDefined(Exception):
+    def __init__(self, message: str) -> None:
+        super()
+        self.message: str = message
+        return
+
+class NoClassTypeForExceptionHandler(Exception):
+    def __init__(self, message: str) -> None:
+        super()
+        self.message: str = message
+        return
+
+
+class MultipleClassDefinitionException(Exception):
+    def __init__(self, message:str) -> None:
+        super()
+        self.message:str=message
+        return
+
+class InvalidBeanFactoryException(Exception):
+    def __init__(self, message:str) -> None:
+        super()
+        self.messae:str=message
+        return
+
+class ContextFieldNotSetException(Exception):
+    def __init__(self, message:str) -> None:
+        super()
+        self.messae:str=message
+        return

pyboot/core/ioc.py

@@ -0,0 +1,119 @@
+from .exceptions import *
+from .types import *
+
+import inspect
+from typing import get_type_hints
+
+#IOC Container
+class IocContainer:
+    """The Application Wide Inversion Of Control(IOC) container for managing beans"""
+    def __init__(self) -> None:
+        self.definitions:set[ClassTBase]=set()
+        self.singletons:dict[ClassTBase,object]=dict()
+        self.bean_factories:dict[ClassTBase,MethodTBase]=dict()
+        return
+
+    def register_class(self,clazz:ClassTBase)->None:
+        if clazz in self.definitions:
+            return
+
+        self.definitions.add(clazz)
+        return
+
+    def register_bean_factory(self,clazz:ClassTBase,method:MethodTBase)->None:
+        if clazz in self.definitions:
+            raise MultipleBeanException(f"Multiple bean definitions for {clazz.__name__}. One is already registered by some class")
+
+        if clazz in self.bean_factories:
+            raise MultipleBeanException(f"Multiple bean definitions for {clazz.__name__}")
+
+        self.bean_factories[clazz]=method
+        return
+
+    def _create_object_from_class(self,clazz:ClassTBase,constructing_object_set:set[ClassTBase]):
+        if clazz in constructing_object_set:
+            raise CircularDependencyException(f"Encountered circular dependency injection in class:{clazz.__name__}")
+
+        constructing_object_set.add(clazz)
+
+        if not "__init__" in clazz.__dict__:
+            return clazz()
+
+        signature=inspect.signature(clazz.__init__)
+        type_hints = get_type_hints(clazz.__init__)
+
+        kwargs:dict[str,object]={}
+
+        for name,parameter in signature.parameters.items():
+            if name =="self":
+                continue
+
+            if parameter.default is not inspect.Parameter.empty:
+                continue
+
+            dependency_type=type_hints.get(name)
+
+            if dependency_type is None:
+                raise DependencyResolutionException(f"Missing type annotation for parameter:{name} in class:{clazz.__name__}")
+
+            kwargs[name]=self._get_bean(clazz=dependency_type,constructing_object_set=constructing_object_set)
+
+        constructing_object_set.remove(clazz)
+
+        print(f"Creating Bean of class:{clazz.__name__} from ioc definition")
+        return clazz(**kwargs)
+
+    
+    def _create_object_from_method(self,bean_type:ClassTBase,method:MethodTBase,constructing_object_set:set[ClassTBase]):
+        if bean_type in constructing_object_set:
+            raise CircularDependencyException(f"Encountered circular dependency injection in class:{bean_type.__name__}")
+
+        constructing_object_set.add(bean_type)
+
+        signature=inspect.signature(method)
+        type_hints = get_type_hints(method)
+
+        kwargs:dict[str,object]={}
+
+        for name,parameter in signature.parameters.items():
+
+            #if it is self, skip
+            if name =="self":
+                continue
+
+            if parameter.default is not inspect.Parameter.empty:
+                continue
+
+            dependency_type=type_hints.get(name)
+
+            if dependency_type is None:
+                raise DependencyResolutionException(f"Missing type annotation for parameter:{name} in method:{method.__name__}")
+
+            kwargs[name]=self._get_bean(clazz=dependency_type,constructing_object_set=constructing_object_set)
+
+        constructing_object_set.remove(bean_type)
+        print(f"Creating bean of class:{bean_type} from method:{method.__name__}")
+        return method(**kwargs)
+
+
+    def _get_bean(self,clazz:ClassTBase,constructing_object_set:set[ClassTBase])->object:
+        if clazz in self.singletons:
+            return self.singletons[clazz]
+
+        if clazz in self.definitions:
+            self.singletons[clazz]=self._create_object_from_class(clazz=clazz,constructing_object_set=constructing_object_set)
+        elif clazz in self.bean_factories:
+            method=self.bean_factories.get(clazz)
+
+            if method is None:
+                raise DependencyResolutionException(f"Missing Factory for bean of class:{clazz.__name__} but somehow reached here!")
+
+            self.singletons[clazz]=self._create_object_from_method(bean_type=clazz,constructing_object_set=constructing_object_set,method=method)
+        else:
+            raise ClassNotRegisteredForBean(f"Class not registered for bean of instance:{clazz.__name__}")
+
+        return self.singletons[clazz]
+
+    def get_bean(self,clazz:ClassTBase)->object:
+        constructing_object_set:set[ClassTBase]=set()
+        return self._get_bean(clazz=clazz,constructing_object_set=constructing_object_set)

pyboot/core/plugin_loader.py

@@ -0,0 +1,30 @@
+from .pyboot_plugin import PyBootPlugin
+
+from importlib.metadata import entry_points
+from .types import ClassTBase
+import inspect
+
+
+class PluginLoader:
+    def __init__(self) -> None:
+        pass
+
+    def load_plugins(self)->set[PyBootPlugin]:
+        plugins:set[PyBootPlugin]=set()
+
+        for entry_point  in entry_points(group="pyboot.plugins"):
+            plugin_class=entry_point.load()
+
+            if not isinstance(plugin_class,ClassTBase):
+                raise TypeError(f"Plugin:{entry_point.name} must reference a {ClassTBase} class")
+
+            if not issubclass(plugin_class,PyBootPlugin):
+                raise TypeError(f"Plugin:{entry_point.name} must extend the {PyBootPlugin} PyBootPlugin")
+
+            if inspect.isabstract(plugin_class):
+                raise TypeError(f"Plugin:{entry_point.name} must not be an abstract class")
+
+            plugin_instance=plugin_class()
+            plugins.add(plugin_instance)
+
+        return plugins

pyboot/core/pyboot_context.py

@@ -0,0 +1,16 @@
+from .types  import *
+from .ioc import IocContainer
+from .exceptions import *
+
+from typing import Any
+
+T = TypeVar("T")
+
+#PyBoot Context Class
+class PyBootContext:
+    def __init__(self,app:Any) -> None:
+        self.discovered_classes:set[ClassTBase]=set()
+        self.ioc:IocContainer=IocContainer()
+        self.app:Any=app
+        return
+

pyboot/core/pyboot_plugin.py

@@ -0,0 +1,52 @@
+from abc import ABC,abstractmethod
+from .pyboot_context import PyBootContext
+
+class PyBootPlugin(ABC):
+
+    @abstractmethod
+    def after_plugins_discovery(self,context:PyBootContext)->None:
+        """Runs just after pyboot has discovered all the plugins"""
+        pass
+
+    @abstractmethod
+    def before_classes_discovery(self,context:PyBootContext)->None:
+        """Runs just before pyboot begins to discover classes"""
+        pass
+
+    @abstractmethod
+    def after_classes_discovery(self,context:PyBootContext)->None:
+        """Run just after pyboot has discovered all the classes"""
+        pass
+
+    @abstractmethod
+    def before_register(self,context:PyBootContext)->None:
+        """Runs before the pyboot begins the register process of plugins"""
+
+    @abstractmethod
+    def on_register(self,context:PyBootContext)->None:
+        """Runs when the pyboot has discovered the classes and is registering them via plugin system"""
+        pass
+
+    @abstractmethod
+    def after_register(self,context:PyBootContext)->None:
+        """Runs after the register process of the plugins and before the load process"""
+        pass
+
+    @abstractmethod
+    def before_load(self,context:PyBootContext)->None:
+        """Runs before the pyboot load of the plugins"""
+        pass
+
+    @abstractmethod
+    def on_load(self,context:PyBootContext)->None:
+        """Runs after the pyboot has created the beans indicated in the ioc definition system"""
+        pass
+
+    @abstractmethod
+    def after_load(self,context:PyBootContext)->None:
+        """Runs after the on_load process has finished on all the plugins"""
+
+    @abstractmethod
+    def on_ready(self,context:PyBootContext)->None:
+        """Runs at the final stage of application ready"""
+        pass

pyboot/core/types.py

@@ -0,0 +1,7 @@
+from typing import TypeVar,Callable
+
+#Class Type
+ClassTBase=type
+ClassT=TypeVar("ClassT",bound=type)
+
+MethodTBase=Callable[...,object]

pyboot_framework-0.1.0.dist-info/METADATA

@@ -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.**

pyboot_framework-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+pyboot/__init__.py,sha256=c07AfR5wiAb-_0sXKI8DYDk9tWBJsB4x_QbdfKi9rTQ,222
+pyboot/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyboot/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyboot/core/application.py,sha256=rCMLNkaAbRlEdLju6smGN_nFAQRIzLkU6KjBtvgGtNk,6913
+pyboot/core/exceptions.py,sha256=868F3DOdUIsJbn0opn-rCSgxgJzuWhScOwaJabBTIb8,1848
+pyboot/core/ioc.py,sha256=nSpJkHVT6deJxLhaQF9JWoS97wVetS6NWsC56hTsptU,4677
+pyboot/core/plugin_loader.py,sha256=oSQsVgRpJsoZOOaHZVaae017Vdio5nWRTMpkj6DWg8A,995
+pyboot/core/pyboot_context.py,sha256=9hkspedL4OTENb6YYhgqgxlylwzS7kyAGM04dgjzZLU,360
+pyboot/core/pyboot_plugin.py,sha256=3WddbMNgEKhM_PvqIKN1CHXGRj2rSzShN2Ae6dfkV9Q,1814
+pyboot/core/types.py,sha256=xUnJk7f-FtmhznnMo8GGvAKhVwejjM9NQOPsInbI0UQ,140
+pyboot/core/builtins/BuiltInAttr.py,sha256=jYuxOOf7Efe9Vm96Y4HZMtUaOMhbgZ7oSCrun4e9foE,244
+pyboot/core/builtins/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyboot/core/builtins/component.py,sha256=ZkmbKF7r30FbwWY2yaS5SbvAo82n0su-M9xAXh-ZF3s,1518
+pyboot/core/builtins/configuration.py,sha256=BjeRfoz77wGwR0jDExsJPnwA3XhEEWC_xuEYbViCkxM,3752
+pyboot/core/builtins/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyboot_framework-0.1.0.dist-info/METADATA,sha256=VPFo-IRJzXUIjkTdRnev9vR9mHl7daBKo8lYOYm3NZg,17078
+pyboot_framework-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pyboot_framework-0.1.0.dist-info/entry_points.txt,sha256=qX-VV6uSkQe9tmcpFm3idvG9qxqrcMcqKEsMfy36pdM,147
+pyboot_framework-0.1.0.dist-info/top_level.txt,sha256=0RlOji1KqNyWOq0MS6pPeyLcMXlLapCTPSKFGgYH1yw,7
+pyboot_framework-0.1.0.dist-info/RECORD,,

pyboot_framework-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_framework-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[pyboot.plugins]
+component = pyboot.core.builtins.component.ComponentPlugin
+configuration = pyboot.core.builtins.configuration.ConfigurationPlugin

pyboot_framework-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyboot