pico-boot 0.1.0.post0__py3-none-any.whl

pico_boot/__init__.py

@@ -0,0 +1,121 @@
+import inspect
+import os
+from importlib import import_module
+from importlib.metadata import entry_points
+from types import ModuleType
+from typing import Any, Iterable, List, TYPE_CHECKING, Union
+
+KeyT = Union[str, type]
+
+if TYPE_CHECKING:
+    from typing import Dict, Optional, Tuple
+    from pico_ioc import PicoContainer, ContextConfig
+    from pico_ioc import init as init, ContainerObserver
+else:
+    from typing import Dict, Optional, Tuple
+    import logging
+    from pico_ioc import PicoContainer, ContextConfig
+    from pico_ioc import init as _ioc_init, ContainerObserver
+
+    logger = logging.getLogger(__name__)
+
+    def _to_module_list(modules: Union[Any, Iterable[Any]]) -> List[Any]:
+        if isinstance(modules, Iterable) and not isinstance(modules, (str, bytes)):
+            return list(modules)
+        return [modules]
+
+    def _import_module_like(obj: Any) -> ModuleType:
+        if isinstance(obj, ModuleType):
+            return obj
+        if isinstance(obj, str):
+            return import_module(obj)
+        module_name = getattr(obj, "__module__", None) or getattr(obj, "__name__", None)
+        if not module_name:
+            raise ImportError(f"Cannot determine module for object {obj!r}")
+        return import_module(module_name)
+
+    def _normalize_modules(raw: Iterable[Any]) -> List[ModuleType]:
+        seen: set[str] = set()
+        result: List[ModuleType] = []
+        for item in raw:
+            m = _import_module_like(item)
+            name = m.__name__
+            if name not in seen:
+                seen.add(name)
+                result.append(m)
+        return result
+
+    def _harvest_scanners(modules: List[ModuleType]) -> list:
+        scanners: list = []
+        for m in modules:
+            module_scanners = getattr(m, "PICO_SCANNERS", None)
+            if module_scanners:
+                scanners.extend(module_scanners)
+        return scanners
+
+    def _load_plugin_modules(group: str = "pico_boot.modules") -> List[ModuleType]:
+        eps = entry_points()
+        if hasattr(eps, "select"):
+            selected = eps.select(group=group)
+        else:  # legacy API
+            selected = [ep for ep in eps if ep.group == group]
+
+        seen: set[str] = set()
+        modules: List[ModuleType] = []
+
+        for ep in selected:
+            try:
+                if ep.module in ("pico_ioc", "pico_boot"):
+                    continue
+                m = import_module(ep.module)
+            except Exception as exc:
+                logger.warning(
+                    "Failed to load pico-boot plugin entry point '%s' (%s): %s",
+                    ep.name,
+                    ep.module,
+                    exc,
+                )
+                continue
+
+            name = m.__name__
+            if name not in seen:
+                seen.add(name)
+                modules.append(m)
+
+        return modules
+
+    _IOC_INIT_SIG = inspect.signature(_ioc_init)
+
+    def init(*args: Any, **kwargs: Any) -> PicoContainer:
+        bound = _IOC_INIT_SIG.bind(*args, **kwargs)
+        bound.apply_defaults()
+
+        base_modules = _normalize_modules(_to_module_list(bound.arguments["modules"]))
+
+        auto_flag = os.getenv("PICO_BOOT_AUTO_PLUGINS", "true").lower()
+        auto_plugins = auto_flag not in ("0", "false", "no")
+
+        if auto_plugins:
+            plugin_modules = _load_plugin_modules()
+            all_modules = _normalize_modules(list(base_modules) + plugin_modules)
+        else:
+            all_modules = base_modules
+
+        bound.arguments["modules"] = all_modules
+
+        harvested = _harvest_scanners(all_modules)
+        if harvested:
+            existing = bound.arguments.get("custom_scanners") or []
+            bound.arguments["custom_scanners"] = list(existing) + harvested
+
+        return _ioc_init(*bound.args, **bound.kwargs)
+
+    init.__signature__ = _IOC_INIT_SIG
+
+__all__ = [
+    "init",
+    "PicoContainer",
+    "ContextConfig",
+    "ContainerObserver",
+]
+

pico_boot/_version.py

@@ -0,0 +1 @@
+__version__ = '0.1.0.post0'

pico_boot-0.1.0.post0.dist-info/METADATA

