Pico-Boot

Zero-configuration bootstrap for the Pico ecosystem.

Pico-Boot is a thin orchestration layer over pico-ioc that provides:

• Auto-discovery of plugins via Python entry points
• Custom scanner harvesting from loaded modules

Requires Python 3.11+ (tested on 3.11, 3.12, 3.13 and 3.14)

When to Use Pico-Boot vs Pico-IoC

Installation

pip install pico-boot

This automatically installs pico-ioc as a dependency.

Quick Start

Basic Usage

# 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:

pip install pico-fastapi pico-sqlalchemy pico-celery

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:

# 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

Disabling Auto-Discovery

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:

[project.entry-points."pico_boot.modules"]
my_library = "my_library"

Example: Creating a Redis Integration

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

# 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 documentation.

Complete Example

Project Structure

myapp/
├── application.yaml
├── main.py
├── config.py
├── services.py
└── repositories.py

application.yaml

database:
  url: postgresql://localhost/myapp

redis:
  url: redis://localhost:6379/0

app:
  name: My Application
  debug: false

config.py

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

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

from pico_ioc import configuration, YamlTreeSource, EnvSource
from pico_boot import init
from .services import GreetingService

def main():
    # Load configuration via pico-ioc, let pico-boot discover plugins
    config = configuration(
        YamlTreeSource("application.yaml"),
        EnvSource()
    )
    container = init(modules=["myapp"], config=config)

    service = container.get(GreetingService)
    print(service.greet("Alice"))

    container.shutdown()

if __name__ == "__main__":
    main()

Running

$ python -m myapp.main
Welcome to My Application, Alice!

Override with Environment Variables

$ 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:

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.

• Getting Started
• Configuration
• Creating Plugins
• API Reference
• Ecosystem

Ecosystem

Pico-Boot works with these integration packages:

Development

# Run tests
pip install tox
tox

# Build documentation locally
pip install -r docs/requirements.txt
mkdocs serve

Built for AI-assisted development

pico-boot is where the whole ecosystem composes, and the composition itself is agent-friendly: plugins auto-register through entry points, applications declare what they use, and everything an agent adds lands inside one explicit architecture instead of a parallel style.

What keeps agent-written code on-architecture:

• pico-testing is the agent's feedback loop. Auto-discovery is disabled in tests by default (a suite never depends on what happens to be installed), and make_container/make_client boot exactly the modules a test names. boot=True exercises the real pico-boot path when discovery itself is under test.
• pico-initializer scaffolds pico-boot applications with the canonical layout and selected integrations.
• pico-examples shows the packages composed in practice, from hermetic suites to Docker Compose and Kubernetes deployments with real smoke tests.
• pico-learn turns the patterns into executable lessons, validated in CI against the pinned published wheels.
• pico-skills gives coding agents task-specific instructions (/add-app, /add-component, /add-tests).

Every package ships AGENTS.md conventions, llms.txt machine-readable doc indexes, architecture decisions in docs/, and regression tests pinning documented behaviour. Releases are gated by a flagship application booting the entire ecosystem against real infrastructure before anything reaches PyPI.

Install the agent skills for Claude Code or OpenAI Codex:

curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/install.sh | bash -s -- boot

All skills: curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/install.sh | bash - see pico-skills.

License

MIT - LICENSE