pico-ioc 0.4.0__tar.gz → 0.5.1__tar.gz

pico_ioc-0.5.1/.coveragerc

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

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

@@ -0,0 +1,102 @@
+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.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 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-ioc
+

{pico_ioc-0.4.0 → pico_ioc-0.5.1}/.github/workflows/publish-to-pypi.yml

@@ -29,4 +29,8 @@ jobs:
 
     - name: Publish to PyPI
       uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        skip-existing: true
+        verify-metadata: true
+        attestations: false
 

pico_ioc-0.5.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Pérez Cabrera
+
+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_ioc-0.5.1/MANIFEST.in

@@ -0,0 +1,24 @@
+# Incluir ficheros importantes
+include README.md
+include LICENSE
+
+# Incluir todo el código fuente
+recursive-include src *.py
+
+# Incluir datos de tests si quieres que otros puedan correrlos desde el sdist
+# (opcional — puedes quitarlo si no quieres incluir tests en PyPI)
+recursive-include tests *.py
+
+# Excluir cosas innecesarias
+exclude .gitignore
+exclude Dockerfile*
+exclude docker-compose*.yml
+exclude Makefile
+
+# Excluir carpetas de build, virtualenvs, caches, etc.
+prune build
+prune dist
+prune .tox
+prune .pytest_cache
+prune __pycache__
+

pico_ioc-0.5.1/PKG-INFO

