adiumentum 0.1.1__py3-none-any.whl → 0.3.1__py3-none-any.whl

adiumentum/pydantic_extensions.md

@@ -0,0 +1,839 @@
+# pydantic_extensions
+
+```py
+# BaseModel methods:
+ms = [
+ ("_CHECK SIGNATURE",      "model_dump_json"),
+ ("_CHECK SIGNATURE",      "model_dump"),
+ ("_CHECK SIGNATURE",      "model_json_schema"),
+ ("_CHECK SIGNATURE",      "model_validate_json"),
+ ("_CHECK SIGNATURE",      "model_validate"),
+ ("_CHECK SIGNATURE",      "schema_json"),
+ ("_CHECK SIGNATURE",      "schema"),
+ ("_TODO needed?",         "model_post_init"),
+ ("_TODO needed?",         "model_rebuild"),
+ ("_TODO",                 "__repr__"),
+ ("_TODO",                 "__str__"),
+ ("_TODO",                 "model_config"),
+ ("_TODO",                 "model_construct"),
+ ("_TODO",                 "model_copy"),
+ ("_TODO",                 "model_validate_strings"),
+ ("(?) later as needed",  "__pretty__"),
+ ("(?) later as needed",  "__pydantic_complete__"),
+ ("(?) later as needed",  "__pydantic_computed_fields__"),
+ ("(?) later as needed",  "__pydantic_core_schema__"),
+ ("(?) later as needed",  "__pydantic_custom_init__"),
+ ("(?) later as needed",  "__pydantic_decorators__"),
+ ("(?) later as needed",  "__pydantic_extra__"),
+ ("(?) later as needed",  "__pydantic_fields__"),
+ ("(?) later as needed",  "__pydantic_fields_set__"),
+ ("(?) later as needed",  "__pydantic_generic_metadata__"),
+ ("(?) later as needed",  "__pydantic_init_subclass__"),
+ ("(?) later as needed",  "__pydantic_parent_namespace__"),
+ ("(?) later as needed",  "__pydantic_post_init__"),
+ ("(?) later as needed",  "__pydantic_private__"),
+ ("(?) later as needed",  "__pydantic_root_model__"),
+ ("(?) later as needed",  "__pydantic_serializer__"),
+ ("(?) later as needed",  "__pydantic_setattr_handlers__"),
+ ("(?) later as needed",  "__pydantic_validator__"),
+ ("(?) later as needed",  "_iter"),
+ ("(?) later as needed", "__fields__"),
+ ("(?) later as needed",  "__dict__"), # return self or self.__class__(kmap(str, self))?
+ ("(?) later as needed", "__abstractmethods__"),
+ ("(?) later as needed", "__class_vars__"),
+ ("(?) later as needed", "__copy__"),
+ ("(?) later as needed", "__deepcopy__"),
+ ("(?) later as needed", "__fields__"),
+ ("(?) later as needed", "__fields_set__"),
+ ("(?) later as needed", "__getstate__"),
+ ("(?) later as needed", "__reduce__"),
+ ("(?) later as needed", "__reduce_ex__"),
+ ("(?) later as needed", "__replace__"),
+ ("(?) later as needed", "__setstate__"),
+ ("(?) later as needed", "__signature__"),
+ ("(?) later as needed", "__weakref__"),
+ ("(?) later as needed", "_abc_impl"),
+ ("(?) later as needed", "_setattr_handler"),
+ ("(?) not needed?",     "__repr_args__"),
+ ("(?) not needed?",     "__repr_name__"),
+ ("(?) not needed?",     "__repr_recursion__"),
+ ("(?) not needed?",     "__repr_str__"),
+ ("(?) not needed?",     "__rich_repr__"),
+ ("(?) not needed?",     "_copy_and_set_values"),
+ ("(?) not needed?",     "_get_value"),
+ ("(?) not needed?",     "model_parametrized_name"),
+ ("(?) not needed?",     "__class_getitem__"),  # available in TypeAdapter
+ ("(?) not needed?",     "__private_attributes__"),
+ ("✔ builtin?",          "__sizeof__"),
+ ("✔ builtin?",          "__slots__"),
+ ("✔ builtin",           "__class__"),
+ ("✔ builtin",           "__delattr__"),
+ ("✔ builtin",           "__dir__"),
+ ("✔ builtin",           "__doc__"),
+ ("✔ builtin",           "__module__"),
+ ("✔ builtin",           "__subclasshook__"),
+ ("✔ deprecated",        "construct"),
+ ("✔ deprecated",        "copy"),
+ ("✔ deprecated",        "dict"),
+ ("✔ deprecated",        "json"),
+ ("✔ deprecated",        "model_fields"),
+ ("✔ deprecated",        "parse_file"),
+ ("✔ deprecated",        "parse_obj"),
+ ("✔ deprecated",        "parse_raw"),
+ ("✔ deprecated",        "update_forward_refs"),
+ ("✔ deprecated",        "validate"),
+ ("✔ inherited?",        "__new__"),
+ ("✔ inherited",         "__eq__"),
+ ("✔ inherited",         "__format__"),
+ ("✔ inherited",         "__ge__"),
+ ("✔ inherited",         "__getattr__"),
+ ("✔ inherited",         "__getattribute__"),
+ ("✔ inherited",         "__gt__"),
+ ("✔ inherited",         "__hash__"),
+ ("✔ inherited",         "__init__"),
+ ("✔ inherited",         "__init_subclass__"),
+ ("✔ inherited",         "__iter__"),
+ ("✔ inherited",         "__le__"),
+ ("✔ inherited",         "__lt__"),
+ ("✔ inherited",         "__ne__"),
+ ("✔ inherited",         "__setattr__"),
+ ("✔ not needed?",       "_calculate_keys"),
+ ("✔ not needed?",       "model_computed_fields"),
+ ("✔ not needed",        "from_orm"),
+ ("✔ not needed",        "model_fields_set"),
+ ("✔",                   "__annotations__"),
+ ("✔",                   "__get_pydantic_core_schema__"),
+ ("✔",                   "__get_pydantic_json_schema__"),
+ ("✔",                   "model_extra"),
+]
+
+type_adapter_methods_unique = [
+    "__final__",  #
+    "__orig_bases__",  #
+    "__parameters__",  #
+    "_config",  #
+    "_defer_build",  #
+    "_fetch_parent_frame",  #
+    "_init_core_attrs",  #
+    "_model_config",  #
+    "_module_name",  #
+    "_parent_depth",  #
+    "_type",  #
+    "core_schema",  #
+    "dump_json",  # TODO: use
+    "dump_python",  #
+    "get_default_value",  #
+    "json_schema",  #
+    "json_schemas",  #
+    "pydantic_complete",  #
+    "rebuild",  #
+    "serializer",  #
+    "validate_json",  #
+    "validate_python",  #
+    "validate_strings",  #
+    "validator",  #
+]
+
+type_adapter_methods = [
+    "__annotations__",
+    "__class__",
+    "__class_getitem__",
+    "__delattr__",
+    "__dict__",
+    "__dir__",
+    "__doc__",
+    "__eq__",
+    "__final__",
+    "__format__",
+    "__ge__",
+    "__getattribute__",
+    "__getstate__",
+    "__gt__",
+    "__hash__",
+    "__init__",
+    "__init_subclass__",
+    "__le__",
+    "__lt__",
+    "__module__",
+    "__ne__",
+    "__new__",
+    "__orig_bases__",
+    "__parameters__",
+    "__reduce__",
+    "__reduce_ex__",
+    "__repr__",
+    "__setattr__",
+    "__sizeof__",
+    "__str__",
+    "__subclasshook__",
+    "__weakref__",
+    "_config",
+    "_defer_build",
+    "_fetch_parent_frame",
+    "_init_core_attrs",
+    "_model_config",
+    "_module_name",
+    "_parent_depth",
+    "_type",
+    "core_schema",
+    "dump_json",
+    "dump_python",
+    "get_default_value",
+    "json_schema",
+    "json_schemas",
+    "pydantic_complete",
+    "rebuild",
+    "serializer",
+    "validate_json",
+    "validate_python",
+    "validate_strings",
+    "validator",
+]
+```
+
+
+
+## Discussion
+
+Excellent question — this touches on a subtle interaction between **generic custom containers**, **`pydantic`’s validation model**, and **Python’s typing system**.
+
+Let’s go step by step.
+
+---
+
+### 🧩 Goal
+
+You want a generic class
+
+```python
+class BaseDict(Generic[K, V]): ...
+```
+
+that:
+
+1. Behaves like a `dict[K, V]`
+2. Uses `pydantic.TypeAdapter` for validation
+3. Can appear **as a field in a `BaseModel`**, e.g.:
+
+   ```python
+   class MyModel(BaseModel):
+          mapping: MyDict[str, int]
+   ```
+
+---
+
+### ✅ What Pydantic Expects
+
+Pydantic (v2.x) uses the [`__get_pydantic_core_schema__`](https://docs.pydantic.dev/latest/api/functional_validators/#pydantic.get_pydantic_core_schema) and `__get_pydantic_json_schema__` protocols to understand custom classes.
+
+However, **for simple generic containers that are “dict-like”**, you don’t need the full schema hooks if you make your class implement the *minimum dict interface* that pydantic recognizes as “mapping-like”.
+
+---
+
+### ✅ Required Methods for Dict Compatibility
+
+To be treated like a `dict` (and for `TypeAdapter` to use your generic parameters), your class must implement at least these:
+
+| Method                            | Purpose                          | Required by                     |
+| --------------------------------- | -------------------------------- | ------------------------------- |
+| `__init__(self, *args, **kwargs)` | Accepts dict-like initialization | general                         |
+| `__getitem__(self, key)`          | Retrieve an item                 | Mapping protocol                |
+| `__setitem__(self, key, value)`   | Set an item                      | MutableMapping                  |
+| `__delitem__(self, key)`          | Delete an item                   | MutableMapping                  |
+| `__iter__(self)`                  | Iterate over keys                | Mapping protocol                |
+| `__len__(self)`                   | Number of keys                   | Mapping protocol                |
+| `items(self)`                     | Return key-value pairs           | Used by validators, serializers |
+| `keys(self)`                      | Return keys                      | Used by validators, serializers |
+| `values(self)`                    | Return values                    | Optional but expected           |
+| `__contains__(self, key)`         | For `in` checks                  | optional but standard           |
+| `__repr__(self)`                  | For debug clarity                | recommended                     |
+
+You can get most of this automatically by subclassing `collections.abc.MutableMapping`:
+
+```python
+from collections.abc import MutableMapping
+from typing import Generic, TypeVar
+from pydantic import TypeAdapter
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+
+class BaseDict(MutableMapping[K, V], Generic[K, V]):
+    def __init__(self, data=None):
+        self._data = dict(data or {})
+        # Validate with TypeAdapter if desired:
+        if data is not None:
+            adapter = TypeAdapter(dict[K, V])
+            self._data = adapter.validate_python(data)
+
+    def __getitem__(self, key: K) -> V:
+        return self._data[key]
+
+    def __setitem__(self, key: K, value: V) -> None:
+        self._data[key] = value
+
+    def __delitem__(self, key: K) -> None:
+        del self._data[key]
+
+    def __iter__(self):
+        return iter(self._data)
+
+    def __len__(self):
+        return len(self._data)
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}({self._data!r})"
+```
+
+---
+
+### ✅ Making It Work Inside a `BaseModel`
+
+When you define:
+
+```python
+class MyDict(BaseDict[str, int]):
+    pass
+
+
+class MyModel(BaseModel):
+    mapping: MyDict
+```
+
+Pydantic v2 will use your `BaseDict`’s `__init__` and type hints to validate `mapping` automatically — because `BaseDict` behaves like a `dict`.
+
+If you want to **control schema generation** (e.g., for OpenAPI or JSON schema), you can also implement:
+
+```python
+def __get_pydantic_core_schema__(cls, source_type, handler):
+    # delegate to dict but keep your class name
+    return handler(dict)
+```
+
+but that’s optional unless you need advanced integration.
+
+---
+
+### ✅ Summary
+
+To include subclasses of `BaseDict` as values inside a `BaseModel`:
+
+**You must implement (or inherit) the dict interface**, i.e.:
+
+```python
+__getitem__, __setitem__, __delitem__, __iter__, __len__
+```
+
+Optionally add:
+
+```python
+items, keys, values, __contains__, __repr__
+```
+
+and optionally define:
+
+```python
+__get_pydantic_core_schema__  # for full control
+__get_pydantic_json_schema__  # for schema export
+```
+
+If you subclass `collections.abc.MutableMapping`, you automatically satisfy this, and Pydantic will happily treat your class as a `dict`-like field.
+
+---
+
+Perfect — here’s how to make your `BaseDict[K, V]` actually *validate* keys and values using **Pydantic’s `TypeAdapter`**, so that it works transparently both:
+
+* when used *directly* (e.g. `BaseDict[str, int]({"a": 1})`), and
+* when embedded in a **`BaseModel` field** (e.g. `MyModel(mapping={"a": "1"})` → coerced to `int`).
+
+---
+
+## ✅ Step 1. The Generic `BaseDict` Class
+
+```python
+from __future__ import annotations
+from collections.abc import MutableMapping
+from typing import Generic, TypeVar, Any
+from pydantic import TypeAdapter
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+
+class BaseDict(MutableMapping[K, V], Generic[K, V]):
+    """A dict-like container with per-key/value validation via Pydantic."""
+
+    def __init__(self, data: Any | None = None):
+        self._data: dict[K, V] = {}
+        if data is not None:
+            # TypeAdapter for the full mapping type
+            adapter = TypeAdapter(dict[K, V])
+            # Will coerce + validate all keys and values
+            self._data = adapter.validate_python(data)
+
+    # --- Mapping protocol ---
+    def __getitem__(self, key: K) -> V:
+        return self._data[key]
+
+    def __setitem__(self, key: K, value: V) -> None:
+        # validate each key/value pair on assignment
+        key_adapter = TypeAdapter(K)
+        val_adapter = TypeAdapter(V)
+        k = key_adapter.validate_python(key)
+        v = val_adapter.validate_python(value)
+        self._data[k] = v
+
+    def __delitem__(self, key: K) -> None:
+        del self._data[key]
+
+    def __iter__(self):
+        return iter(self._data)
+
+    def __len__(self):
+        return len(self._data)
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}({self._data!r})"
+
+    # --- Optional convenience ---
+    def to_dict(self) -> dict[K, V]:
+        """Return a plain dict for serialization or JSON export."""
+        return dict(self._data)
+```
+
+---
+
+## ✅ Step 2. Using It as a Base Type
+
+You can now subclass it for specific key/value types:
+
+```python
+class StrIntDict(BaseDict[str, int]):
+    pass
+```
+
+And it already works with `TypeAdapter`:
+
+```python
+adapter = TypeAdapter(StrIntDict)
+validated = adapter.validate_python({"a": "42"})
+print(validated)  # StrIntDict({'a': 42})
+print(type(validated))  # <class '__main__.StrIntDict'>
+```
+
+The `"42"` string is converted to `int(42)` automatically.
+
+---
+
+## ✅ Step 3. Using It Inside a Pydantic Model
+
+```python
+from pydantic import BaseModel
+
+
+class MyModel(BaseModel):
+    mapping: StrIntDict
+
+
+m = MyModel(mapping={"x": "100"})
+print(m.mapping)  # StrIntDict({'x': 100})
+print(type(m.mapping))  # <class '__main__.StrIntDict'>
+```
+
+Everything works seamlessly — Pydantic recognizes it as a dict-like container.
+
+---
+
+## ✅ Step 4. Extending Validation Logic (Optional)
+
+You can further specialize validation by overriding `__setitem__` or defining custom methods:
+
+```python
+class PositiveIntDict(BaseDict[str, int]):
+    def __setitem__(self, key: str, value: int):
+        value = TypeAdapter(int).validate_python(value)
+        if value <= 0:
+            raise ValueError("All values must be positive integers")
+        super().__setitem__(key, value)
+```
+
+Then:
+
+```python
+PositiveIntDict({"a": 1, "b": -2})  # → raises ValidationError
+```
+
+---
+
+## ✅ Step 5. (Optional) Schema Control
+
+If you want the schema for OpenAPI / JSONSchema to show up correctly, you can include:
+
+```python
+@classmethod
+def __get_pydantic_core_schema__(cls, source_type, handler):
+    # Delegate to dict’s schema but use our own class for construction
+    schema = handler(dict)
+    schema["cls"] = cls
+    return schema
+```
+
+This step isn’t necessary for normal validation, only for schema generation.
+
+---
+
+### ✨ Summary
+
+✅ For full Pydantic integration:
+
+* Implement `MutableMapping` (as above)
+* Use `TypeAdapter(dict[K, V])` for validating constructor input
+* Optionally use `TypeAdapter(K)` / `TypeAdapter(V)` in `__setitem__` for incremental validation
+* Subclasses automatically work in `BaseModel`s
+
+---
+
+Perfect — this is the last piece of the puzzle.
+Let’s make your `BaseDict` **dump cleanly into JSON** when used inside a Pydantic model — without needing custom encoders or post-processing.
+
+---
+
+## 🧩 Goal
+
+Given this model:
+
+```python
+class MyModel(BaseModel):
+    mapping: StrIntDict
+```
+
+we want:
+
+```python
+MyModel(mapping={"x": 1}).model_dump_json()
+```
+
+to produce:
+
+```json
+{"mapping": {"x": 1}}
+```
+
+and *not* something like
+`{"mapping": "StrIntDict({'x': 1})"}` or a nested object.
+
+---
+
+## ✅ Approach
+
+We can make this work automatically by:
+
+1. Implementing the **`__iter__` and `.items()`** methods properly (Pydantic already looks for those when dumping objects that behave like dicts);
+2. Optionally adding a **`__get_pydantic_json_schema__`** hook for schema correctness;
+3. Implementing **`__iter__` → yields key-value pairs** and **`__getitem__`** properly (already done);
+4. Defining **`__getattr__` or `__getstate__`** is *not* needed;
+5. For extra clarity, you can also define `__pydantic_serializer__` but it’s not necessary here.
+
+---
+
+## ✅ Minimal Change Version (works out of the box)
+
+If you use the earlier implementation of `BaseDict` that subclasses `MutableMapping` and returns a plain `dict` from `.to_dict()`, **it already serializes correctly**:
+
+```python
+from pydantic import BaseModel
+import json
+
+
+class StrIntDict(BaseDict[str, int]):
+    pass
+
+
+class MyModel(BaseModel):
+    mapping: StrIntDict
+
+
+m = MyModel(mapping={"a": "42"})
+print(m.model_dump())  # {'mapping': {'a': 42}}
+print(m.model_dump_json())  # {"mapping":{"a":42}}
+```
+
+That’s it. ✅
+Because Pydantic’s serializer recognizes anything implementing `collections.abc.Mapping`.
+
+---
+
+## ✅ Optional Explicit Serializer (for clarity)
+
+If you prefer to be explicit (especially if you add custom attributes to `BaseDict`), you can define a Pydantic serialization hook:
+
+```python
+from pydantic import GetCoreSchemaHandler, GetJsonSchemaHandler
+from pydantic_core import core_schema
+
+
+class BaseDict(MutableMapping[K, V], Generic[K, V]):
+    ...
+    # (all previous methods unchanged)
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, source_type: Any, handler: GetCoreSchemaHandler
+    ) -> core_schema.CoreSchema:
+        # This makes Pydantic serialize your class like a dict
+        return core_schema.no_info_after_validator_function(
+            cls,  # after validation, return instance
+            handler(dict),  # validate using dict schema
+        )
+
+    @classmethod
+    def __get_pydantic_json_schema__(
+        cls, core_schema: core_schema.CoreSchema, handler: GetJsonSchemaHandler
+    ):
+        # Delegate schema generation to dict
+        json_schema = handler(core_schema)
+        json_schema.update(type="object")
+        return json_schema
+```
+
+Now your class will both **validate** and **serialize** as a mapping, but still **preserve its type** inside Python.
+
+---
+
+## ✅ Final Example
+
+```python
+from pydantic import BaseModel
+
+
+class StrIntDict(BaseDict[str, int]):
+    pass
+
+
+class MyModel(BaseModel):
+    mapping: StrIntDict
+
+
+m = MyModel(mapping={"a": "42"})
+print(m)  # mapping=StrIntDict({'a': 42})
+
+print(m.model_dump())
+# → {'mapping': {'a': 42}}
+
+print(m.model_dump_json(indent=2))
+# → {
+#       "mapping": {
+#         "a": 42
+#       }
+#   }
+```
+
+---
+
+## ✅ Summary
+
+| Goal                                     | Solution                                              |
+| ---------------------------------------- | ----------------------------------------------------- |
+| Include dict-like custom types in models | Subclass `MutableMapping`                             |
+| Validate keys/values                     | Use `TypeAdapter(dict[K, V])` or per-key adapters     |
+| Work inside `BaseModel`                  | Implement `__getitem__`, `__iter__`, `__len__`        |
+| Serialize to JSON cleanly                | Ensure Mapping interface; optionally add schema hooks |
+| Keep Python type fidelity                | Return instance from `__get_pydantic_core_schema__`   |
+
+---
+
+Excellent — this is a great enhancement.
+You’ll end up with a `BaseDict` that not only validates its contents, but also produces *precise error reports*, e.g.:
+
+```
+pydantic_core._pydantic_core.ValidationError: 1 validation error for StrIntDict
+mapping.a
+  Value error, not a positive integer [type=value_error, input_value='-2', ...]
+```
+
+Let's go step by step.
+
+---
+
+## ✅ Design Goal
+
+We want:
+
+1. Each key/value pair to be validated individually.
+2. If any pair fails, Pydantic should raise a standard `ValidationError` listing which key caused the problem.
+3. Work both when constructed directly and inside a `BaseModel`.
+
+---
+
+## ✅ Implementation: Detailed Error Tracking
+
+```python
+from __future__ import annotations
+from collections.abc import MutableMapping
+from typing import Any, Generic, TypeVar
+from pydantic import TypeAdapter, ValidationError
+from pydantic_core import ErrorDetails
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+
+class BaseDict(MutableMapping[K, V], Generic[K, V]):
+    """A dict-like container that validates its contents with Pydantic and
+    reports per-key errors when validation fails."""
+
+    def __init__(self, data: Any | None = None):
+        self._data: dict[K, V] = {}
+        if data is not None:
+            self._data = self._validate_all(data)
+
+    def _validate_all(self, data: Any) -> dict[K, V]:
+        """Validate all items and collect individual key/value errors."""
+        key_adapter = TypeAdapter(K)
+        val_adapter = TypeAdapter(V)
+
+        validated: dict[K, V] = {}
+        errors: list[ErrorDetails] = []
+
+        # We accept any mapping-like object
+        try:
+            items = data.items()
+        except AttributeError:
+            raise TypeError(f"Expected a mapping, got {type(data).__name__}")
+
+        for key, value in items:
+            try:
+                k = key_adapter.validate_python(key)
+                v = val_adapter.validate_python(value)
+                validated[k] = v
+            except ValidationError as e:
+                # Reformat to make it clear which key failed
+                for err in e.errors():
+                    err["loc"] = ("mapping", key, *err["loc"])
+                    errors.append(err)
+
+        if errors:
+            raise ValidationError.from_exception_data(self.__class__.__name__, errors)
+
+        return validated
+
+    # --- Mapping protocol ---
+    def __getitem__(self, key: K) -> V:
+        return self._data[key]
+
+    def __setitem__(self, key: K, value: V) -> None:
+        # Validate per-item on assignment
+        try:
+            k = TypeAdapter(K).validate_python(key)
+            v = TypeAdapter(V).validate_python(value)
+            self._data[k] = v
+        except ValidationError as e:
+            raise ValidationError.from_exception_data(
+                self.__class__.__name__,
+                [{"loc": ("mapping", key, *err["loc"]), **err} for err in e.errors()],
+            )
+
+    def __delitem__(self, key: K) -> None:
+        del self._data[key]
+
+    def __iter__(self):
+        return iter(self._data)
+
+    def __len__(self):
+        return len(self._data)
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}({self._data!r})"
+
+    def to_dict(self) -> dict[K, V]:
+        return dict(self._data)
+```
+
+---
+
+## ✅ Example: Subclass with Constraints
+
+```python
+class PositiveIntDict(BaseDict[str, int]):
+    def __setitem__(self, key, value):
+        v = TypeAdapter(int).validate_python(value)
+        if v <= 0:
+            raise ValidationError.from_exception_data(
+                self.__class__.__name__,
+                [
+                    {
+                        "type": "value_error",
+                        "loc": ("mapping", key),
+                        "msg": "must be positive",
+                        "input": value,
+                    }
+                ],
+            )
+        super().__setitem__(key, v)
+```
+
+---
+
+## ✅ Example Usage
+
+```python
+from pydantic import BaseModel
+
+
+class MyModel(BaseModel):
+    mapping: PositiveIntDict
+
+
+try:
+    m = MyModel(mapping={"a": 1, "b": "-3"})
+except ValidationError as e:
+    print(e)
+```
+
+**Output:**
+
+```
+1 validation error for MyModel
+mapping.b
+  must be positive [type=value_error, input_value='-3', input_type=str]
+```
+
+Each error points exactly to the failing key.
+
+---
+
+## ✅ Explanation
+
+* We use `TypeAdapter(K)` and `TypeAdapter(V)` separately so that **keys and values** each get their own type coercion and validation.
+* If any validation fails, we collect structured errors using `pydantic.ValidationError.errors()`.
+* We inject a meaningful `"loc"` (location path) like `("mapping", key)` for each problematic entry — this is what makes Pydantic’s error output precise.
+
+---
+
+## ✅ Works Inside Models Too
+
+This integrates seamlessly with any `BaseModel` field — Pydantic wraps any internal `ValidationError` raised by the constructor and merges it with the model’s error output.
+
+```python
+class M(BaseModel):
+    data: PositiveIntDict
+
+
+M(data={"a": 1, "b": 0})
+# → raises ValidationError with path: data.b
+```
+
+---
+
+## ✅ Summary
+
+| Feature                     | Implementation                                    |
+| --------------------------- | ------------------------------------------------- |
+| Per-key/value validation    | `TypeAdapter(K)` + `TypeAdapter(V)`               |
+| Aggregated error reporting  | Collect errors and raise single `ValidationError` |
+| Compatible with `BaseModel` | Works transparently                               |
+| Clear error location        | Each error labeled by failing key                 |
+| JSON-safe serialization     | Already works as a `Mapping`                      |
+
+---