@@ -0,0 +1,387 @@
+Metadata-Version: 2.4
+Name: pico-boot
+Version: 0.1.0.post0
+Summary: Pico-IOC integration layer for ecosystem modules. Auto-discovers DI modules via entry points.
+Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 David Perez
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/dperezcabrera/pico-boot
+Project-URL: Repository, https://github.com/dperezcabrera/pico-boot
+Project-URL: Issue Tracker, https://github.com/dperezcabrera/pico-boot/issues
+Keywords: ioc,di,dependency injection,boot,inversion of control,asyncio,plugins,bootstrap
+Classifier: Development Status :: 4 - Beta
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pico-ioc>=2.2.0
+Provides-Extra: async
+Requires-Dist: asyncpg>=0.29.0; extra == "async"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23.5; extra == "test"
+Requires-Dist: pytest-cov>=5; extra == "test"
+Dynamic: license-file
+
+# Pico-Boot
+
+[![PyPI](https://img.shields.io/pypi/v/pico-boot.svg)](https://pypi.org/project/pico-boot/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+![CI (tox matrix)](https://github.com/dperezcabrera/pico-boot/actions/workflows/ci.yml/badge.svg)
+[![codecov](https://codecov.io/gh/dperezcabrera/pico-boot/branch/main/graph/badge.svg)](https://codecov.io/gh/dperezcabrera/pico-boot)
+[![Docs](https://img.shields.io/badge/Docs-pico--stack-blue?style=flat&logo=readthedocs&logoColor=white)](https://dperezcabrera.github.io/pico-boot/)
+
+**Zero-configuration bootstrap for the Pico ecosystem.**
+
+Pico-Boot is a thin orchestration layer over [pico-ioc](https://github.com/dperezcabrera/pico-ioc) that provides:
+
+- **Auto-discovery of plugins** via Python entry points
+- **Custom scanner harvesting** from loaded modules
+
+> 🐍 Requires Python 3.11+
+
+---
+
+## When to Use Pico-Boot vs Pico-IoC
+
+| Use Case | Recommendation |
+|----------|----------------|
+| Simple app, manual control | Use `pico-ioc` directly |
+| Multiple pico-* integrations (fastapi, sqlalchemy, celery) | Use `pico-boot` |
+| Want zero-config plugin discovery | Use `pico-boot` |
+
+---
+
+## Installation
+
+```bash
+pip install pico-boot
+```
+
+This automatically installs `pico-ioc` as a dependency.
+
+---
+
+## Quick Start
+
+### Basic Usage
+
+```python
+# app.py
+from pico_ioc import component, provides
+from pico_boot import init
+
+@component
+class Database:
+    def query(self) -> str:
+        return "data"
+
+@component
+class UserService:
+    def __init__(self, db: Database):
+        self.db = db
+
+# pico-boot's init() replaces pico-ioc's init()
+# It auto-discovers plugins and harvests custom scanners
+container = init(modules=[__name__])
+
+service = container.get(UserService)
+print(service.db.query())
+```
+
+---
+
+## Features
+
+### 1. Plugin Auto-Discovery
+
+When you install a pico-* integration package, it automatically registers itself:
+
+```bash
+pip install pico-fastapi pico-sqlalchemy pico-celery
+```
+
+```python
+from pico_boot import init
+
+# All installed pico-* plugins are automatically loaded!
+container = init(modules=["myapp"])
+```
+
+No need to explicitly import or configure each integration.
+
+### 2. Custom Scanner Harvesting
+
+Modules can expose custom component scanners via `PICO_SCANNERS`:
+
+```python
+# my_plugin/__init__.py
+from pico_ioc import CustomScanner
+
+class MyScanner(CustomScanner):
+    def scan(self, module):
+        # Custom component discovery logic
+        pass
+
+PICO_SCANNERS = [MyScanner()]
+```
+
+Pico-Boot automatically collects and applies these scanners.
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PICO_BOOT_AUTO_PLUGINS` | `true` | Enable/disable plugin auto-discovery |
+
+### Disabling Auto-Discovery
+
+```bash
+export PICO_BOOT_AUTO_PLUGINS=false
+```
+
+Useful for testing or when you want explicit control.
+
+---
+
+## Creating a Pico-Boot Plugin
+
+To make your library discoverable by pico-boot, add an entry point in `pyproject.toml`:
+
+```toml
+[project.entry-points."pico_boot.modules"]
+my_library = "my_library"
+```
+
+### Example: Creating a Redis Integration
+
+```python
+# pico_redis/__init__.py
+import redis
+from pico_ioc import provides, configured
+from dataclasses import dataclass
+
+@configured(prefix="redis")
+@dataclass
+class RedisConfig:
+    url: str = "redis://localhost:6379/0"
+
+@provides(redis.Redis)
+def build_redis(config: RedisConfig) -> redis.Redis:
+    return redis.Redis.from_url(config.url)
+```
+
+```toml
+# pyproject.toml
+[project.entry-points."pico_boot.modules"]
+pico_redis = "pico_redis"
+```
+
+Now any app using pico-boot will automatically have Redis available!
+
+For a complete guide, see the [Creating Plugins](https://dperezcabrera.github.io/pico-boot/creating-plugins/) documentation.
+
+---
+
+## Complete Example
+
+### Project Structure
+
+```
+myapp/
+├── application.yaml
+├── main.py
+├── config.py
+├── services.py
+└── repositories.py
+```
+
+### application.yaml
+
+```yaml
+database:
+  url: postgresql://localhost/myapp
+
+redis:
+  url: redis://localhost:6379/0
+
+app:
+  name: My Application
+  debug: false
+```
+
+### config.py
+
+```python
+from dataclasses import dataclass
+from pico_ioc import configured
+
+@configured(prefix="database")
+@dataclass
+class DatabaseConfig:
+    url: str
+
+@configured(prefix="redis")
+@dataclass
+class RedisConfig:
+    url: str
+
+@configured(prefix="app")
+@dataclass
+class AppConfig:
+    name: str
+    debug: bool = False
+```
+
+### services.py
+
+```python
+from pico_ioc import component
+from .config import AppConfig
+
+@component
+class GreetingService:
+    def __init__(self, config: AppConfig):
+        self.app_name = config.name
+
+    def greet(self, user: str) -> str:
+        return f"Welcome to {self.app_name}, {user}!"
+```
+
+### main.py
+
+```python
+from pico_ioc import configuration, YamlSource, EnvSource
+from pico_boot import init
+from .services import GreetingService
+
+def main():
+    # Load configuration via pico-ioc, let pico-boot discover plugins
+    config = configuration(
+        YamlSource("application.yaml"),
+        EnvSource()
+    )
+    container = init(modules=["myapp.config", "myapp.services"], config=config)
+
+    service = container.get(GreetingService)
+    print(service.greet("Alice"))
+
+    container.shutdown()
+
+if __name__ == "__main__":
+    main()
+```
+
+### Running
+
+```bash
+$ python -m myapp.main
+Welcome to My Application, Alice!
+```
+
+### Override with Environment Variables
+
+```bash
+$ APP_NAME="Production App" python -m myapp.main
+Welcome to Production App, Alice!
+```
+
+---
+
+## API Reference
+
+### `init(*args, **kwargs) -> PicoContainer`
+
+Drop-in replacement for `pico_ioc.init()` with additional features:
+
+- Auto-discovers plugins from `pico_boot.modules` entry points
+- Harvests custom scanners (`PICO_SCANNERS`) from loaded modules
+
+All parameters from `pico_ioc.init()` are supported:
+
+```python
+container = init(
+    modules=["myapp"],           # Modules to scan
+    config=my_config,            # Optional: custom ContextConfig
+    profiles=["prod"],           # Optional: active profiles
+    overrides={Service: Mock()}, # Optional: test overrides
+    observers=[MyObserver()],    # Optional: container observers
+    custom_scanners=[],          # Optional: additional scanners
+)
+```
+
+---
+
+## Documentation
+
+Full documentation is available at [dperezcabrera.github.io/pico-boot](https://dperezcabrera.github.io/pico-boot/).
+
+- [Getting Started](https://dperezcabrera.github.io/pico-boot/getting-started/)
+- [Configuration](https://dperezcabrera.github.io/pico-boot/configuration/)
+- [Creating Plugins](https://dperezcabrera.github.io/pico-boot/creating-plugins/)
+- [API Reference](https://dperezcabrera.github.io/pico-boot/api-reference/)
+- [Ecosystem](https://dperezcabrera.github.io/pico-boot/ecosystem/)
+
+---
+
+## Ecosystem
+
+Pico-Boot works with these integration packages:
+
+| Package | Description |
+|---------|-------------|
+| [pico-ioc](https://github.com/dperezcabrera/pico-ioc) | Core DI container |
+| [pico-fastapi](https://github.com/dperezcabrera/pico-fastapi) | FastAPI integration |
+| [pico-sqlalchemy](https://github.com/dperezcabrera/pico-sqlalchemy) | SQLAlchemy integration |
+| [pico-celery](https://github.com/dperezcabrera/pico-celery) | Celery integration |
+| [pico-pydantic](https://github.com/dperezcabrera/pico-pydantic) | Pydantic validation |
+
+---
+
+## Development
+
+```bash
+# Run tests
+pip install tox
+tox
+
+# Build documentation locally
+pip install -r docs/requirements.txt
+mkdocs serve
+```
+
+---
+
+## License
+
+MIT - [LICENSE](./LICENSE)

pico_boot-0.1.0.post0.dist-info/RECORD

@@ -0,0 +1,7 @@
+pico_boot/__init__.py,sha256=kiTzllt7y4VcLwTB-xo8VNvwoEkVvSHeM4A_jy-I0RA,3957
+pico_boot/_version.py,sha256=0iP1THdPq83rbUsMGDOrAIfUyC5BhxyeOWsGdqdnFSY,28
+pico_boot-0.1.0.post0.dist-info/licenses/LICENSE,sha256=j86ePhARUMlHapXj0uGGdmnRTholb6VMoORCv8jkGdU,1068
+pico_boot-0.1.0.post0.dist-info/METADATA,sha256=kr6Kf_u8a_1gCmH9k5_48_sfPuJy0GlnJ6BVUicfNWQ,10238
+pico_boot-0.1.0.post0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+pico_boot-0.1.0.post0.dist-info/top_level.txt,sha256=XKFMUvxblFAJ8HJIToiDbAt5wyzp1xIRcTz0__-0gMo,10
+pico_boot-0.1.0.post0.dist-info/RECORD,,

pico_boot-0.1.0.post0.dist-info/WHEEL

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

pico_boot-0.1.0.post0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Perez
+
+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.

pico_boot-0.1.0.post0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pico_boot