feat: add AlwaysNone

Author: iloveitaly

polyfactory/__init__.py

@@ -1,17 +1,17 @@
 from .exceptions import ConfigurationException
 from .factories import BaseFactory
-from .fields import Fixture, Ignore, PostGenerated, Require, Use, NeverNone
-from .persistence import AsyncPersistenceProtocol, SyncPersistenceProtocol
+from .fields import AlwaysNone, Fixture, Ignore, NeverNone, PostGenerated, Require, Use
+from .persistence import AsyncPersistenceProtocol
 
 __all__ = (
+    "AlwaysNone",
     "AsyncPersistenceProtocol",
     "BaseFactory",
     "ConfigurationException",
     "Fixture",
     "Ignore",
+    "NeverNone",
     "PostGenerated",
     "Require",
-    "NeverNone",
-    "SyncPersistenceProtocol",
     "Use",
 )

polyfactory/factories/base.py

@@ -54,7 +54,7 @@
 )
 from polyfactory.exceptions import ConfigurationException, MissingBuildKwargException, ParameterException
 from polyfactory.field_meta import Null
-from polyfactory.fields import Fixture, Ignore, NeverNone, PostGenerated, Require, Use
+from polyfactory.fields import AlwaysNone, Fixture, Ignore, NeverNone, PostGenerated, Require, Use
 from polyfactory.utils.helpers import (
     flatten_annotation,
     get_collection_type,
@@ -949,6 +949,10 @@ def should_set_none_value(cls, field_meta: FieldMeta) -> bool:
         """
         field_value = hasattr(cls, field_meta.name) and getattr(cls, field_meta.name)
         never_none = field_value and isinstance(field_value, NeverNone)
+        always_none = field_value and isinstance(field_value, AlwaysNone)
+
+        if always_none:
+            return True
 
         return (
             cls.__allow_none_optionals__
@@ -1026,7 +1030,7 @@ def _check_declared_fields_exist_in_model(cls) -> None:
                 f"{field_name} is declared on the factory {cls.__name__}"
                 f" but it is not part of the model {cls.__model__.__name__}"
             )
-            if isinstance(field_value, (Use, PostGenerated, Ignore, Require, NeverNone)):
+            if isinstance(field_value, (Use, PostGenerated, Ignore, Require, NeverNone, AlwaysNone)):
                 raise ConfigurationException(error_message)
 
     @classmethod
@@ -1047,9 +1051,12 @@ def process_kwargs(cls, **kwargs: Any) -> dict[str, Any]:
             if cls.should_set_field_value(field_meta, **kwargs) and not cls.should_use_default_value(field_meta):
                 field_value = getattr(cls, field_meta.name, None)
 
-                # TODO why do we need the BaseFactory check here, only dunder methods which are ignored would trigger this?
-                # NeverNone should be treated as a normally-generated field
-                if field_value and not hasattr(BaseFactory, field_meta.name) and not isinstance(field_value, NeverNone):
+                # NeverNone & AlwaysNone should be treated as a normally-generated field, since this changes logic
+                # within get_field_value.
+                excluded_field_value = field_value and isinstance(field_value, (NeverNone, AlwaysNone))
+
+                # TODO why do we need the BaseFactory check here, only dunder methods which are ignored would trigger this?  # noqa: FIX002
+                if field_value and not hasattr(BaseFactory, field_meta.name) and not excluded_field_value:
                     if isinstance(field_value, Ignore):
                         continue
 

polyfactory/fields.py

@@ -23,11 +23,23 @@ class Require:
 
 
 class NeverNone:
-    """A factory field that marks as always generated, even if it's an optional"""
+    """A factory field that marks as always generated, even if it's an optional."""
+
+
+class AlwaysNone:
+    """A factory field that marks as never generated, setting the value to None, regardless of if it's an optional field
+
+    This is distinct from Ignore() which does not set a value for a field at all. If Ignore() is used and a default value
+    for a field is not set on the underlying model, then the field will not be set at all.
+    """
 
 
 class Ignore:
-    """A factory field that marks an attribute as ignored."""
+    """A factory field that marks an attribute as ignored. This prevents the factory generating any value for this field.
+
+    If you are using this on a pydantic model this will cause the field to be omitted from the resulting pydantic model
+    if there is no default value set for the pydantic field.
+    """
 
 
 class Use(Generic[P, T]):