Merge pull request #25 from joshorr/josho/excluded-auto-partial-fields

feat: add way to exclude specific fields from auto partials.

Author: joshorr

README.md

@@ -11,8 +11,8 @@
 
 An easy way to add or create partials for Pydantic models.
 
-![PythonSupport](https://img.shields.io/static/v1?label=python&message=%203.10|%203.11|%203.12&color=blue?style=flat-square&logo=python)
-![PyPI version](https://badge.fury.io/py/xmodel.svg?)
+[![PythonSupport](https://img.shields.io/static/v1?label=python&message=%203.10|%203.11|%203.12&color=blue?style=flat-square&logo=python)](https://pypi.org/project/pydantic-partials/)
+[![PyPI version](https://badge.fury.io/py/pydantic_partials.svg?)](https://pypi.org/project/pydantic-partials/)
 
 ## Documentation
 
@@ -136,8 +136,61 @@ Notice that if a field has a default value, it's used instead of marking it as `
 Also, the `Missing` sentinel value is a separate value vs `None`, allowing one to easily
 know if a value is truly just missing or is `None`/`Null`.
 
+### Exclude Fields From Auto Partials
 
-### Automatic Partials Configuration
+You can exclude specific fields from the automatic partials via these means:
+
+- `AutoPartialExclude[...]`
+  - This puts a special `Annotated` item on field to mark it as excluded.
+- `class PartialRequired(PartialModel, auto_partials_exclude={'id', 'created_at'}):`
+  - This way provides them via class argument `auto_partials_exclude`
+- Or via the standard `model_config`
+  - `model_config = {'auto_partials_exclude': {'id', 'created_at'}}`
+  - A dict, using `auto_partials_exclude` as the key and a set of field names as the value.
+
+Any of these methods are inheritable.
+You can override an excluded value by explicitly marking a field as Partial via `some_field: Partial[str]`
+
+Here is an example using the `AutoPartialExclude` method, also showing how it can inherit.
+
+```python
+from pydantic_partials import PartialModel, AutoPartialExclude, Missing
+from pydantic import BaseModel, ValidationError
+from datetime import datetime
+import pytest
+
+class PartialRequired(PartialModel):
+    id: AutoPartialExclude[str]
+    created_at: AutoPartialExclude[datetime]
+
+class TestModel(BaseModel):
+    id: str
+    created_at: datetime
+    name: str
+    value: str
+    some_null_by_default_field: str | None = None
+
+class PartialTestModel(TestModel, PartialRequired):
+    pass
+
+# Will raise validation error for the two fields excluded from auto-partials
+with pytest.raises(
+    ValidationError,
+    match=r'2 validation errors[\w\W]*'
+          r'id[\w\W]*Field required[\w\W]*'
+          r'created_at[\w\W]*Field required'
+):
+    PartialTestModel()
+
+# If we give them values, we get no ValidationError
+obj = PartialTestModel(id='some-value', created_at=datetime.now())
+
+# And fields have the expected values.
+assert obj.id == 'some-value'
+assert obj.name is Missing
+```
+
+### Auto Partials Configuration
 
 You can turn off automatically applying partials to all non-defaulted fields
 via `auto_partials` class argument or modeL_config option:

pydantic_partials/__init__.py

@@ -1,3 +1,3 @@
-from .partial import PartialModel, Partial
+from .partial import PartialModel, Partial, AutoPartialExclude
 from .config import PartialConfigDict
 from .sentinels import Missing, MissingType

pydantic_partials/config.py

@@ -26,3 +26,16 @@ class PartialConfigDict(ConfigDict):
         unless the user already a default value defined by user for field.
         This ensures that Pydantic won't require the field be assigned a value.
     """
+
+    auto_partials_exclude: set[str]
+    """ A set of field names to exclude from the `auto_partials` functionality.
+        
+        All parent classes `partials_exclude` string sets will be combined
+        together for a final exclusion list.
+        
+        Any partials set manually/directly via the fields annotation will still be a partial field
+        regardless if it's referenced in this `auto_partials_exclude` set or not. This only effects
+        the way automatic partials are applied.
+        
+        You can also use `pydantic_partials.partial.AutoPartialExclude` to more easily mark fields as excluded.
+    """

pydantic_partials/meta.py

@@ -1,5 +1,5 @@
 import typing
-from typing import Any, get_args, get_origin, TypeVar
+from typing import Any, get_args, get_origin, TypeVar, Iterable
 
 from pydantic import BaseModel
 
@@ -9,7 +9,7 @@
 from xsentinels.default import DefaultType
 
 from .config import PartialConfigDict
-from .sentinels import Missing, MissingType
+from .sentinels import Missing, MissingType, AutoPartialExcludeMarker
 
 from logging import getLogger
 
@@ -46,6 +46,7 @@ def __new__(
             *,
 
             auto_partials: bool | DefaultType = Default,
+            auto_partials_exclude: Iterable[str] | DefaultType = Default,
 
             # A private/internal detail for generic base subclasses that want to also change the fields,
             # this prevents having to rebuild the class a second time; if this is True then the subclass
@@ -62,6 +63,13 @@ def __new__(
                 If `True` (default): Will automatically make all fields on the model `Partial`.
                 If `False`: User needs to mark individual fields as `Partial` where they want.
 
+            auto_partials_exclude: A set of strings of field names to exclude from automatic partials.
+                If you explicitly mark a field as a Partial, this won't effect that. THis only effects
+                automatically applied partial fields.
+
+                You can also use `pydantic_partials.partial.AutoPartialExclude` to more easily mark fields as excluded.
+                For more details see `pydantic_partials.config.PartialConfigDict.auto_partials_exclude`.
+
             **kwargs: Passed along other class arguments to Pydantic and any __init_subclass__ methods.
         """
         # Create the class first...
@@ -74,19 +82,41 @@ def __new__(
         if auto_partials is not Default:
             cls.model_config['auto_partials'] = auto_partials
 
+        if auto_partials_exclude:
+            cls.model_config['auto_partials_exclude'] = set(auto_partials_exclude)
+
+        final_auto_exclude = cls.model_config.get('auto_partials_exclude', set())
+        for c in cls.__mro__:
+            parent_config = getattr(c, 'model_config', set())
+            if not parent_config:
+                continue
+
+            final_auto_exclude.update(parent_config.get('auto_partials_exclude', set()))
+
         need_rebuild = False
 
         partial_fields = set()
         for k, v in cls.model_fields.items():
             field_type = v.annotation
-            if get_origin(field_type) is None:
+            origin = get_origin(field_type)
+            if origin is None:
                 if field_type is MissingType:
                     partial_fields.add(k)
 
+            # TODO: Check that `field_type` is a union?
             for arg_type in get_args(field_type):
                 if arg_type is MissingType:
                     partial_fields.add(k)
 
+            for mdv in v.metadata:
+                # If we find the marker AND we are not already marked as a partial_field,
+                # add field to auto-exclude list.
+                if mdv is AutoPartialExcludeMarker and k not in partial_fields:
+                    final_auto_exclude.add(k)
+
+        if final_auto_exclude:
+            cls.model_config['auto_partials_exclude'] = final_auto_exclude
+
         final_partial_auto = cls.model_config.get('auto_partials', True)
         if final_partial_auto is not False:
             # I'll be putting in more options for `final_partial_auto` in the near future,
@@ -99,6 +129,10 @@ def __new__(
                     # The field is already a Partial
                     continue
 
+                if k in final_auto_exclude:
+                    # The field is excluded.
+                    continue
+
                 if v.default is PydanticUndefined and v.default_factory is None:
                     v.annotation = v.annotation | MissingType
                     partial_fields.add(k)

pydantic_partials/partial.py

@@ -1,10 +1,10 @@
 import typing
-from typing import Any, get_args, get_origin, TypeVar
+from typing import Any, get_args, get_origin, TypeVar, Annotated
 
 from pydantic import BaseModel, model_serializer, JsonValue
 
 from .meta import PartialMeta
-from .sentinels import Missing, MissingType
+from .sentinels import Missing, MissingType, AutoPartialExcludeMarker
 
 from logging import getLogger
 
@@ -17,6 +17,9 @@
     assigned to it. 
 """
 
+PME = TypeVar('PME')
+AutoPartialExclude = Annotated[PME, AutoPartialExcludeMarker]
+
 
 class PartialModel(
     BaseModel,

pydantic_partials/sentinels.py

@@ -1,4 +1,4 @@
-from typing import Any, Type, TypeVar
+from typing import Any, Type, TypeVar, Annotated
 
 from pydantic import GetCoreSchemaHandler
 from pydantic_core import core_schema, PydanticOmit
@@ -54,5 +54,12 @@ def _serialize(value: Any) -> 'MissingType':
 """ Returned as attribute value when attribute value is missing. Can also be set on attribute to indicate it's missing.
 """
 
-T = TypeVar('T')
 
+class AutoPartialExcludeMarkerType(Sentinel):
+    pass
+
+
+AutoPartialExcludeMarker = AutoPartialExcludeMarkerType()
+""" Used by `pydantic_partials.partial.AutoPartialExclude` to mark a field as excluded from automatic partials.
+    See `pydantic_partials.config.PartialConfigDict.auto_partials_exclude` for more details.
+"""

setup.cfg

@@ -1,5 +1,5 @@
 [pycodestyle]
 ignore = E121,E123,E126,E203,E226,E242,E704,E731,W391,W503,W504,C0103
-max-line-length = 99
+max-line-length = 120
 statistics = True
 exclude = setup.py,**/migrations/*,lib/*,.git,__pycache__,node_modules,.venv,.eggs/*,.serverless/**

tests/test_doc_examples.py

@@ -103,3 +103,40 @@ class PartialTestModel(PartialModel, TestModel):
     assert obj.model_dump() == {
         'name': 'a-name', 'some_null_by_default_field': None
     }
+
+
+def test_doc_example__auto_exclude__index__4():
+    from pydantic_partials import PartialModel, AutoPartialExclude, Missing
+    from pydantic import BaseModel, ValidationError
+    from datetime import datetime
+    import pytest
+
+    class PartialRequired(PartialModel):
+        id: AutoPartialExclude[str]
+        created_at: AutoPartialExclude[datetime]
+
+    class TestModel(BaseModel):
+        id: str
+        created_at: datetime
+        name: str
+        value: str
+        some_null_by_default_field: str | None = None
+
+    class PartialTestModel(TestModel, PartialRequired):
+        pass
+
+    # Will raise validation error for the two fields excluded from auto-partials
+    with pytest.raises(
+        ValidationError,
+        match=r'2 validation errors[\w\W]*'
+              r'id[\w\W]*Field required[\w\W]*'
+              r'created_at[\w\W]*Field required'
+    ):
+        PartialTestModel()
+
+    # If we give them values, we get no ValidationError
+    obj = PartialTestModel(id='some-value', created_at=datetime.now())
+
+    # And fields have the expected values.
+    assert obj.id == 'some-value'
+    assert obj.name is Missing

tests/test_inheritance.py

@@ -0,0 +1,109 @@
+from datetime import datetime
+
+import pytest
+
+from pydantic_partials import PartialModel, Missing
+from pydantic import ValidationError, BaseModel
+
+from pydantic_partials.partial import AutoPartialExclude
+
+
+def test_doc_example__index__3():
+    class TestModel(BaseModel):
+        name: str
+        value: str
+        some_null_by_default_field: str | None = None
+
+    class PartialTestModel(PartialModel, TestModel):
+        pass
+
+    try:
+        # This should produce an error because
+        # `name` and `value`are required fields.
+        TestModel()
+    except ValidationError as e:
+        print(f'Pydantic will state `name` + `value` are required: {e}')
+    else:
+        raise Exception('Pydantic should have required `required_decimal`.')
+
+        # We inherit from `TestModel` and add `PartialModel` to the mix.
+
+    # `PartialTestModel` can now be allocated without the required fields.
+    # Any missing required fields will be marked with the `Missing` value
+    # and won't be serialized out.
+    obj = PartialTestModel(name='a-name')
+
+    assert obj.name == 'a-name'
+    assert obj.value is Missing
+    assert obj.some_null_by_default_field is None
+
+    # The `None` field value is still serialized out,
+    # only fields with a `Missing` value assigned are skipped.
+    assert obj.model_dump() == {
+        'name': 'a-name', 'some_null_by_default_field': None
+    }
+
+
+def test_auto_excluded_inheritance_1():
+    class TestModel(BaseModel):
+        name: str
+        value: str
+        some_null_by_default_field: str | None = None
+
+    class PartialTestModel(PartialModel, TestModel):
+        value: AutoPartialExclude[str]
+
+    with pytest.raises(ValidationError, match=r'1 validation error.*\n *value *\n +Field required') as e_info:
+        PartialTestModel()
+
+    PartialTestModel(value='sss')
+
+
+def test_auto_excluded_inheritance_w_sibling():
+    class BaseRequired(BaseModel):
+        id: AutoPartialExclude[str]
+        created_at: AutoPartialExclude[datetime]
+
+    class TestModel(BaseRequired):
+        name: str
+        value: str
+        some_null_by_default_field: str | None = None
+
+    class PartialTestModel(PartialModel, TestModel):
+        pass
+
+    with pytest.raises(
+            ValidationError,
+            match=r'2 validation errors[\w\W]*'
+                  r'id[\w\W]*Field required[\w\W]*'
+                  r'created_at[\w\W]*Field required'
+    ):
+        PartialTestModel()
+
+    PartialTestModel(id='sss', created_at=datetime.now())
+
+
+def test_auto_excluded_inheritance_w_sibling_2():
+    class PartialRequired(PartialModel, auto_partials_exclude={'id', 'created_at'}):
+        id: str
+        created_at: datetime
+
+    class TestModel(BaseModel):
+        id: str
+        created_at: datetime
+        name: str
+        value: str
+        some_null_by_default_field: str | None = None
+
+    class PartialTestModel(TestModel, PartialRequired):
+        pass
+
+    with pytest.raises(
+            ValidationError,
+            match=r'2 validation errors[\w\W]*'
+                  r'id[\w\W]*Field required[\w\W]*'
+                  r'created_at[\w\W]*Field required'
+    ):
+        PartialTestModel()
+
+    PartialTestModel(id='sss', created_at=datetime.now())