mixinv2 0.3.0.post12.dev0__tar.gz → 0.3.0.post24.dev0__tar.gz

{mixinv2-0.3.0.post12.dev0 → mixinv2-0.3.0.post24.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mixinv2
-Version: 0.3.0.post12.dev0
+Version: 0.3.0.post24.dev0
 Summary: A dependency injection framework with pytest-fixture syntax, plus a configuration language for declarative programming
 Project-URL: Repository, https://github.com/Atry/MIXINv2
 Author-email: "Yang, Bo" <yang-bo@yang-bo.com>

{mixinv2-0.3.0.post12.dev0 → mixinv2-0.3.0.post24.dev0}/docs/Makefile

@@ -16,9 +16,5 @@ help:
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile api-docs
+%: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-.PHONY: api-docs
-api-docs:
-	sphinx-apidoc --implicit-namespaces -o api ../src/mixinv2

{mixinv2-0.3.0.post12.dev0 → mixinv2-0.3.0.post24.dev0}/docs/conf.py

@@ -7,6 +7,8 @@ import subprocess
 import sys
 from pathlib import Path
 
+from sphinx.ext import apidoc
+
 # -- Path setup --------------------------------------------------------------
 # Add mixinv2/src to sys.path so autodoc can import the modules.
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
@@ -37,7 +39,7 @@ autodoc_default_options = {
 }
 
 templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'api/modules.rst', 'api/mixinv2.rst']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'api/modules.rst']
 
 
 
@@ -72,3 +74,20 @@ extlinks = {
         '%s',
     ),
 }
+
+
+def _generate_api_docs(app: object) -> None:
+    docs_directory = Path(__file__).resolve().parent
+    package_directory = docs_directory.parent / "src" / "mixinv2"
+    output_directory = docs_directory / "api"
+
+    apidoc.main([
+        "--implicit-namespaces",
+        "-o",
+        str(output_directory),
+        str(package_directory),
+    ])
+
+
+def setup(app: object) -> None:
+    app.connect("builder-inited", _generate_api_docs)

{mixinv2-0.3.0.post12.dev0 → mixinv2-0.3.0.post24.dev0}/docs/mixinv2-tutorial.rst

@@ -21,7 +21,7 @@ MIXINv2 solves this by separating the application into three layers:
   per operation (``sqlite3.connect``, ``str.split``, ``wfile.write``). Each adapter
   declares its inputs as ``@extern`` and exposes a single ``@public @resource``
   output. The adapter contains **zero business logic**.
