pico-ioc 0.1.0__tar.gz

pico_ioc-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI (tox matrix)
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13']
+    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 tox for this Python
+        run: tox -e py${{ matrix.python-version && join(matrix.python-version, '') }}
+

pico_ioc-0.1.0/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,32 @@
+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
+

pico_ioc-0.1.0/Dockerfile.test

@@ -0,0 +1,9 @@
+ARG PYTHON_VERSION=3.11
+FROM python:${PYTHON_VERSION}-slim
+
+WORKDIR /app
+COPY . .
+RUN python -m pip install --upgrade pip tox
+
+CMD bash -lc 'ENV=py$(python -c "import sys;print(f\"{sys.version_info.major}{sys.version_info.minor}\")"); tox -e $ENV'
+

pico_ioc-0.1.0/Makefile

@@ -0,0 +1,14 @@
+.PHONY: $(VERSIONS) build-% test-% test-all
+
+VERSIONS = 3.8 3.9 3.10 3.11 3.12 3.13
+
+build-%:
+	docker build --pull --build-arg PYTHON_VERSION=$* \
+		-t pico-ioc-test:$* -f Dockerfile.test .
+
+test-%: build-%
+	docker run --rm pico-ioc-test:$*
+
+test-all: $(addprefix test-, $(VERSIONS))
+	@echo "✅ All versions done"
+

pico_ioc-0.1.0/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: pico-ioc
+Version: 0.1.0
+Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
+Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
+Project-URL: Homepage, https://github.com/dperezcabrera/pico-ioc
+Project-URL: Repository, https://github.com/dperezcabrera/pico-ioc
+Project-URL: Issue Tracker, https://github.com/dperezcabrera/pico-ioc/issues
+Keywords: ioc,di,dependency injection,inversion of control,decorator
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown

pico_ioc-0.1.0/README.MD

