pico-boot 0.1.0.post0__tar.gz

pico_boot-0.1.0.post0/.coveragerc

@@ -0,0 +1,17 @@
+[run]
+branch = True
+source =
+    pico_boot
+omit =
+    */_version.py
+
+[paths]
+pico_boot =
+    src/pico_boot
+    .tox/*/lib/*/site-packages/pico_boot
+    .tox/*/site-packages/pico_boot
+    */site-packages/pico_boot
+
+[report]
+show_missing = True
+

pico_boot-0.1.0.post0/.github/workflows/ci.yml

@@ -0,0 +1,101 @@
+name: CI & Coverage
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  tests:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ "3.11", "3.12", "3.13", "3.14" ]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install tox
+        run: |
+          python -m pip install --upgrade pip
+          pip install tox
+
+      - name: Run tests with coverage (writes to repo root)
+        shell: bash
+        run: |
+          set -euxo pipefail
+          tox -e cov
+          # Rename to per-version file for artifact + merge job
+          mv .coverage .coverage.${{ matrix.python-version }}
+          ls -la .coverage.${{ matrix.python-version }}
+
+      - name: Upload .coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: .coverage.${{ matrix.python-version }}
+          include-hidden-files: true
+          if-no-files-found: error
+
+  coverage-merge:
+    name: Merge coverage
+    runs-on: ubuntu-latest
+    needs: tests
+    steps:
+      - name: Checkout (for repo context)
+        uses: actions/checkout@v4
+
+      - name: Download all coverage artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: coverage-reports
+
+      - name: Combine coverage and generate reports
+        shell: bash
+        run: |
+          set -euxo pipefail
+          python -m pip install coverage
+          files=$(find coverage-reports -type f -name ".coverage.*" -print)
+          if [ -z "$files" ]; then
+            echo "No coverage data files found"; exit 1
+          fi
+          coverage combine $files
+          coverage report -m --rcfile=.coveragerc
+          coverage xml -o coverage.xml --rcfile=.coveragerc
+          coverage html -d htmlcov --rcfile=.coveragerc
+
+      - name: Upload combined coverage XML
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-xml
+          path: coverage.xml
+          if-no-files-found: error
+
+      - name: Upload HTML coverage report
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-html
+          path: htmlcov
+          if-no-files-found: error
+
+      - name: Upload to Codecov
+        if: always() && !cancelled()
+        uses: codecov/codecov-action@v5
+        continue-on-error: true
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: dperezcabrera/pico-boot

pico_boot-0.1.0.post0/.github/workflows/docs.yml

@@ -0,0 +1,104 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [ main, master ]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    branches: [ main, master ]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+  workflow_dispatch:
+
+permissions:
+  actions: read
+  contents: write
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -r docs/requirements.txt
+
+      - name: Validate documentation build
+        run: mkdocs build --strict
+
+      - name: Check for broken links (best-effort)
+        run: |
+          pip install linkchecker
+          python -m http.server --directory site 8000 &
+          sleep 3
+          linkchecker http://127.0.0.1:8000 --check-extern || true
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -r docs/requirements.txt
+
+      - name: Build documentation
+        run: |
+          mkdocs build --strict --verbose
+          echo "Built on $(date -u)" > site/build-info.txt
+          echo "Commit: ${{ github.sha }}" >> site/build-info.txt
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: './site'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+      - name: Comment on commit (optional)
+        if: success()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.repos.createCommitComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              commit_sha: context.sha,
+              body: `✅ Documentation deployed successfully!\n\n📚 View at: ${'${{ steps.deployment.outputs.page_url }}'}`
+            })
+

pico_boot-0.1.0.post0/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,35 @@
+name: Publish Python Package to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+
+    - name: Install build deps
+      run: python -m pip install --upgrade pip build
+
+    - name: Build package
+      run: python -m build
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        skip-existing: true
+        verify-metadata: true
+        attestations: false

pico_boot-0.1.0.post0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] - 2025-02-04
+
+### Added
+- Initial release of Pico-Boot
+- Plugin auto-discovery via `pico_boot.modules` entry points
+- Automatic configuration file loading (YAML/JSON)
+- Environment variable configuration support
+- Custom scanner harvesting from modules
+- `PICO_BOOT_AUTO_PLUGINS` environment variable to control auto-discovery
+- `PICO_BOOT_CONFIG_FILE` environment variable for custom config path
+- Full documentation with MkDocs Material
+- GitHub Actions workflows (CI, docs, PyPI publish)
+
+### Compatibility
+- Python 3.11 - 3.14
+- pico-ioc >= 2.1.3
+
+[0.1.0]: https://github.com/dperezcabrera/pico-boot/releases/tag/v0.1.0

pico_boot-0.1.0.post0/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/MANIFEST.in

@@ -0,0 +1,18 @@
+include README.md
+include LICENSE
+
+recursive-include src *.py
+
+recursive-include tests *.py
+
+exclude .gitignore
+exclude Dockerfile*
+exclude docker-compose*.yml
+exclude Makefile
+
+prune build
+prune dist
+prune .tox
+prune .pytest_cache
+prune __pycache__
+

pico_boot-0.1.0.post0/PKG-INFO

@@ -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)