-- **``.oyaml`` files** contain all application logic, written in MIXINv2. MIXINv2 is not just a configuration format — it is a
+- ``.mixin.yaml`` files contain all application logic, written in MIXINv2. MIXINv2 is not just a configuration format — it is a
   complete language with lexical scoping, nested scopes, deep-merge composition,
   and lazy evaluation. These features make it more natural than Python for
   expressing business logic, which is inherently declarative ("the user ID is
@@ -30,8 +30,8 @@ MIXINv2 solves this by separating the application into three layers:
 - **Configuration values** (SQL queries, format strings, host/port) are pure
   YAML scalars, gathered in one place.
 
-Business logic written in ``.oyaml`` is **portable**: it is decoupled from the
-Python FFI layer. Swap the FFI adapters and the same ``.oyaml`` logic runs against
+Business logic written in ``.mixin.yaml`` is **portable**: it is decoupled from the
+Python FFI layer. Swap the FFI adapters and the same ``.mixin.yaml`` logic runs against
 a different runtime — mock adapters for unit testing, a different language's
 stdlib for cross-platform deployment, or instrumented adapters for profiling.
 With Python ``@scope`` decorators, business logic is locked to the Python runtime
@@ -45,64 +45,64 @@ Python FFI adapters
 
 Each ``@scope`` class wraps exactly one stdlib operation. Below are three
 representative adapters; the full module
-(:github:`tests/fixtures/app_oyaml/stdlib_ffi/FFI.py`)
+(:github:`packages/mixinv2-examples/src/mixinv2_examples/app_mixin/StdlibFFI/FFI/`)
 contains 10 more following the same pattern.
 
 ``SqliteConnectAndExecuteScript`` — multiple inputs, single output:
 
-.. literalinclude:: ../../tests/fixtures/app_oyaml/stdlib_ffi/FFI/SqliteConnectAndExecuteScript.py
+.. literalinclude:: ../../mixinv2-examples/src/mixinv2_examples/app_mixin/StdlibFFI/FFI/SqliteConnectAndExecuteScript.py
    :language: python
 
 ``GetItem`` — generic ``sequence[index]`` operation:
 
-.. literalinclude:: ../../tests/fixtures/app_oyaml/stdlib_ffi/FFI/GetItem.py
+.. literalinclude:: ../../mixinv2-examples/src/mixinv2_examples/app_mixin/StdlibFFI/FFI/GetItem.py
    :language: python
 
 ``HttpSendResponse`` — chained I/O, send status + headers + body:
 
-.. literalinclude:: ../../tests/fixtures/app_oyaml/stdlib_ffi/FFI/HttpSendResponse.py
+.. literalinclude:: ../../mixinv2-examples/src/mixinv2_examples/app_mixin/StdlibFFI/FFI/HttpSendResponse.py
    :language: python
 
 Notice what is *not* here: no SQL queries, no ``"/"`` separator, no format string,
 no ``:memory:`` path, no port number. Those are all business decisions that live
-in the ``.oyaml``.
+in the ``.mixin.yaml``.
 
 
-``.oyaml`` composition
-----------------------
+``.mixin.yaml`` composition
+---------------------------
 
-An ``.oyaml`` file describes a **dependency graph**, not an execution sequence.
+A ``.mixin.yaml`` file describes a **dependency graph**, not an execution sequence.
 There is no top-to-bottom control flow — the runtime evaluates resources lazily,
 on demand. Think spreadsheet cells, not shell scripts.
 
-The business logic lives in ``Library.oyaml``, which references FFI adapters
+The business logic lives in ``Library.mixin.yaml``, which references FFI adapters
 through abstract declarations (``FFI:`` scope with ``[]`` slots). A concrete FFI
-module (``stdlib_ffi/FFI.py``) overrides these slots at composition time. This
+module (``StdlibFFI/FFI/``) overrides these slots at composition time. This
 separation means the business logic is portable — swap ``stdlib_ffi`` for a
-different FFI implementation and the ``.oyaml`` files need no changes.
+different FFI implementation and the ``.mixin.yaml`` files need no changes.
 
-The following sections walk through ``Library.oyaml`` one scope at a time,
+The following sections walk through ``Library.mixin.yaml`` one scope at a time,
 introducing new language concepts as they appear.
 
 
 ``SQLiteDatabase`` — extern, inheritance, wiring, projection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. literalinclude:: ../../tests/fixtures/app_oyaml/Library.oyaml
+.. literalinclude:: ../../mixinv2-examples/src/mixinv2_examples/app_mixin/Library.mixin.yaml
    :language: yaml
    :start-after: # [docs:sqlite-database]
    :end-before: # [/docs:sqlite-database]
 
 Four new concepts:
 
-- **``field: []``** — an **extern declaration**, the ``.oyaml`` equivalent of
+- ``field: []`` — an **extern declaration**, the ``.mixin.yaml`` equivalent of
   ``@extern``. The value must come from a parent scope or the caller.
-- **``- [FFI, SqliteConnectAndExecuteScript]``** — **inheritance**. ``_db`` inherits
+- ``- [FFI, SqliteConnectAndExecuteScript]`` — **inheritance**. ``_db`` inherits
   the FFI adapter, gaining all of its resources (``connection``).
-- **``database_path: [database_path]``** — **wiring**. The reference ``[database_path]``
+- ``database_path: [database_path]`` — **wiring**. The reference ``[database_path]``
   is a lexical lookup: search outward through enclosing scopes until a field
   named ``database_path`` is found.
-- **``connection: [_db, connection]``** — **path navigation**. Access the
+- ``connection: [_db, connection]`` — **path navigation**. Access the
   ``connection`` resource on the child scope ``_db``. The leading underscore on
   ``_db`` makes it private; ``connection`` is the public-facing projection.
 
@@ -110,16 +110,16 @@ Four new concepts:
 ``UserRepository`` (app-scoped part) — nested scope, scope-as-dataclass
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. literalinclude:: ../../tests/fixtures/app_oyaml/Library.oyaml
+.. literalinclude:: ../../mixinv2-examples/src/mixinv2_examples/app_mixin/Library.mixin.yaml
    :language: yaml
    :start-after: # [docs:user-repository-app]
    :end-before: # [/docs:user-repository-app]
 
-- **``User:``** is a **nested scope** with two extern fields — the ``.oyaml``
+- ``User:`` is a **nested scope** with two extern fields — the ``.mixin.yaml``
   equivalent of ``@scope class User`` with ``@public @extern`` fields. It acts as a
   dataclass constructor: ``current_user`` (below) will supply values for
   ``user_id`` and ``name``.
-- **``connection: []``** declares that ``UserRepository`` expects a ``connection``
+- ``connection: []`` declares that ``UserRepository`` expects a ``connection``
   from outside. When composed with ``SQLiteDatabase`` inside ``app``, this extern
   is satisfied by ``SQLiteDatabase.connection`` — resolved by name through
   lexical scoping.
@@ -128,7 +128,7 @@ Four new concepts:
 ``UserRepository.RequestScope`` — ANF style, cross-scope references
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. literalinclude:: ../../tests/fixtures/app_oyaml/Library.oyaml
+.. literalinclude:: ../../mixinv2-examples/src/mixinv2_examples/app_mixin/Library.mixin.yaml
    :language: yaml
    :start-after: # [docs:user-repository-request-scope]
    :end-before: # [/docs:user-repository-request-scope]
@@ -146,7 +146,7 @@ searches outward through parent, grandparent, etc. No import statement is
 needed; the scope hierarchy *is* the namespace.
 
 **Constructing ``current_user``:** Instead of calling ``User(user_id=..., name=...)``,
-the ``.oyaml`` directly defines ``current_user`` as a scope with two fields. The
+the ``.mixin.yaml`` directly defines ``current_user`` as a scope with two fields. The
 ``User`` scope-as-dataclass above establishes the field names; here those same
 names are filled with concrete values.
 
@@ -154,7 +154,7 @@ names are filled with concrete values.
 ``HttpHandlers`` — flat inheritance, qualified this
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. literalinclude:: ../../tests/fixtures/app_oyaml/Library.oyaml
+.. literalinclude:: ../../mixinv2-examples/src/mixinv2_examples/app_mixin/Library.mixin.yaml
    :language: yaml
    :start-after: # [docs:http-handlers]
    :end-before: # [/docs:http-handlers]
@@ -170,7 +170,7 @@ namespace. The last list item (the mapping starting with ``request: []``) define
 point ``user_count`` is just an extern ``[]`` — its actual value comes from
 ``UserRepository`` after deep merge (explained below).
 
-**Qualified this: ``[RequestScope, ~, written]``** — instead of declaring
+**Qualified this:** ``[RequestScope, ~, written]`` — instead of declaring
 ``written: []`` and writing ``response: [written]``, this navigates the runtime
 composition graph to access the ``written`` property inherited from
 ``HttpSendResponse``. The advantage: if ``HttpSendResponse`` is accidentally not
@@ -180,26 +180,26 @@ composed, this fails with an error instead of silently creating an empty scope.
 ``NetworkServer`` — deep merge, config scoping
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. literalinclude:: ../../tests/fixtures/app_oyaml/Library.oyaml
+.. literalinclude:: ../../mixinv2-examples/src/mixinv2_examples/app_mixin/Library.mixin.yaml
    :language: yaml
    :start-after: # [docs:network-server]
    :end-before: # [/docs:network-server]
 
-All the scopes above live in ``Library.oyaml``. They reference ``[FFI, Xxx]`` which
+All the scopes above live in ``Library.mixin.yaml``. They reference ``[FFI, Xxx]`` which
 resolves to abstract declarations at the top of the file — no concrete Python
 code is involved yet.
 
 
-``Apps.oyaml`` — integration entry point
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``Apps.mixin.yaml`` — integration entry point
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-``Apps.oyaml`` is a separate file that inherits the real FFI implementation and
+``Apps.mixin.yaml`` is a separate file that inherits the real FFI implementation and
 the Library, then defines concrete application entries:
 
-.. literalinclude:: ../../tests/fixtures/app_oyaml/Apps.oyaml
+.. literalinclude:: ../../mixinv2-examples/src/mixinv2_examples/app_mixin/Apps.mixin.yaml
    :language: yaml
-   :start-after: # [docs:apps-oyaml]
-   :end-before: # [/docs:apps-oyaml]
+   :start-after: # [docs:apps-mixin-yaml]
+   :end-before: # [/docs:apps-mixin-yaml]
 
 **Library/FFI separation:** ``- [stdlib_ffi]`` makes the real ``FFI`` module
 (Python ``@scope`` classes) visible. ``- [Library]`` makes the business logic
@@ -208,21 +208,21 @@ with ``Library.FFI`` (abstract declarations), and the real ``@resource`` methods
 override the ``[]`` slots. The business logic never imports Python directly.
 
 **Portability:** To run the same business logic on a different runtime, replace
-``- [stdlib_ffi]`` with a different FFI package — the ``Library.oyaml`` file needs
+``- [stdlib_ffi]`` with a different FFI package — the ``Library.mixin.yaml`` file needs
 no changes. To test with mocks, provide a mock FFI module instead of
 ``stdlib_ffi``.
 
 **"What Color Is Your Function?"** (`blog post <https://journal.stuffwithstuff.com/2015/02/01/what-color-is-your-function/>`_):
-The same ``Library.oyaml`` runs unchanged on both synchronous and asynchronous
+The same ``Library.mixin.yaml`` runs unchanged on both synchronous and asynchronous
 runtimes. Replacing ``- [stdlib_ffi]`` with ``- [async_ffi]`` swaps the FFI layer
 to one built on ``aiosqlite`` + ``starlette``
-(:github:`implementation <tests/fixtures/app_oyaml/async_ffi/FFI/>`) — the business
+(:github:`implementation <packages/mixinv2-examples/src/mixinv2_examples/app_mixin/AsyncFFI/FFI/>`) — the business
 logic never knows whether it is sync or async. Function color is confined
-entirely to the FFI boundary; ``Library.oyaml`` itself is *colorless*.
+entirely to the FFI boundary; ``Library.mixin.yaml`` itself is *colorless*.
 
 **Composition via inheritance:** ``memory_app`` inherits four scopes via
 qualified this (``[Apps, ~, SQLiteDatabase]`` etc.) because these scopes are
-inherited properties, not own properties of ``Apps.oyaml``. This is not four
+inherited properties, not own properties of ``Apps.mixin.yaml``. This is not four
 separate instances — it is a single scope with all four merged together. The
 last list item supplies concrete values for every ``[]`` extern.
 
@@ -281,7 +281,7 @@ Python vs MIXINv2
 
    * - Aspect
      - Python ``@scope``
-     - MIXINv2 (``.oyaml``)
+     - MIXINv2 (``.mixin.yaml``)
    * - Composition
      - Manual ``@extend`` + ``RelativeReference``
      - Inheritance list: ``- [Parent]``
@@ -299,7 +299,7 @@ Python vs MIXINv2
      - Qualified this: ``[Scope, ~, symbol]``
    * - Business logic location
      - Mixed with I/O in Python
-     - Separate ``.oyaml`` file, portable across FFI
+     - Separate ``.mixin.yaml`` file, portable across FFI
    * - Configuration
      - Kwargs at call site
      - Scalar values in ``memory_app:`` scope
@@ -310,13 +310,13 @@ Evaluation
 
 .. code-block:: python
 
-   import tests.fixtures.app_oyaml as app_oyaml
+   import tests.fixtures.app_mixin as app_mixin
    from mixinv2 import evaluate
 
-   # evaluate() auto-discovers stdlib_ffi/, Library.oyaml, and Apps.oyaml.
-   root = evaluate(app_oyaml, modules_public=True)
+   # evaluate() auto-discovers stdlib_ffi/, Library.mixin.yaml, and Apps.mixin.yaml.
+   root = evaluate(app_mixin, modules_public=True)
 
-   # Access the composed app — Apps is the .oyaml file name.
+   # Access the composed app — Apps is the .mixin.yaml file name.
    composed_app = root.Apps.memory_app
 
    composed_app.server               # HTTPServer on 127.0.0.1:<assigned port>
@@ -328,14 +328,14 @@ Evaluation
    scope.current_user.name           # "alice"
    scope.response                    # sends HTTP response as side effect
 
-Swapping configuration is just a different entry in ``Apps.oyaml`` — the Python
-FFI adapters and ``Library.oyaml`` never change. Swapping the FFI layer is just a
-different ``@scope`` module — the ``.oyaml`` business logic never changes.
+Swapping configuration is just a different entry in ``Apps.mixin.yaml`` — the Python
+FFI adapters and ``Library.mixin.yaml`` never change. Swapping the FFI layer is just a
+different ``@scope`` module — the ``.mixin.yaml`` business logic never changes.
 
 Runnable tests for this example are in
-:github:`tests/test_readme_package_examples.py`,
+:github:`packages/mixinv2-examples/tests/test_readme_package_examples.py`,
 using the fixture package at
-:github:`tests/fixtures/app_oyaml/`.
+:github:`packages/mixinv2-examples/src/mixinv2_examples/app_mixin/`.
 
 The full language specification is in :doc:`specification`.
 

{mixinv2-0.3.0.post12.dev0 → mixinv2-0.3.0.post24.dev0}/docs/specification.md

@@ -91,7 +91,7 @@ As a configuration language, MIXINv2 excels in defining complex systems with int
 The following example demonstrates how to use MIXINv2 to define a basic arithmetic operation represented as an AST:
 
 ```yaml
-# math_operations.oyaml
+# math_operations.mixin.yaml
 
 Number:
   - {} # An overlay that represents a number type.
@@ -108,7 +108,7 @@ multiply:
 ```
 
 ```yaml
-# test.oyaml
+# test.mixin.yaml
 
 example_calculation:
   - [add]
@@ -124,7 +124,7 @@ example_calculation:
 1. The `Number` overlay represents a basic number type with no initial value, aligning with MIXINv2's immutable and lazy-evaluated nature.
 2. The `add` overlay inherits from `Number` and defines two properties, `addend1` and `addend2`, both of which are also `Number`.
 3. The `multiply` overlay defines a multiplication operation with two properties: `multiplicand` and `multiplier`.
-4. In `test.oyaml`, the `example_calculation` overlay uses the `add` operation to add two numbers:
+4. In `test.mixin.yaml`, the `example_calculation` overlay uses the `add` operation to add two numbers:
    - `addend1` is a multiplication of `2` and `3`, represented using the `multiply` overlay.
    - `addend2` is the constant `4`.
 
@@ -286,7 +286,7 @@ In this example, `my_number` has both a scalar value `42` and inherits the `Numb
 In MIXINv2, properties with the same name defined in multiple parent overlays are always automatically merged:
 
 ```yaml
-# basic_features.oyaml
+# basic_features.mixin.yaml
 Vehicle:
   - wheels: [Number]
   - engine: {}
@@ -295,7 +295,7 @@ Motor:
   - engine:
       gasoline: true # Defines a default scalar value for 'engine'
 
-# advanced_features.oyaml
+# advanced_features.mixin.yaml
 hybrid_car:
   - ["basic_features", Vehicle]
   - ["basic_features", Motor]
@@ -464,17 +464,17 @@ MIXINv2 allows inheriting overlays defined in different files. The rules for cro
 project/
 │
 ├── module/
-│   ├── vehicle.oyaml
-│   ├── electric.oyaml
-│   └── car.oyaml
+│   ├── vehicle.mixin.yaml
+│   ├── electric.mixin.yaml
+│   └── car.mixin.yaml
 │
 ├── config/
-│   └── settings.oyaml
+│   └── settings.mixin.yaml
 └── test/
-    └── test_car.oyaml
+    └── test_car.mixin.yaml
 ```
 
-**vehicle.oyaml**:
+**vehicle.mixin.yaml**:
 
 ```yaml
 Vehicle:
@@ -482,7 +482,7 @@ Vehicle:
   wheels: [Number]
 ```
 
-**electric.oyaml**:
+**electric.mixin.yaml**:
 
 ```yaml
 Electric:
@@ -491,7 +491,7 @@ Electric:
   - battery_capacity: [Number]
 ```
 
-**car.oyaml**:
+**car.mixin.yaml**:
 
 ```yaml
 Car:
@@ -500,11 +500,11 @@ Car:
   - model: [String]
 ```
 
-**test_car.oyaml**:
+**test_car.mixin.yaml**:
 
 ```yaml
 test_car:
-  - [module, Car] # Cross-directory inheritance to Car in module/car.oyaml
+  - [module, Car] # Cross-directory inheritance to Car in module/car.mixin.yaml
   - model: "Test Model"
   - test_battery:
       - [module, Electric, battery_capacity] # Inheritance to battery_capacity in Electric
@@ -512,7 +512,7 @@ test_car:
 
 In this example:
 
-- The `test_car` overlay in `test_car.oyaml` inherits `Car` and `Electric` from the `module` directory using the format `[module, Car]` and `[module, Electric, battery_capacity]`.
+- The `test_car` overlay in `test_car.mixin.yaml` inherits `Car` and `Electric` from the `module` directory using the format `[module, Car]` and `[module, Electric, battery_capacity]`.
 - The first segment of the inheritance (`module`) indicates the directory in which the target overlays are located.
 - The inheritance format and scope rules ensure that overlays are correctly resolved based on the file and directory structure.
 
@@ -704,7 +704,7 @@ When an overlay inherits from multiple parent overlays, the properties from all
 **Example:**
 
 ```yaml
-# basic_features.oyaml
+# basic_features.mixin.yaml
 Vehicle:
   - wheels: [Number]
   - engine: {}
@@ -713,7 +713,7 @@ Motor:
   - engine:
       gasoline: true # Scalar value for 'engine'
 
-# advanced_features.oyaml
+# advanced_features.mixin.yaml
 hybrid_car:
   - ["basic_features", Vehicle]
   - ["basic_features", Motor]
@@ -740,15 +740,15 @@ Scalar values (e.g., strings, numbers, booleans) can coexist with properties wit
 **Example:**
 
 ```yaml
-# number.oyaml
+# number.mixin.yaml
 Number:
   - {} # Represents a number type overlay
 
-# value.oyaml
+# value.mixin.yaml
 value_42:
   - 42 # Defines scalar value 42
 
-# my_number.oyaml
+# my_number.mixin.yaml
 my_number:
   - [Number]
   - [value_42]
@@ -770,15 +770,15 @@ An overlay can have both scalar values and properties, and these can be inherite
 **Example:**
 
 ```yaml
-# person.oyaml
+# person.mixin.yaml
 PersonDetails:
   name: [String]
   age: [Number]
 
-# height.oyaml
+# height.mixin.yaml
 height_value: 180 # Scalar value representing height
 
-# combined_person.oyaml
+# combined_person.mixin.yaml
 combined_person:
   - [PersonDetails]
   - name: "John Doe"
@@ -806,7 +806,7 @@ MIXINv2's approach to inheritance ensures that properties and scalar values from
 **Example of Conflict-Free Inheritance:**
 
 ```yaml
-# basic_features.oyaml
+# basic_features.mixin.yaml
 Vehicle:
   - wheels: [Number]
   - engine:
@@ -815,7 +815,7 @@ Vehicle:
 Motor:
   - engine: {} # Defines 'engine' property
 
-# advanced_features.oyaml
+# advanced_features.mixin.yaml
 hybrid_car:
   - ["basic_features", Vehicle]
   - ["basic_features", Motor]

mixinv2-0.3.0.post24.dev0/docs/tutorial.rst

@@ -0,0 +1,206 @@
+Getting Started with Decorators
+================================
+
+The examples below build a single web application step by step, introducing one
+concept at a time. All code is runnable with the standard library only.
+
+
+Step 1 — Define services
+------------------------
+
+Decorate a class with ``@scope`` to make it a DI container. Annotate each value with
+``@resource`` and expose it with ``@public``. Resources declare their dependencies as
+ordinary function parameters; the framework injects them by name.
+
+Use ``@extern`` to declare a dependency that must come from outside the scope — the
+equivalent of a pytest fixture parameter. Pass multiple scopes to ``evaluate()`` to
+compose them; dependencies are resolved by name across scope boundaries. Config
+values are passed as kwargs when calling the evaluated scope.
+
+.. literalinclude:: ../../mixinv2-examples/src/mixinv2_examples/app_decorator/step1_services.py
+   :language: python
+   :start-after: # [docs:step1-define-services]
+   :end-before: # [/docs:step1-define-services]
+   :dedent:
+
+``SQLiteDatabase`` owns ``databasePath``; ``UserRepository`` has no knowledge of the
+database layer — it only declares ``connection: sqlite3.Connection`` as a parameter
+and receives it automatically from the composed scope.
+
+
+Step 2 — Layer cross-cutting concerns with ``@patch`` and ``@merge``
+--------------------------------------------------------------------
+
+``@patch`` wraps an existing resource value with a transformation. This lets an
+add-on scope modify a value without touching the scope that defined it — the same
+idea as pytest's ``monkeypatch``, but composable.
+
+.. literalinclude:: ../../mixinv2-examples/src/mixinv2_examples/app_decorator/step2_patch.py
+   :language: python
+   :start-after: # [docs:step2-patch]
+   :end-before: # [/docs:step2-patch]
+   :dedent:
+
+When several independent scopes each contribute a piece to the same resource, use
+``@merge`` to define how the contributions are aggregated:
+
+.. literalinclude:: ../../mixinv2-examples/src/mixinv2_examples/app_decorator/step2_merge.py
+   :language: python
+   :start-after: # [docs:step2-merge]
+   :end-before: # [/docs:step2-merge]
+   :dedent:
+
+A ``@patch`` can itself declare ``@extern`` dependencies, which are injected like any
+other resource:
+
+.. literalinclude:: ../../mixinv2-examples/src/mixinv2_examples/app_decorator/step2_patch_extern.py
+   :language: python
+   :start-after: # [docs:step2-patch-extern]
+   :end-before: # [/docs:step2-patch-extern]
+   :dedent:
+
+
+Step 3 — Force evaluation at startup with ``@eager``
+-----------------------------------------------------
+
+All resources are lazy by default: computed on first access, then cached for the
+lifetime of the scope. Mark a resource ``@eager`` to evaluate it immediately when
+``evaluate()`` returns — useful for schema migrations or connection pre-warming that
+must complete before the application starts serving requests:
+
+.. literalinclude:: ../../mixinv2-examples/src/mixinv2_examples/app_decorator/step3_eager.py
+   :language: python
+   :start-after: # [docs:step3-eager]
+   :end-before: # [/docs:step3-eager]
+   :dedent:
+
+Without ``@eager``, the ``CREATE TABLE`` would not run until ``root.connection`` is first
+accessed.
+
+
+Step 4 — App scope vs request scope
+------------------------------------
+
+So far all resources have had application lifetime: created once at startup and
+reused for every request. Real applications also need per-request resources — values
+that must be created fresh for each incoming request and discarded when it completes.
+
+A nested ``@scope`` named ``RequestScope`` serves as a per-request factory. The
+framework injects it by name as a ``Callable``; calling
+``RequestScope(request=handler)`` returns a fresh instance.
+
+The application below has four scopes, each owning only its own concern:
+
+- **SQLiteDatabase** — owns ``databasePath``, provides ``connection``
+- **UserRepository** — business logic; owns ``userCount`` and per-request ``currentUser``
+- **HttpHandlers** — HTTP layer; owns per-request ``userId``, ``responseBody``, ``responseSent``
+- **NetworkServer** — network layer; owns ``host``/``port``, creates the ``HTTPServer``
+
+``UserRepository.RequestScope`` and ``HttpHandlers.RequestScope`` are composed into a
+single ``RequestScope`` by the union mount. ``userId`` (extracted from the HTTP path
+by ``HttpHandlers.RequestScope``) flows automatically into ``currentUser`` (looked up
+in the DB by ``UserRepository.RequestScope``) without any glue code.
+
+``responseSent`` is an IO resource: it sends the HTTP response as a side effect and
+returns ``None``. The handler body is a single attribute access — all logic lives in
+the DI graph. In an async framework (e.g. FastAPI), return an ``asyncio.Task[None]``
+instead of a coroutine, which cannot be safely awaited in multiple dependents.
+
+.. literalinclude:: ../../mixinv2-examples/src/mixinv2_examples/app_decorator/step4_http_server.py
+   :language: python
+   :start-after: # [docs:step4-http-server]
+   :end-before: # [/docs:step4-http-server]
+   :dedent:
+
+Assemble into a module and evaluate — pass the module directly to ``evaluate()``:
+
+.. code-block:: python
+
+   import mixinv2_examples.app_decorator.step4_http_server as step4_http_server
+
+   root = evaluate(step4_http_server, modules_public=True).App(
+       databasePath="/var/lib/myapp/prod.db",
+       host="127.0.0.1",
+       port=8080,
+   )
+   server = root.server
+
+Swapping to a test configuration is just different kwargs; no scope or composition changes:
+
+.. code-block:: python
+
+   test_root = evaluate(step4_http_server, modules_public=True).App(
+       databasePath=":memory:",  # fresh, isolated database for each test
+       host="127.0.0.1",
+       port=0,                    # OS assigns a free port
+   )
+   # test_root.connection  → sqlite3.Connection to :memory:
+   # test_root.server      → HTTPServer on OS-assigned port
+
+
+Decorator reference
+-------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 75
+
+   * - Decorator
+     - Purpose
+   * - ``@scope``
+     - Define a DI container (class) or sub-namespace
+   * - ``@resource``
+     - Declare a lazily-computed value; parameters are injected by name
+   * - ``@public``
+     - Expose a ``@resource`` or ``@scope`` to external callers
+   * - ``@extern``
+     - Declare a required dependency that must come from the composed scope
+   * - ``@patch``
+     - Provide a transformation that wraps an existing resource
+   * - ``@patch_many``
+     - Like ``@patch`` but yields multiple transformations at once
+   * - ``@merge``
+     - Define how patches are aggregated (e.g. ``frozenset``, ``list``, custom reducer)
+   * - ``@eager``
+     - Force evaluation at scope creation rather than on first access
+   * - ``@extend(*refs)``
+     - Inherit from other scopes explicitly (for package-level union mounts)
+   * - ``evaluate(*scopes)``
+     - Resolve and union-mount one or more scopes into a single dependency graph
+
+
+Python modules as scopes
+-------------------------
+
+The ``@scope`` classes above are a teaching convenience — the real-world style is
+plain Python modules, just like pytest fixtures don't require a class. Every
+``@scope`` class maps directly to a module file; pass it to ``evaluate()`` the same
+way:
+
+.. code-block:: python
+
+   import SqliteDatabase   # SqliteDatabase.py with @extern / @resource / @public
+   import UserRepository   # UserRepository/ package
+
+The same decorators work on module-level functions exactly as on class methods. A
+subpackage becomes a nested scope — ``UserRepository/RequestScope/`` is the
+module equivalent of a nested ``@scope class RequestScope``.
+
+Use ``@extend`` in a package's ``__init__.py`` to declare the composition, then
+``evaluate()`` receives the single package:
+
+.. literalinclude:: ../../mixinv2-examples/src/mixinv2_examples/app_di/__init__.py
+   :language: python
+   :start-after: # [docs:module-extend]
+   :end-before: # [/docs:module-extend]
+
+.. code-block:: python
+
+   import myapp
+
+   root = evaluate(myapp, modules_public=True).App(databasePath=":memory:")
+
+Runnable module-based equivalents of all tutorial examples are in
+:github:`packages/mixinv2-examples/tests/test_readme_package_examples.py`,
+using the fixture package at
+:github:`packages/mixinv2-examples/src/mixinv2_examples/app_di/`.

{mixinv2-0.3.0.post12.dev0 → mixinv2-0.3.0.post24.dev0}/src/mixinv2/_mixin_parser.py

@@ -217,7 +217,7 @@ def _make_scalar_resource(
 ) -> EndofunctionMergerDefinition[object]:
     """Create an EndofunctionMergerDefinition that returns a scalar value.
 
-    This is the oyaml equivalent of ``@resource def field(): return scalar_value``.
+    This is the .mixin.yaml equivalent of ``@resource def field(): return scalar_value``.
     """
     return EndofunctionMergerDefinition(
         inherits=(),

mixinv2-0.3.0.post12.dev0/docs/tutorial.rst

@@ -1,336 +0,0 @@
-Getting Started with Decorators
-================================
-
-The examples below build a single web application step by step, introducing one
-concept at a time. All code is runnable with the standard library only.
-
-
-Step 1 — Define services
-------------------------
-
-Decorate a class with ``@scope`` to make it a DI container. Annotate each value with
-``@resource`` and expose it with ``@public``. Resources declare their dependencies as
-ordinary function parameters; the framework injects them by name.
-
-Use ``@extern`` to declare a dependency that must come from outside the scope — the
-equivalent of a pytest fixture parameter. Pass multiple scopes to ``evaluate()`` to
-compose them; dependencies are resolved by name across scope boundaries. Config
-values are passed as kwargs when calling the evaluated scope.
-
-.. literalinclude:: ../../tests/test_readme_examples.py
-   :language: python
-   :start-after: # [docs:step1-define-services]
-   :end-before: # [/docs:step1-define-services]
-   :dedent:
-
-``SQLiteDatabase`` owns ``database_path``; ``UserRepository`` has no knowledge of the
-database layer — it only declares ``connection: sqlite3.Connection`` as a parameter
-and receives it automatically from the composed scope.
-
-
-Step 2 — Layer cross-cutting concerns with ``@patch`` and ``@merge``
---------------------------------------------------------------------
-
-``@patch`` wraps an existing resource value with a transformation. This lets an
-add-on scope modify a value without touching the scope that defined it — the same
-idea as pytest's ``monkeypatch``, but composable.
-
-.. literalinclude:: ../../tests/test_readme_examples.py
-   :language: python
-   :start-after: # [docs:step2-patch]
-   :end-before: # [/docs:step2-patch]
-   :dedent:
-
-When several independent scopes each contribute a piece to the same resource, use
-``@merge`` to define how the contributions are aggregated:
-
-.. literalinclude:: ../../tests/test_readme_examples.py
-   :language: python
-   :start-after: # [docs:step2-merge]
-   :end-before: # [/docs:step2-merge]
-   :dedent:
-
-A ``@patch`` can itself declare ``@extern`` dependencies, which are injected like any
-other resource:
-
-.. literalinclude:: ../../tests/test_readme_examples.py
-   :language: python
-   :start-after: # [docs:step2-patch-extern]
-   :end-before: # [/docs:step2-patch-extern]
-   :dedent:
-
-
-Step 3 — Force evaluation at startup with ``@eager``
------------------------------------------------------
-
-All resources are lazy by default: computed on first access, then cached for the
-lifetime of the scope. Mark a resource ``@eager`` to evaluate it immediately when
-``evaluate()`` returns — useful for schema migrations or connection pre-warming that
-must complete before the application starts serving requests:
-
-.. literalinclude:: ../../tests/test_readme_examples.py
-   :language: python
-   :start-after: # [docs:step3-eager]
-   :end-before: # [/docs:step3-eager]
-   :dedent:
-
-Without ``@eager``, the ``CREATE TABLE`` would not run until ``root.connection`` is first
-accessed.
-
-
-Step 4 — App scope vs request scope
-------------------------------------
-
-So far all resources have had application lifetime: created once at startup and
-reused for every request. Real applications also need per-request resources — values
-that must be created fresh for each incoming request and discarded when it completes.
-
-A nested ``@scope`` named ``RequestScope`` serves as a per-request factory. The
-framework injects it by name as a ``Callable``; calling
-``RequestScope(request=handler)`` returns a fresh instance.
-
-The application below has four scopes, each owning only its own concern:
-
-- **SQLiteDatabase** — owns ``database_path``, provides ``connection``
-- **UserRepository** — business logic; owns ``user_count`` and per-request ``current_user``
-- **HttpHandlers** — HTTP layer; owns per-request ``user_id``, ``response_body``, ``response_sent``
-- **NetworkServer** — network layer; owns ``host``/``port``, creates the ``HTTPServer``
-
-``UserRepository.RequestScope`` and ``HttpHandlers.RequestScope`` are composed into a
-single ``RequestScope`` by the union mount. ``user_id`` (extracted from the HTTP path
-by ``HttpHandlers.RequestScope``) flows automatically into ``current_user`` (looked up
-in the DB by ``UserRepository.RequestScope``) without any glue code.
-
-``response_sent`` is an IO resource: it sends the HTTP response as a side effect and
-returns ``None``. The handler body is a single attribute access — all logic lives in
-the DI graph. In an async framework (e.g. FastAPI), return an ``asyncio.Task[None]``
-instead of a coroutine, which cannot be safely awaited in multiple dependents.
-
-.. code-block:: python
-
-   import threading
-   import urllib.request
-   from http.server import BaseHTTPRequestHandler, HTTPServer
-   from types import ModuleType
-
-   from mixinv2 import LexicalReference, extend
-
-   @scope
-   class SQLiteDatabase:
-       @extern
-       def database_path() -> str: ...      # database owns its own config
-
-       # App-scoped: one connection for the entire process lifetime.
-       # check_same_thread=False: created in main thread, used in handler threads.
-       @public
-       @resource
-       def connection(database_path: str) -> sqlite3.Connection:
-           db = sqlite3.connect(database_path, check_same_thread=False)
-           db.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")
-           db.execute("INSERT INTO users VALUES (1, 'alice')")
-           db.execute("INSERT INTO users VALUES (2, 'bob')")
-           db.commit()
-           return db
-
-   @scope
-   class UserRepository:
-       @extern
-       def connection() -> sqlite3.Connection: ...
-
-       # @scope as a composable dataclass — fields are @extern, constructed via DI.
-       @public
-       @scope
-       class User:
-           @public
-           @extern
-           def user_id() -> int: ...
-
-           @public
-           @extern
-           def name() -> str: ...
-
-       # App-scoped: total count, computed once.
-       @public
-       @resource
-       def user_count(connection: sqlite3.Connection) -> int:
-           (count,) = connection.execute("SELECT COUNT(*) FROM users").fetchone()
-           return count
-
-       # Request-scoped: per-request DB resources.
-       @public
-       @scope
-       class RequestScope:
-           @extern
-           def user_id() -> int: ...        # provided by HttpHandlers.RequestScope
-
-           @public
-           @resource
-           def current_user(
-               connection: sqlite3.Connection, user_id: int, User: Callable
-           ) -> object:
-               row = connection.execute(
-                   "SELECT id, name FROM users WHERE id = ?", (user_id,)
-               ).fetchone()
-               assert row is not None, f"no user with id={user_id}"
-               identifier, name = row
-               return User(user_id=identifier, name=name)
-
-   @scope
-   class HttpHandlers:
-       # RequestScope is nested because its lifetime is per-request,
-       # not per-application.
-       @public
-       @scope
-       class RequestScope:
-           @extern
-           def request() -> BaseHTTPRequestHandler: ...
-
-           # user_id is extracted from the request and injected into
-           # UserRepository.RequestScope.current_user automatically.
-           @public
-           @resource
-           def user_id(request: BaseHTTPRequestHandler) -> int:
-               return int(request.path.split("/")[-1])
-
-           # current_user and user_count resolved from their respective scopes.
-           @public
-           @resource
-           def response_body(user_count: int, current_user: object) -> bytes:
-               return f"total={user_count} current={current_user.name}".encode()
-
-           # IO resource: sends the HTTP response as a side effect.
-           @public
-           @resource
-           def response_sent(
-               request: BaseHTTPRequestHandler,
-               response_body: bytes,
-           ) -> None:
-               request.send_response(200)
-               request.end_headers()
-               request.wfile.write(response_body)
-
-   @scope
-   class NetworkServer:
-       @extern
-       def host() -> str: ...               # network layer owns its own config
-
-       @extern
-       def port() -> int: ...
-
-       # RequestScope is injected by name as a Callable (StaticScope).
-       # Calling RequestScope(request=handler) returns a fresh InstanceScope.
-       @public
-       @resource
-       def server(host: str, port: int, RequestScope: Callable) -> HTTPServer:
-           class Handler(BaseHTTPRequestHandler):
-               def do_GET(self) -> None:
-                   RequestScope(request=self).response_sent
-
-           return HTTPServer((host, port), Handler)
-
-   # Declare composition via @extend — each scope only knows its own config.
-   @extend(
-       LexicalReference(path=("SQLiteDatabase",)),
-       LexicalReference(path=("UserRepository",)),
-       LexicalReference(path=("HttpHandlers",)),
-       LexicalReference(path=("NetworkServer",)),
-   )
-   @public
-   @scope
-   class app:
-       pass
-
-   # Assemble into a module and evaluate — composition is declared above, not here.
-   myapp = ModuleType("myapp")
-   myapp.SQLiteDatabase = SQLiteDatabase
-   myapp.UserRepository = UserRepository
-   myapp.HttpHandlers = HttpHandlers
-   myapp.NetworkServer = NetworkServer
-   myapp.app = app
-
-   root = evaluate(myapp, modules_public=True).app(
-       database_path="/var/lib/myapp/prod.db",
-       host="127.0.0.1",
-       port=8080,
-   )
-   server = root.server
-
-Swapping to a test configuration is just different kwargs; no scope or composition changes:
-
-.. code-block:: python
-
-   test_root = evaluate(myapp, modules_public=True).app(
-       database_path=":memory:",  # fresh, isolated database for each test
-       host="127.0.0.1",
-       port=0,                    # OS assigns a free port
-   )
-   # test_root.connection  → sqlite3.Connection to :memory:
-   # test_root.server      → HTTPServer on OS-assigned port
-
-
-Decorator reference
--------------------
-
-.. list-table::
-   :header-rows: 1
-   :widths: 25 75
-
-   * - Decorator
-     - Purpose
-   * - ``@scope``
-     - Define a DI container (class) or sub-namespace
-   * - ``@resource``
-     - Declare a lazily-computed value; parameters are injected by name
-   * - ``@public``
-     - Expose a ``@resource`` or ``@scope`` to external callers
-   * - ``@extern``
-     - Declare a required dependency that must come from the composed scope
-   * - ``@patch``
-     - Provide a transformation that wraps an existing resource
-   * - ``@patch_many``
-     - Like ``@patch`` but yields multiple transformations at once
-   * - ``@merge``
-     - Define how patches are aggregated (e.g. ``frozenset``, ``list``, custom reducer)
-   * - ``@eager``
-     - Force evaluation at scope creation rather than on first access
-   * - ``@extend(*refs)``
-     - Inherit from other scopes explicitly (for package-level union mounts)
-   * - ``evaluate(*scopes)``
-     - Resolve and union-mount one or more scopes into a single dependency graph
-
-
-Python modules as scopes
--------------------------
-
-The ``@scope`` classes above are a teaching convenience — the real-world style is
-plain Python modules, just like pytest fixtures don't require a class. Every
-``@scope`` class maps directly to a module file; pass it to ``evaluate()`` the same
-way:
-
-.. code-block:: python
-
-   import sqlite_database   # sqlite_database.py with @extern / @resource / @public
-   import user_repository   # user_repository/ package
-
-The same decorators work on module-level functions exactly as on class methods. A
-subpackage becomes a nested scope — ``user_repository/request_scope/`` is the
-module equivalent of a nested ``@scope class RequestScope``.
-
-Use ``@extend`` in a package's ``__init__.py`` to declare the composition, then
-``evaluate()`` receives the single package:
-
-.. literalinclude:: ../../tests/fixtures/app_di/__init__.py
-   :language: python
-   :start-after: # [docs:module-extend]
-   :end-before: # [/docs:module-extend]
-
-.. code-block:: python
-
-   import myapp
-
-   root = evaluate(myapp, modules_public=True).app(database_path=":memory:")
-
-Runnable module-based equivalents of all tutorial examples are in
-:github:`tests/test_readme_package_examples.py`,
-using the fixture package at
-:github:`tests/fixtures/app_di/`.