Picobox Dependency Injection

Warnings

• breaking The `picobox.contrib` package was renamed to `picobox.ext` in version 4.0.0. Any imports or references to `picobox.contrib` will now fail.
  Fix: Update all imports from `picobox.contrib` to `picobox.ext` (e.g., `from picobox.contrib.flaskscopes` becomes `from picobox.ext.flaskscopes`).
• breaking Picobox 4.0.0 dropped support for Python 3.7. Picobox 3.0.0 dropped support for Python 2.7, 3.4, 3.5, and 3.6. Ensure your Python environment meets the `requires_python>=3.8` specification.
  Fix: Upgrade your Python interpreter to version 3.8 or newer.
• breaking In version 2.0.0, `picobox.push()` was changed to push a box onto the stack immediately when called as a function, rather than waiting for the `__enter__()` method if used as a context manager. This can alter the timing of when a box becomes active.
  Fix: Review existing code using `picobox.push()` to understand if its new immediate behavior impacts dependency resolution. If relying on context manager semantics, ensure the `with` statement correctly defines the scope.
• gotcha Picobox scopes (`singleton`, `threadlocal`, `contextvars`, `factory`) determine the lifespan and sharing of injected dependencies. Misunderstanding or misapplying scopes can lead to unexpected state sharing or excessive object creation. For example, `contextvars` is critical for asyncio applications.
  Fix: Carefully choose the appropriate scope for each dependency based on its intended lifecycle. Use `picobox.singleton` for global instances, `picobox.threadlocal` for thread-specific instances, and `picobox.contextvars` for async task-specific instances (Python 3.7+).
• gotcha The `@picobox.pass_()` decorator internally modifies the function signature. While fixed in 4.0.0 to prevent shadowing return types, on older versions or if not configured carefully, it could interfere with LSP servers or static analysis tools that rely on precise type hints.
  Fix: Upgrade to Picobox 4.0.0 or later to benefit from the fix. Always verify that type hints are correctly interpreted by your development tools after applying the decorator.

Install

• pip install picobox Install latest version

Imports

• picobox

  import picobox

• Box

  from picobox import Box

• push

  from picobox import push

• pass_

  from picobox import pass_

• singleton

  from picobox import singleton

• threadlocal

  from picobox import threadlocal

• contextvars
  wrong:

  from picobox.contrib import flaskscopes

  correct:

  from picobox import contextvars

  In Picobox 4.0.0, the `picobox.contrib` package was renamed to `picobox.ext`. Old imports like `from picobox.contrib import flaskscopes` will break.

Quickstart

This quickstart demonstrates defining a `Box`, adding both value and factory dependencies with scoping, and then using the `@picobox.pass_` decorator to inject these dependencies into a function. The `picobox.push()` function is used as a context manager to activate the box for the current scope.

import picobox

class MyService:
    def __init__(self, config_value: int):
        self.config_value = config_value

    def do_work(self) -> str:
        return f"Working with config: {self.config_value}"

# 1. Create a Box instance
box = picobox.Box()

# 2. Put dependencies into the box
# 'my_config' is a simple value
box.put('my_config', 123)

# 'my_service' is a factory, instantiated once per injection or scope
box.put('my_service', factory=MyService, scope=picobox.singleton, depends=['my_config'])

# 3. Use picobox.push to make the box active (often as a context manager)
with picobox.push(box):
    # 4. Define a function that needs dependencies, using @picobox.pass_
    @picobox.pass_('my_service')
    @picobox.pass_('my_config', as_='cfg_val')
    def run_application(my_service: MyService, cfg_val: int):
        print(f"Retrieved config value: {cfg_val}")
        print(my_service.do_work())

    run_application()