@@ -0,0 +1,284 @@
+Metadata-Version: 2.4
+Name: pico-ioc
+Version: 0.5.1
+Summary: A minimalist, zero-dependency Inversion of Control (IoC) container for Python.
+Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 David Pérez Cabrera
+        
+        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-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
+License-File: LICENSE
+Dynamic: license-file
+
+Got it ✅
+Here’s your **updated README.md in full English**, keeping all original sections but now including the **name-first resolution** feature and new tests section.
+
+---
+
+````markdown
+# 📦 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)
+[![codecov](https://codecov.io/gh/dperezcabrera/pico-ioc/branch/main/graph/badge.svg)](https://codecov.io/gh/dperezcabrera/pico-ioc)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
+[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
+
+**Pico-IoC** is a tiny, zero-dependency, decorator-based Inversion of Control container for Python.  
+Build loosely-coupled, testable apps without manual wiring. Inspired by the Spring ecosystem.
+
+---
+
+## ✨ Key Features
+
+* **Zero dependencies** — pure Python.
+* **Decorator API** — `@component`, `@factory_component`, `@provides`.
+* **Auto discovery** — scans a package and registers components.
+* **Eager by default, fail-fast** — non-lazy bindings are instantiated immediately after `init()`. Missing deps fail startup.
+* **Opt-in lazy** — set `lazy=True` to defer creation (wrapped in `ComponentProxy`).
+* **Factories** — encapsulate complex creation logic.
+* **Smart resolution order** — **parameter name** takes precedence over **type annotation**, then **MRO fallback**, then **string(name)**.
+* **Re-entrancy guard** — prevents `get()` during scanning.
+* **Auto-exclude caller** — `init()` skips the calling module to avoid double scanning.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install pico-ioc
+````
+
+---
+
+## 🚀 Quick Start
+
+```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}"
+
+container = init(__name__)  # blueprint runs here (eager + fail-fast)
+db = container.get(DatabaseService)
+print(db.get_data())
+```
+
+---
+
+## 🧩 Custom Component Keys
+
+```python
+from pico_ioc import component, init
+
+@component(name="config")  # custom key
+class AppConfig:
+    db_url = "postgresql://user:pass@localhost/db"
+
+@component
+class Repository:
+    def __init__(self, config: "config"):  # resolve by NAME
+        self.url = config.db_url
+
+container = init(__name__)
+print(container.get("config").db_url)
+```
+
+---
+
+## 🏭 Factories and `@provides`
+
+* Default is **eager** (`lazy=False`). Eager bindings are constructed at the end of `init()`.
+* Use `lazy=True` for on-first-use creation via `ComponentProxy`.
+
+```python
+from pico_ioc import factory_component, provides, init
+
+COUNTER = {"value": 0}
+
+@factory_component
+class ServicesFactory:
+    @provides(key="heavy_service", lazy=True)
+    def heavy(self):
+        COUNTER["value"] += 1
+        return {"payload": "hello"}
+
+container = init(__name__)
+svc = container.get("heavy_service")  # not created yet
+print(COUNTER["value"])               # 0
+print(svc["payload"])                 # triggers creation
+print(COUNTER["value"])               # 1
+```
+
+---
+
+## 🧠 Dependency Resolution Order (Updated in v0.5.0)
+
+Starting with **v0.5.0**, Pico-IoC enforces **name-first resolution**:
+
+1. **Parameter name** (highest priority)
+2. **Exact type annotation**
+3. **MRO fallback** (walk base classes)
+4. **String(name)**
+
+This means that if a dependency could match both by name and type, **the name match wins**.
+
+Example:
+
+```python
+from pico_ioc import component, factory_component, provides, init
+
+class BaseType: ...
+class Impl(BaseType): ...
+
+@component(name="inject_by_name")
+class InjectByName:
+    def __init__(self):
+        self.value = "by-name"
+
+@factory_component
+class NameVsTypeFactory:
+    @provides("choose", lazy=True)
+    def make(self, inject_by_name, hint: BaseType = None):
+        return inject_by_name.value
+
+container = init(__name__)
+assert container.get("choose") == "by-name"
+```
+
+---
+
+## ⚡ Eager vs. Lazy (Blueprint Behavior)
+
+At the end of `init()`, Pico-IoC performs a **blueprint**:
+
+* **Eager** (`lazy=False`, default): instantiated immediately; failures stop startup.
+* **Lazy** (`lazy=True`): returns a `ComponentProxy`; instantiated on first real use.
+
+**Lifecycle:**
+
+```
+       ┌───────────────────────┐
+       │        init()         │
+       └───────────────────────┘
+                  │
+                  ▼
+       ┌───────────────────────┐
+       │   Scan & bind deps    │
+       └───────────────────────┘
+                  │
+                  ▼
+       ┌─────────────────────────────┐
+       │  Blueprint instantiates all │
+       │    non-lazy (eager) beans   │
+       └─────────────────────────────┘
+                  │
+       ┌───────────────────────┐
+       │   Container ready     │
+       └───────────────────────┘
+```
+
+---
+
+## 🛠 API Reference
+
+### `init(root, *, exclude=None, auto_exclude_caller=True) -> PicoContainer`
+
+Scan and bind components in `root` (str module name or module).
+Skips the calling module if `auto_exclude_caller=True`.
+Runs blueprint (instantiate all `lazy=False` bindings).
+
+### `@component(cls=None, *, name=None, lazy=False)`
+
+Register a class as a component.
+Use `name` for a custom key.
+Set `lazy=True` to defer creation.
+
+### `@factory_component`
+
+Mark a class as a component factory (its methods can `@provides` bindings).
+
+### `@provides(key, *, lazy=False)`
+
+Declare that a factory method provides a component under `key`.
+Set `lazy=True` for deferred creation (`ComponentProxy`).
+
+---
+
+## 🧪 Testing
+
+```bash
+pip install tox
+tox
+```
+
+**New in v0.5.0:**
+Additional tests verify:
+
+* Name vs. type precedence.
+* Mixed binding key resolution in factories.
+* Eager vs. lazy instantiation edge cases.
+
+---
+
+## 🔌 Extensibility: Plugins, Binder, and Lifecycle Hooks
+
+From `v0.4.0` onward, Pico-IoC can be cleanly extended without patching the core.
+
+*(plugin API docs unchanged from before)*
+
+---
+
+## 📜 License
+
+MIT — see [LICENSE](https://opensource.org/licenses/MIT)
+
+```
+
+

pico_ioc-0.5.1/README.md

@@ -0,0 +1,237 @@
+Got it ✅
+Here’s your **updated README.md in full English**, keeping all original sections but now including the **name-first resolution** feature and new tests section.
+
+---
+
+````markdown
+# 📦 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)
+[![codecov](https://codecov.io/gh/dperezcabrera/pico-ioc/branch/main/graph/badge.svg)](https://codecov.io/gh/dperezcabrera/pico-ioc)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
+[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-ioc&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-ioc)
+
+**Pico-IoC** is a tiny, zero-dependency, decorator-based Inversion of Control container for Python.  
+Build loosely-coupled, testable apps without manual wiring. Inspired by the Spring ecosystem.
+
+---
+
+## ✨ Key Features
+
+* **Zero dependencies** — pure Python.
+* **Decorator API** — `@component`, `@factory_component`, `@provides`.
+* **Auto discovery** — scans a package and registers components.
+* **Eager by default, fail-fast** — non-lazy bindings are instantiated immediately after `init()`. Missing deps fail startup.
+* **Opt-in lazy** — set `lazy=True` to defer creation (wrapped in `ComponentProxy`).
+* **Factories** — encapsulate complex creation logic.
+* **Smart resolution order** — **parameter name** takes precedence over **type annotation**, then **MRO fallback**, then **string(name)**.
+* **Re-entrancy guard** — prevents `get()` during scanning.
+* **Auto-exclude caller** — `init()` skips the calling module to avoid double scanning.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install pico-ioc
+````
+
+---
+
+## 🚀 Quick Start
+
+```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}"
+
+container = init(__name__)  # blueprint runs here (eager + fail-fast)
+db = container.get(DatabaseService)
+print(db.get_data())
+```
+
+---
+
+## 🧩 Custom Component Keys
+
+```python
+from pico_ioc import component, init
+
+@component(name="config")  # custom key
+class AppConfig:
+    db_url = "postgresql://user:pass@localhost/db"
+
+@component
+class Repository:
+    def __init__(self, config: "config"):  # resolve by NAME
+        self.url = config.db_url
+
+container = init(__name__)
+print(container.get("config").db_url)
+```
+
+---
+
+## 🏭 Factories and `@provides`
+
+* Default is **eager** (`lazy=False`). Eager bindings are constructed at the end of `init()`.
+* Use `lazy=True` for on-first-use creation via `ComponentProxy`.
+
+```python
+from pico_ioc import factory_component, provides, init
+
+COUNTER = {"value": 0}
+
+@factory_component
+class ServicesFactory:
+    @provides(key="heavy_service", lazy=True)
+    def heavy(self):
+        COUNTER["value"] += 1
+        return {"payload": "hello"}
+
+container = init(__name__)
+svc = container.get("heavy_service")  # not created yet
+print(COUNTER["value"])               # 0
+print(svc["payload"])                 # triggers creation
+print(COUNTER["value"])               # 1
+```
+
+---
+
+## 🧠 Dependency Resolution Order (Updated in v0.5.0)
+
+Starting with **v0.5.0**, Pico-IoC enforces **name-first resolution**:
+
+1. **Parameter name** (highest priority)
+2. **Exact type annotation**
+3. **MRO fallback** (walk base classes)
+4. **String(name)**
+
+This means that if a dependency could match both by name and type, **the name match wins**.
+
+Example:
+
+```python
+from pico_ioc import component, factory_component, provides, init
+
+class BaseType: ...
+class Impl(BaseType): ...
+
+@component(name="inject_by_name")
+class InjectByName:
+    def __init__(self):
+        self.value = "by-name"
+
+@factory_component
+class NameVsTypeFactory:
+    @provides("choose", lazy=True)
+    def make(self, inject_by_name, hint: BaseType = None):
+        return inject_by_name.value
+
+container = init(__name__)
+assert container.get("choose") == "by-name"
+```
+
+---
+
+## ⚡ Eager vs. Lazy (Blueprint Behavior)
+
+At the end of `init()`, Pico-IoC performs a **blueprint**:
+
+* **Eager** (`lazy=False`, default): instantiated immediately; failures stop startup.
+* **Lazy** (`lazy=True`): returns a `ComponentProxy`; instantiated on first real use.
+
+**Lifecycle:**
+
+```
+       ┌───────────────────────┐
+       │        init()         │
+       └───────────────────────┘
+                  │
+                  ▼
+       ┌───────────────────────┐
+       │   Scan & bind deps    │
+       └───────────────────────┘
+                  │
+                  ▼
+       ┌─────────────────────────────┐
+       │  Blueprint instantiates all │
+       │    non-lazy (eager) beans   │
+       └─────────────────────────────┘
+                  │
+       ┌───────────────────────┐
+       │   Container ready     │
+       └───────────────────────┘
+```
+
+---
+
+## 🛠 API Reference
+
+### `init(root, *, exclude=None, auto_exclude_caller=True) -> PicoContainer`
+
+Scan and bind components in `root` (str module name or module).
+Skips the calling module if `auto_exclude_caller=True`.
+Runs blueprint (instantiate all `lazy=False` bindings).
+
+### `@component(cls=None, *, name=None, lazy=False)`
+
+Register a class as a component.
+Use `name` for a custom key.
+Set `lazy=True` to defer creation.
+
+### `@factory_component`
+
+Mark a class as a component factory (its methods can `@provides` bindings).
+
+### `@provides(key, *, lazy=False)`
+
+Declare that a factory method provides a component under `key`.
+Set `lazy=True` for deferred creation (`ComponentProxy`).
+
+---
+
+## 🧪 Testing
+
+```bash
+pip install tox
+tox
+```
+
+**New in v0.5.0:**
+Additional tests verify:
+
+* Name vs. type precedence.
+* Mixed binding key resolution in factories.
+* Eager vs. lazy instantiation edge cases.
+
+---
+
+## 🔌 Extensibility: Plugins, Binder, and Lifecycle Hooks
+
+From `v0.4.0` onward, Pico-IoC can be cleanly extended without patching the core.
+
+*(plugin API docs unchanged from before)*
+
+---
+
+## 📜 License
+
+MIT — see [LICENSE](https://opensource.org/licenses/MIT)
+
+```
+
+