Merge pull request #2 from joshorr/josho/adjust-docs

Josho/adjust docs

Author: joshorr

.gitignore

@@ -1,7 +1,7 @@
 # Custom Ones
 
 /scripts
-
+/api
 
 # Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
 # Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839

README.md

@@ -2,44 +2,110 @@
 
 Provides easy way to map dict to/from Full-Fledged 'JsonModel' object.
 
-![PythonSupport](https://img.shields.io/static/v1?label=python&message=%203.8|%203.9|%203.10|%203.11&color=blue?style=flat-square&logo=python)
+![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?)
 
 ## Documentation
 
-**[📄 Detailed Documentation](https://xyngular.github.io/py-xmodel/latest/)** | **[🐍 PyPi](https://pypi.org/project/xmodel/)**
-
-## Getting Started
-
-???+ warning "Alpha Software!"
-    This is pre-release Alpha software, based on another code base and
-    the needed changes to make a final release version are not yet
-    completed. Everything is subject to change!
+**[📄 Detailed Documentation](https://joshorr.github.io/pydantic-partials/latest/)** | **[🐍 PyPi](https://pypi.org/project/pydantic-partials/)**
 
+## Quick Start
 
 ```shell
-poetry install xmodel
+poetry install pydantic-partials
 ```
 
 or
 
 ```shell
-pip install xmodel
+pip install pydantic-partials
 ```
 
-Very basic example:
+By default, all fields without a default value will have the ability to be partial,
+and can be missing from both validation and serialization.
+
+Very basic example is below:
 
 ```python
-from xmodel import JsonModel
+from pydantic_partials import PartialModel, Missing, Partial
 
-class MyModel(JsonModel):
+
+class MyModel(PartialModel):
     some_attr: str
 
-json_dict_input = {'some_attr': 'a-value'}    
 
-obj = MyModel(json_dict_input)
-assert obj.some_attr == 'a-value'
+# By default, Partial fields without any value will get set to a special `Missing` type.
+# Any field that is set to Missing is excluded from the model_dump/model_dump_json
+obj = MyModel()
+assert obj.some_attr is Missing
+assert obj.model_dump() == {}
+
+# You can set the real value at any time, and it will behave like expected.
+obj.some_attr = 'hello'
+assert obj.some_attr is 'hello'
+assert obj.model_dump() == {'some_attr': 'hello'}
+
+# You can always manually set a field to `Missing` directly.
+obj.some_attr = Missing
+
+# And now it's removed from the model-dump.
+assert obj.model_dump() == {}
+
+# The json dump is also affected in the same way.
+assert obj.model_dump_json() == '{}'
+```
+
+
+You can turn off this default behavior by via `auto_partials` class argument or modeL_config option:
+
+```python
+from pydantic_partials import PartialModel, PartialConfigDict
+
+class TestModel1(PartialModel, auto_partials=False):
+    ...
+
+class TestModel2(PartialModel):
+    model_config = PartialConfigDict(auto_partials=False)
+    ...
+
+```
+
+You can disable this automatic function. This means you have complete control of exactly which field 
+can be partial or not.  You can use either the generic `Partial[...]` generic or a union with `MissingType`
+to mark a field as a partial field.  The generic simple makes the union to MissingType for you.
+
+Example of disabling auto_partials:
+
+```python
+from pydantic_partials import PartialModel, Missing, MissingType, Partial, PartialConfigDict
+from decimal import Decimal
+from pydantic import ValidationError
+
+class TestModel(PartialModel, auto_partials=False):
+    # Can use `Partial` generic type
+    partial_int: Partial[int] = Missing
+    
+    # Or union with `MissingType`
+    partial_str: str | MissingType
+    
+    required_decimal: Decimal
+    
+try:
+    TestModel()
+except ValidationError as e:
+    print(f'Pydantic will state `required_decimal` is required: {e}')
+else:
+    raise Exception('Pydantic should have required `required_decimal`.')
+    
+obj = TestModel(required_decimal='1.34')
+
+# You can find out at any time if a field is missing or not:
+assert obj.partial_int is Missing
+assert obj.partial_str is Missing
+
+assert obj.required_decimal == Decimal('1.34')
 
-json_dict = obj.api.json()
-assert json_dict == json_dict_input
 ```
+
+
+

pydantic_partials/config.py

@@ -9,7 +9,7 @@ class PartialConfigDict(ConfigDict):
     """
     Defaults to `True`.
     
-    If `True` (default): When class is created, all required attributes will be made `Partial`,
+    - If `True` (default): When class is created, all required attributes will be made `Partial`,
         and their default set to `Missing`. This means that all attributes that don't have any
         default or default_factory defined will automatically have `MissingType`/`LazyType` added
         to their annotation and field default set to `Missing`/`Lazy`.
@@ -19,7 +19,7 @@ class PartialConfigDict(ConfigDict):
         This allows Pydantic to create an instance of the model without a value defined
         for partial fields.
     
-    If `False`: Class won't automatically add `Partial` fields.
+    - If `False`: Class won't automatically add `Partial` fields.
         Instead adding them to individual fields will be up to the user.
         
         The default value of any fields set by user to be `Partial` will still be adjusted

pydantic_partials/meta.py

@@ -15,7 +15,11 @@
 
 
 # metaclass to make all fields in a model optional, useful for PATCH requests
-class _PartialMeta(ModelMetaclass):
+class PartialMeta(ModelMetaclass):
+    """ Metaclass of `pydantic_partials.partial.PartialModel`, used to support partial fields,
+        including the ability ot automatically apply `pydantic_partials.partial.Partial`[...] to fields
+        via `pydantic_partials.config.PartialConfigDict.auto_partials` configuration option.
+    """
     model_partial_fields: typing.ClassVar[set[str]]
     """ Set of strings representing field names that can be missing from validation/serialization.
         If they are missing, they will return the `Missing` sentinel value and the field will be entirely
@@ -53,7 +57,7 @@ def __new__(
         """
 
         Args:
-            auto_partials: For more details see `pydantic_partials.config.PartialConfigDict.auto_partial`.
+            auto_partials: For more details see `pydantic_partials.config.PartialConfigDict.auto_partials`.
                 If `Default`: Inherit behavior from parent/model_config; otherwise defaults to `True`.
                 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.

pydantic_partials/partial.py

@@ -3,7 +3,7 @@
 
 from pydantic import BaseModel, model_serializer, JsonValue
 
-from .meta import _PartialMeta
+from .meta import PartialMeta
 from .sentinels import Missing, MissingType
 
 from logging import getLogger
@@ -23,18 +23,25 @@ class PartialModel(
 
     # Need metaclass to examine fields for missing type
     # and also to auto-add missing type if desired.
-    metaclass=_PartialMeta,
+    metaclass=PartialMeta,
 
     # Needed so `Missing` default values will be validated and therefore the `PydanticOmit` will be
     # raised and inform Pydantic to ignore/omit the field value.
     validate_default=True
 ):
-    """ Class Args:
-            auto_partial: For more details see `pydantic_partials.config.PartialConfigDict.auto_partial`.
-                If `Default`: Inherit behavior from parent/model_config; otherwise defaults to `True`.
-                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.
     """
+    Class Args:
+
+    - auto_partial: For more details see `pydantic_partials.config.PartialConfigDict.auto_partials`.
+        - If `Default`: Inherit behavior from parent/model_config; otherwise defaults to `True`.
+        - 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.
+    """
+
+    def __init__(self, *args, **kwargs):
+        """ Pydantic partial model class, with ability to easily dynamically omit fields when serializing a model.
+        """
+        super().__init__(*args, **kwargs)
 
     if not typing.TYPE_CHECKING:
 

pydantic_partials/sentinels.py

@@ -6,7 +6,10 @@
 
 
 class MissingType(Sentinel):
-    # See (https://docs.pydantic.dev/latest/concepts/json_schema/#modifying-the-schema).
+    """ Class/Type of `Missing`, a sentinel that is used to indicate if a field is missing its value
+        in a `pydantic_partials.partial.PartialModel` subclass.
+    """
+    # Notes/See (https://docs.pydantic.dev/latest/concepts/json_schema/#modifying-the-schema).
 
     @classmethod
     def __get_pydantic_core_schema__(
@@ -41,6 +44,8 @@ def _serialize(value: Any) -> 'MissingType':
 
 
 Missing = MissingType()
+""" Returned as attribute value when attribute value is missing. Can also be set on attribute to indicate it's missing.
+"""
 
 T = TypeVar('T')
 

pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "pydantic-partials"
 version = "1.0.0"
-description = "Pydantic partial model class, with ability to easily dynamically omit fields when seralizing a model."
+description = "Pydantic partial model class, with ability to easily dynamically omit fields when serializing a model."
 
 authors = ["Josh Orr <[email protected]>"]
 packages = [{include = "pydantic_partials"}]