@@ -0,0 +1,202 @@
+# Pico-IoC: A Minimalist IoC Container for Python
+
+[![PyPI](https://img.shields.io/pypi/v/pico-ioc.svg)](https://pypi.org/project/pico-ioc/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+![CI (tox matrix)](https://github.com/dperezcabrera/pico-ioc/actions/workflows/ci.yml/badge.svg)
+
+**Pico-IoC** is a tiny, zero-dependency, decorator-based Inversion of Control (IoC) container for Python.  
+It helps you manage dependencies in a clean, intuitive, and *Pythonic* way.
+
+The core idea is to let you build loosely coupled, easily testable applications without manually wiring components.  
+*Inspired by the IoC philosophy popularized by the Spring Framework.*
+
+---
+
+## Key Features
+
+* ✨ **Zero Dependencies:** Pure Python, no external libraries.
+* 🚀 **Decorator-Based API:** Simple decorators like `@component` and `@provides`.
+* 🔍 **Automatic Discovery:** Scans your package to auto-register components.
+* 🧩 **Lazy Instantiation:** Objects are created on first use.
+* 🏭 **Flexible Factories:** Encapsulate complex creation logic.
+* 🤝 **Framework-Agnostic:** Works with Flask, FastAPI, CLIs, scripts, etc.
+
+---
+
+## Installation
+
+```bash
+pip install pico-ioc
+```
+
+---
+
+## Quick Start
+
+Getting started is simple. Decorate your classes and let Pico-IoC wire them up.
+
+```python
+from pico_ioc import component, init
+
+@component
+class AppConfig:
+    def get_db_url(self):
+        return "postgresql://user:pass@host/db"
+
+@component
+class DatabaseService:
+    def __init__(self, config: AppConfig):
+        self._cs = config.get_db_url()
+
+    def get_data(self):
+        return f"Data from {self._cs}"
+
+# Initialize the container scanning the current module
+container = init(__name__)
+
+db = container.get(DatabaseService)
+print(db.get_data())  # Data from postgresql://user:pass@host/db
+```
+
+---
+
+## More Examples
+
+### 🧩 Custom Component Name
+
+```python
+from pico_ioc import component, init
+
+@component(name="config")
+class AppConfig:
+    def __init__(self):
+        self.db_url = "postgresql://user:pass@localhost/db"
+
+@component
+class Repository:
+    def __init__(self, config: "config"):  # refer by custom name if you prefer
+        self._url = config.db_url
+
+container = init(__name__)
+repo = container.get(Repository)
+print(repo._url)           # postgresql://user:pass@localhost/db
+print(container.get("config").db_url)
+```
+
+> Pico-IoC prefers **type annotations** to resolve deps; if missing, it falls back to the **parameter name**.
+
+### 💤 Lazy Factories (only build when used)
+
+```python
+from pico_ioc import factory_component, provides, init
+
+CREATION_COUNTER = {"value": 0}
+
+@factory_component
+class ServicesFactory:
+    @provides(name="heavy_service")  # returns a LazyProxy by default
+    def make_heavy(self):
+        CREATION_COUNTER["value"] += 1
+        return {"payload": "Hello from heavy service"}
+
+container = init(__name__)
+svc = container.get("heavy_service")
+print(CREATION_COUNTER["value"])  # 0 (not created yet)
+
+print(svc["payload"])             # triggers creation
+print(CREATION_COUNTER["value"])  # 1
+```
+
+### 📦 Project-Style Package Scanning
+
+```
+project_root/
+└── myapp/
+    ├── __init__.py
+    ├── services.py
+    └── main.py
+```
+
+**myapp/services.py**
+
+```python
+from pico_ioc import component
+
+@component
+class Config:
+    def __init__(self):
+        self.base_url = "https://api.example.com"
+
+@component
+class ApiClient:
+    def __init__(self, config: Config):
+        self.base_url = config.base_url
+
+    def get(self, path: str):
+        return f"GET {self.base_url}/{path}"
+```
+
+**myapp/main.py**
+
+```python
+import pico_ioc
+from myapp.services import ApiClient
+
+# Scan the whole 'myapp' package
+container = pico_ioc.init("myapp")
+
+client = container.get(ApiClient)
+print(client.get("status"))  # GET https://api.example.com/status
+```
+
+---
+
+## API Reference (mini)
+
+### `init(root_package_or_module) -> PicoContainer`
+
+Initialize the container by scanning a root **package** (str) or **module**. Returns the configured container.
+
+### `@component(cls=None, *, name: str | None = None)`
+
+Mark a class as a component. Registered by **class type** by default, or by **name** if provided.
+
+### `@factory_component`
+
+Mark a class as a factory holder. Methods inside can be `@provides(...)`.
+
+### `@provides(name: str, lazy: bool = True)`
+
+Declare that a factory method **produces** a component registered under `name`. By default it’s **lazy** (a proxy that creates on first real use).
+
+---
+
+## Testing
+
+`pico-ioc` ships with `pytest` tests and a `tox` matrix.
+
+```bash
+pip install tox
+tox -e py311           # run on a specific version
+tox                    # run all configured envs
+```
+
+---
+
+## Contributing
+
+Issues and PRs are welcome. If you spot a bug or have an idea, open an issue!
+
+---
+
+## License
+
+MIT — see the [LICENSE](https://opensource.org/licenses/MIT).
+
+---
+
+## Authors
+
+* **David Perez Cabrera**
+* **Gemini 2.5-Pro**
+* **GPT-5**

pico_ioc-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=69.0", "wheel", "setuptools-scm>=8.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pico-ioc"
+dynamic = ["version"]
+authors = [{ name = "David Perez Cabrera", email = "dperezcabrera@gmail.com" }]
+description = "A minimalist, zero-dependency Inversion of Control (IoC) container for Python."
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.8"
+license = { file = "LICENSE" }
+keywords = ["ioc", "di", "dependency injection", "inversion of control", "decorator"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/dperezcabrera/pico-ioc"
+Repository = "https://github.com/dperezcabrera/pico-ioc"
+"Issue Tracker" = "https://github.com/dperezcabrera/pico-ioc/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["pico_ioc*"]
+
+[tool.setuptools_scm]
+version_scheme = "post-release"
+local_scheme = "no-local-version"
+fallback_version = "0.0.0"
+write_to = "src/pico_ioc/_version.py"
+write_to_template = "__version__ = '{version}'\n"
+

pico_ioc-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pico_ioc-0.1.0/src/pico_ioc/__init__.py

@@ -0,0 +1,213 @@
+# src/pico_ioc/__init__.py
+
+import functools, inspect, pkgutil, importlib, logging, sys
+from typing import Callable, Any, Iterator, AsyncIterator
+
+try:
+    # written at build time by setuptools-scm
+    from ._version import __version__
+except Exception:  # pragma: no cover
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]
+
+# ==============================================================================
+# --- 1. Container and Chameleon Proxy (Framework-Agnostic) ---
+# ==============================================================================
+class PicoContainer:
+    def __init__(self):
+        self._providers = {}
+        self._singletons = {}
+
+    def bind(self, key: Any, provider: Callable[[], Any]):
+        self._providers[key] = provider
+
+    def get(self, key: Any) -> Any:
+        if key in self._singletons:
+            return self._singletons[key]
+        if key in self._providers:
+            instance = self._providers[key]()
+            self._singletons[key] = instance
+            return instance
+        raise NameError(f"No provider found for key: {key}")
+
+class LazyProxy:
+    """
+    A full-fledged lazy proxy that delegates almost all operations
+    to the real object, which is created only on first access.
+    It is completely framework-agnostic.
+    """
+    def __init__(self, object_creator: Callable[[], Any]):
+        object.__setattr__(self, "_object_creator", object_creator)
+        object.__setattr__(self, "__real_object", None)
+
+    def _get_real_object(self) -> Any:
+        real_obj = object.__getattribute__(self, "__real_object")
+        if real_obj is None:
+            real_obj = object.__getattribute__(self, "_object_creator")()
+            object.__setattr__(self, "__real_object", real_obj)
+        return real_obj
+
+    # --- Core Proxying and Representation ---
+    @property
+    def __class__(self):
+        return self._get_real_object().__class__
+
+    def __getattr__(self, name):
+        return getattr(self._get_real_object(), name)
+        
+    def __setattr__(self, name, value):
+        setattr(self._get_real_object(), name, value)
+
+    def __delattr__(self, name):
+        delattr(self._get_real_object(), name)
+
+    def __str__(self):
+        return str(self._get_real_object())
+
+    def __repr__(self):
+        return repr(self._get_real_object())
+        
+    def __dir__(self):
+        return dir(self._get_real_object())
+
+    # --- Emulation of container types ---
+    def __len__(self): return len(self._get_real_object())
+    def __getitem__(self, key): return self._get_real_object()[key]
+    def __setitem__(self, key, value): self._get_real_object()[key] = value
+    def __delitem__(self, key): del self._get_real_object()[key]
+    def __iter__(self): return iter(self._get_real_object())
+    def __reversed__(self): return reversed(self._get_real_object())
+    def __contains__(self, item): return item in self._get_real_object()
+
+    # --- Emulation of numeric types and operators ---
+    def __add__(self, other): return self._get_real_object() + other
+    def __sub__(self, other): return self._get_real_object() - other
+    def __mul__(self, other): return self._get_real_object() * other
+    def __matmul__(self, other): return self._get_real_object() @ other
+    def __truediv__(self, other): return self._get_real_object() / other
+    def __floordiv__(self, other): return self._get_real_object() // other
+    def __mod__(self, other): return self._get_real_object() % other
+    def __divmod__(self, other): return divmod(self._get_real_object(), other)
+    def __pow__(self, other, modulo=None): return pow(self._get_real_object(), other, modulo)
+    def __lshift__(self, other): return self._get_real_object() << other
+    def __rshift__(self, other): return self._get_real_object() >> other
+    def __and__(self, other): return self._get_real_object() & other
+    def __xor__(self, other): return self._get_real_object() ^ other
+    def __or__(self, other): return self._get_real_object() | other
+
+    # --- Right-hand side numeric operators ---
+    def __radd__(self, other): return other + self._get_real_object()
+    def __rsub__(self, other): return other - self._get_real_object()
+    def __rmul__(self, other): return other * self._get_real_object()
+    def __rmatmul__(self, other): return other @ self._get_real_object()
+    def __rtruediv__(self, other): return other / self._get_real_object()
+    def __rfloordiv__(self, other): return other // self._get_real_object()
+    def __rmod__(self, other): return other % self._get_real_object()
+    def __rdivmod__(self, other): return divmod(other, self._get_real_object())
+    def __rpow__(self, other): return pow(other, self._get_real_object())
+    def __rlshift__(self, other): return other << self._get_real_object()
+    def __rrshift__(self, other): return other >> self._get_real_object()
+    def __rand__(self, other): return other & self._get_real_object()
+    def __rxor__(self, other): return other ^ self._get_real_object()
+    def __ror__(self, other): return other | self._get_real_object()
+
+    # --- Unary operators ---
+    def __neg__(self): return -self._get_real_object()
+    def __pos__(self): return +self._get_real_object()
+    def __abs__(self): return abs(self._get_real_object())
+    def __invert__(self): return ~self._get_real_object()
+
+    # --- Comparison operators ---
+    def __eq__(self, other): return self._get_real_object() == other
+    def __ne__(self, other): return self._get_real_object() != other
+    def __lt__(self, other): return self._get_real_object() < other
+    def __le__(self, other): return self._get_real_object() <= other
+    def __gt__(self, other): return self._get_real_object() > other
+    def __ge__(self, other): return self._get_real_object() >= other
+    def __hash__(self): return hash(self._get_real_object())
+
+    # --- Truthiness, Callability and Context Management ---
+    def __bool__(self): return bool(self._get_real_object())
+    def __call__(self, *args, **kwargs): return self._get_real_object()(*args, **kwargs)
+    def __enter__(self): return self._get_real_object().__enter__()
+    def __exit__(self, exc_type, exc_val, exc_tb): return self._get_real_object().__exit__(exc_type, exc_val, exc_tb)
+
+# ==============================================================================
+# --- 2. The Scanner and `init` Facade ---
+# ==============================================================================
+def _scan_and_configure(package_or_name, container: PicoContainer):
+    package = importlib.import_module(package_or_name) if isinstance(package_or_name, str) else package_or_name
+    logging.info(f"🚀 Scanning in '{package.__name__}'...")
+    component_classes, factory_classes = [], []
+    for _, name, _ in pkgutil.walk_packages(package.__path__, package.__name__ + '.'):
+        try:
+            module = importlib.import_module(name)
+            for _, obj in inspect.getmembers(module, inspect.isclass):
+                if hasattr(obj, '_is_component'):
+                    component_classes.append(obj)
+                elif hasattr(obj, '_is_factory_component'):
+                    factory_classes.append(obj)
+        except Exception as e:
+            logging.warning(f"  ⚠️ Module {name} not processed: {e}")
+
+    for factory_cls in factory_classes:
+        try:
+            sig = inspect.signature(factory_cls.__init__)
+            instance = factory_cls(container) if 'container' in sig.parameters else factory_cls()
+            for _, method in inspect.getmembers(instance, inspect.ismethod):
+                if hasattr(method, '_provides_name'):
+                    container.bind(getattr(method, '_provides_name'), method)
+        except Exception as e:
+            logging.error(f"  ❌ Error in factory {factory_cls.__name__}: {e}", exc_info=True)
+
+    for component_cls in component_classes:
+        key = getattr(component_cls, '_component_key', component_cls)
+        def create_component(cls=component_cls):
+            sig = inspect.signature(cls.__init__)
+            deps = {}
+            for p in sig.parameters.values():
+                if p.name == 'self' or p.kind in (
+                    inspect.Parameter.VAR_POSITIONAL,  # *args
+                    inspect.Parameter.VAR_KEYWORD,     # **kwargs
+                ):
+                    continue
+                dep_key = p.annotation if p.annotation is not inspect._empty else p.name
+                deps[p.name] = container.get(dep_key)
+            return cls(**deps)
+        container.bind(key, create_component)
+
+_container = None
+def init(root_package):
+    global _container
+    if _container:
+        return _container
+    _container = PicoContainer()
+    logging.info("🔌 Initializing 'pico-ioc'...")
+    _scan_and_configure(root_package, _container)
+    logging.info("✅ Container configured and ready.")
+    return _container
+
+# ==============================================================================
+# --- 3. The Decorators ---
+# ==============================================================================
+def factory_component(cls):
+    setattr(cls, '_is_factory_component', True)
+    return cls
+
+def provides(name: str, lazy: bool = True):
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            return LazyProxy(lambda: func(*args, **kwargs)) if lazy else func(*args, **kwargs)
+        setattr(wrapper, '_provides_name', name)
+        return wrapper
+    return decorator
+
+def component(cls=None, *, name: str = None):
+    def decorator(cls):
+        setattr(cls, '_is_component', True)
+        setattr(cls, '_component_key', name if name is not None else cls)
+        return cls
+    return decorator(cls) if cls else decorator
+

pico_ioc-0.1.0/src/pico_ioc/_version.py

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

pico_ioc-0.1.0/src/pico_ioc.egg-info/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: pico-ioc
+Version: 0.1.0
+Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
+Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
+Project-URL: Homepage, https://github.com/dperezcabrera/pico-ioc
+Project-URL: Repository, https://github.com/dperezcabrera/pico-ioc
+Project-URL: Issue Tracker, https://github.com/dperezcabrera/pico-ioc/issues
+Keywords: ioc,di,dependency injection,inversion of control,decorator
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown

pico_ioc-0.1.0/src/pico_ioc.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+Dockerfile.test
+Makefile
+README.MD
+pyproject.toml
+tox.ini
+.github/workflows/ci.yml
+.github/workflows/publish-to-pypi.yml
+src/pico_ioc/__init__.py
+src/pico_ioc/_version.py
+src/pico_ioc.egg-info/PKG-INFO
+src/pico_ioc.egg-info/SOURCES.txt
+src/pico_ioc.egg-info/dependency_links.txt
+src/pico_ioc.egg-info/top_level.txt
+tests/test_pico_ioc.py

pico_ioc-0.1.0/src/pico_ioc.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pico_ioc-0.1.0/src/pico_ioc.egg-info/top_level.txt

@@ -0,0 +1 @@
+pico_ioc

pico_ioc-0.1.0/tests/test_pico_ioc.py

@@ -0,0 +1,178 @@
+# tests/test_pico_ioc.py
+
+import pytest
+import sys
+import pico_ioc
+
+# --- Test Environment Setup Fixture ---
+
+@pytest.fixture
+def test_project(tmp_path):
+    """
+    Creates a fake project structure in a temporary directory
+    so that the pico_ioc scanner can find the components.
+    """
+    project_root = tmp_path / "test_project"
+    project_root.mkdir()
+    
+    # Add the root directory to the Python path so modules can be imported
+    sys.path.insert(0, str(tmp_path))
+
+    # >>> THE LINE THAT FIXES THE PROBLEM <<<
+    # Turn 'test_project' into a regular package.
+    (project_root / "__init__.py").touch()
+
+    # Create the package and modules with test components
+    package_dir = project_root / "services"
+    package_dir.mkdir()
+    
+    # __init__.py file to turn 'services' into a sub-package
+    (package_dir / "__init__.py").touch()
+
+    # Module with simple components and components with dependencies
+    (package_dir / "components.py").write_text("""
+from pico_ioc import component
+
+@component
+class SimpleService:
+    def get_id(self):
+        return id(self)
+
+@component
+class AnotherService:
+    def __init__(self, simple_service: SimpleService):
+        self.child = simple_service
+
+@component(name="custom_name_service")
+class CustomNameService:
+    pass
+""")
+
+    # Module with a component factory
+    (package_dir / "factories.py").write_text("""
+from pico_ioc import factory_component, provides
+
+# To test that instantiation is lazy
+CREATION_COUNTER = {"value": 0}
+
+@factory_component
+class ServiceFactory:
+    @provides(name="complex_service")
+    def create_complex_service(self):
+        CREATION_COUNTER["value"] += 1
+        return "This is a complex service"
+""")
+    
+    # Return the root package name for init() to use
+    yield "test_project"
+    
+    sys.path.pop(0)
+
+    # Reset the global pico_ioc container to isolate tests.
+    pico_ioc._container = None
+
+    # Purge the temporary package from the module cache so each test starts
+    # with a fresh module state (e.g., CREATION_COUNTER resets to 0).
+    mods_to_del = [
+        m for m in list(sys.modules.keys())
+        if m == "test_project" or m.startswith("test_project.")
+    ]
+    for m in mods_to_del:
+        sys.modules.pop(m, None)
+
+
+# --- Test Suite ---
+
+def test_simple_component_retrieval(test_project):
+    """Verifies that a simple component can be registered and retrieved."""
+    # Import the TEST classes after the fixture has created them
+    from test_project.services.components import SimpleService
+    
+    container = pico_ioc.init(test_project)
+    service = container.get(SimpleService)
+    
+    assert service is not None
+    assert isinstance(service, SimpleService)
+
+def test_dependency_injection(test_project):
+    """Verifies that a dependency is correctly injected into another component."""
+    from test_project.services.components import SimpleService, AnotherService
+
+    container = pico_ioc.init(test_project)
+    another_service = container.get(AnotherService)
+
+    assert another_service is not None
+    assert hasattr(another_service, "child")
+    assert isinstance(another_service.child, SimpleService)
+
+def test_components_are_singletons_by_default(test_project):
+    """Verifies that get() always returns the same instance for a component."""
+    from test_project.services.components import SimpleService
+
+    container = pico_ioc.init(test_project)
+    service1 = container.get(SimpleService)
+    service2 = container.get(SimpleService)
+
+    assert service1 is service2
+    assert service1.get_id() == service2.get_id()
+
+def test_get_unregistered_component_raises_error(test_project):
+    """Verifies that requesting an unregistered component raises a NameError."""
+    container = pico_ioc.init(test_project)
+    
+    class UnregisteredClass:
+        pass
+
+    with pytest.raises(NameError, match="No provider found for key"):
+        container.get(UnregisteredClass)
+
+def test_factory_provides_component(test_project):
+    """Verifies that a component created by a factory can be retrieved."""
+    container = pico_ioc.init(test_project)
+    
+    service = container.get("complex_service")
+    
+    # The object is a proxy, but it should delegate the comparison
+    assert service == "This is a complex service"
+
+def test_factory_instantiation_is_lazy(test_project):
+    """
+    Verifies that a factory's @provides method is only executed
+    when the object is first accessed.
+    """
+    # Import the counter from the test factory
+    from test_project.services.factories import CREATION_COUNTER
+    
+    container = pico_ioc.init(test_project)
+    
+    # Initially, the counter must be 0 because nothing has been created yet
+    assert CREATION_COUNTER["value"] == 0
+    
+    # We get the proxy, but this should NOT trigger the creation
+    service_proxy = container.get("complex_service")
+    assert CREATION_COUNTER["value"] == 0
+    
+    # Now we access an attribute of the real object (through the proxy)
+    # This SHOULD trigger the creation
+    result = service_proxy.upper() # .upper() is called on the real string
+    
+    assert CREATION_COUNTER["value"] == 1
+    assert result == "THIS IS A COMPLEX SERVICE"
+    
+    # If we access it again, the counter should not increment
+    _ = service_proxy.lower()
+    assert CREATION_COUNTER["value"] == 1
+
+def test_component_with_custom_name(test_project):
+    """Verifies that a component with a custom name can be registered and retrieved."""
+    from test_project.services.components import CustomNameService
+    
+    container = pico_ioc.init(test_project)
+    
+    # We get the service using its custom name
+    service = container.get("custom_name_service")
+    assert isinstance(service, CustomNameService)
+    
+    # Verify that requesting it by its class fails, as it was registered by name
+    with pytest.raises(NameError):
+        container.get(CustomNameService)

pico_ioc-0.1.0/tox.ini

@@ -0,0 +1,10 @@
+[tox]
+env_list = py38, py39, py310, py311, py312, py313
+isolated_build = true
+skip_missing_interpreters = false
+
+[testenv]
+description = Run tests with pytest
+deps = pytest
+commands = pytest
+