v0.30.0-skip-if (#147)

* Add "skip if" support for serializing dataclass fields

* Looks good, just need to add tests and docs

* Add test cases

* Update docs

* Update docs on Meta

* Add `JSONPyWizard` and some condition functions

* Add `IS_TRUTHY` and `IS_FALSY` conditions
* Add `JSONPyWizard` to skip key transformation during serialization (dump)

* update docs

* update docs

* re-order sections in docs

* update docs

* that should be v1 not v2

* Update HISTORY.rst

* Update docs

Author: rnag

HISTORY.rst

@@ -2,6 +2,26 @@
 History
 =======
 
+0.30.0 (2024-11-25)
+-------------------
+
+**Features and Improvements**
+
+- **Conditional Field Skipping**: Omit fields during JSON serialization based on user-defined conditions.
+    - Introduced new :class:`Meta` settings:
+        - :attr:`skip_if` — Skips all fields matching a condition.
+        - :attr:`skip_defaults_if` — Skips fields with default values matching a condition.
+    - Added per-field controls using :func:`SkipIf()` annotations.
+    - Introduced the :func:`skip_if_field` wrapper for maximum flexibility.
+
+- **New Helper Class**: :class:`JSONPyWizard`
+    - A ``JSONWizard`` helper to disable *camelCase* transformation and keep keys as-is.
+
+- **Typing Improvements**: Added more ``*.pyi`` files for enhanced type checking and IDE support.
+
+- **Documentation Updates**:
+    - Added details about upcoming changes in the next major release, ``v1.0``.
+
 0.29.3 (2024-11-24)
 -------------------
 

README.rst

@@ -27,12 +27,12 @@ Full documentation is available at `Read The Docs`_. (`Installation`_)
 
 
 
-Dataclass Wizard offers simple, elegant, *wizarding* tools for
+**Dataclass Wizard** offers simple, elegant, *wizarding* 🪄 tools for
 interacting with Python's ``dataclasses``.
 
-    It excels at lightning-fast de/serialization, converting dataclass
-    instances to/from JSON effortlessly -- perfect for *nested dataclass*
-    models!
+    It excels at ⚡️ lightning-fast de/serialization, effortlessly
+    converting dataclass instances to/from JSON -- perfect for
+    *nested dataclass* models!
 
 -------------------
 
@@ -106,8 +106,9 @@ Here are the key features that ``dataclass-wizard`` offers:
 Wizard Mixins
 -------------
 
-In addition to the ``JSONWizard``, here are a few extra Mixin_ classes that might prove quite convenient to use.
+In addition to ``JSONWizard``, these handy Mixin_ classes simplify your workflow:
 
+* `JSONPyWizard`_ — A ``JSONWizard`` helper to skip *camelCase* and keep keys as-is.
 * `JSONListWizard`_ -- Extends ``JSONWizard`` to return `Container`_ -- instead of *list* -- objects where possible.
 * `JSONFileWizard`_ -- Makes it easier to convert dataclass instances from/to JSON files on a local drive.
 * `TOMLWizard`_ -- Provides support to convert dataclass instances to/from TOML.
@@ -940,6 +941,130 @@ dataclasses in ``Union`` types. For more info, check out the
     # True
     assert c == c.from_json(c.to_json())
 
+Conditional Field Skipping
+--------------------------
+
+.. admonition:: **Added in v0.30.0**
+
+    Dataclass Wizard introduces `conditional skipping`_ to omit fields during JSON serialization based on user-defined conditions. This feature works seamlessly with:
+
+    - **Global rules** via ``Meta`` settings.
+    - **Per-field controls** using ``SkipIf()`` `annotations`_.
+    - **Field wrappers** for maximum flexibility.
+
+Quick Examples
+~~~~~~~~~~~~~~
+
+1. **Globally Skip Fields Matching a Condition**
+
+  Define a global skip rule using ``Meta.skip_if``:
+
+  .. code-block:: python3
+
+    from dataclasses import dataclass
+    from dataclass_wizard import JSONWizard, IS_NOT
+
+
+    @dataclass
+    class Example(JSONWizard):
+        class _(JSONWizard.Meta):
+            skip_if = IS_NOT(True)  # Skip fields if the value is not `True`
+
+        my_bool: bool
+        my_str: 'str | None'
+
+
+    print(Example(my_bool=True, my_str=None).to_dict())
+    # Output: {'myBool': True}
+
+2. **Skip Defaults Based on a Condition**
+
+  Skip fields with default values matching a specific condition using ``Meta.skip_defaults_if``:
+
+  .. code-block:: python3
+
+    from __future__ import annotations  # Can remove in PY 3.10+
+
+    from dataclasses import dataclass
+    from dataclass_wizard import JSONPyWizard, IS
+
+
+    @dataclass
+    class Example(JSONPyWizard):
+        class _(JSONPyWizard.Meta):
+            skip_defaults_if = IS(None)  # Skip default `None` values.
+
+        str_with_no_default: str | None
+        my_str: str | None = None
+        my_bool: bool = False
+
+
+    print(Example(str_with_no_default=None, my_str=None).to_dict())
+    #> {'str_with_no_default': None, 'my_bool': False}
+
+
+  .. note::
+      Setting ``skip_defaults_if`` also enables ``skip_defaults=True`` automatically.
+
+3. **Per-Field Conditional Skipping**
+
+  Apply skip rules to specific fields with `annotations`_ or ``skip_if_field``:
+
+  .. code-block:: python3
+
+    from __future__ import annotations  # can be removed in Python 3.10+
+
+    from dataclasses import dataclass
+    from typing import Annotated
+
+    from dataclass_wizard import JSONWizard, SkipIfNone, skip_if_field, EQ
+
+
+    @dataclass
+    class Example(JSONWizard):
+        my_str: Annotated[str | None, SkipIfNone]  # Skip if `None`.
+        other_str: str | None = skip_if_field(EQ(''), default=None)  # Skip if empty.
+
+    print(Example(my_str=None, other_str='').to_dict())
+    # Output: {}
+
+4. **Skip Fields Based on Truthy or Falsy Values**
+
+   Use the ``IS_TRUTHY`` and ``IS_FALSY`` helpers to conditionally skip fields based on their truthiness:
+
+   .. code-block:: python3
+
+    from dataclasses import dataclass, field
+    from dataclass_wizard import JSONWizard, IS_FALSY
+
+
+    @dataclass
+    class ExampleWithFalsy(JSONWizard):
+        class _(JSONWizard.Meta):
+            skip_if = IS_FALSY()  # Skip fields if they evaluate as "falsy".
+
+        my_bool: bool
+        my_list: list = field(default_factory=list)
+        my_none: None = None
+
+    print(ExampleWithFalsy(my_bool=False, my_list=[], my_none=None).to_dict())
+    #> {}
+
+.. note::
+
+   *Special Cases*
+
+   - **SkipIfNone**: Alias for ``SkipIf(IS(None))``, skips fields with a value of ``None``.
+   - **Condition Helpers**:
+
+     - ``IS``, ``IS_NOT``: Identity checks.
+     - ``EQ``, ``NE``, ``LT``, ``LE``, ``GT``, ``GE``: Comparison operators.
+     - ``IS_TRUTHY``, ``IS_FALSY``: Skip fields based on truthy or falsy values.
+
+   Combine these helpers for flexible serialization rules!
+
+.. _conditional skipping: https://dataclass-wizard.readthedocs.io/en/latest/common_use_cases/serialization_options.html#skip-if-functionality
+
 Serialization Options
 ---------------------
 
@@ -1064,6 +1189,33 @@ mixin class.
 For more examples and important how-to's on properties with default values,
 refer to the `Using Field Properties`_ section in the documentation.
 
+What's New in v1.0
+------------------
+
+.. warning::
+
+   **Default Key Transformation Update**
+
+   Starting with ``v1.0.0``, the default key transformation for JSON serialization
+   will change to keep keys *as-is* instead of converting them to `camelCase`.
+
+   - **New Default Behavior**: ``key_transform='NONE'`` will be the standard setting.
+
+   **How to Prepare**:
+   You can enforce this future behavior right now by using the ``JSONPyWizard`` helper:
+
+   .. code-block:: python3
+
+      from dataclasses import dataclass
+      from dataclass_wizard import JSONPyWizard
+
+      @dataclass
+      class MyModel(JSONPyWizard):
+          my_field: str
+
+      print(MyModel(my_field="value").to_dict())
+      # Output: {'my_field': 'value'}
+
 Contributing
 ------------
 
@@ -1089,6 +1241,7 @@ This package was created with Cookiecutter_ and the `rnag/cookiecutter-pypackage
 .. _`rnag/cookiecutter-pypackage`: https://github.com/rnag/cookiecutter-pypackage
 .. _`Contributing`: https://dataclass-wizard.readthedocs.io/en/latest/contributing.html
 .. _`open an issue`: https://github.com/rnag/dataclass-wizard/issues
+.. _`JSONPyWizard`: https://dataclass-wizard.readthedocs.io/en/latest/common_use_cases/wizard_mixins.html#jsonpywizard
 .. _`JSONListWizard`: https://dataclass-wizard.readthedocs.io/en/latest/common_use_cases/wizard_mixins.html#jsonlistwizard
 .. _`JSONFileWizard`: https://dataclass-wizard.readthedocs.io/en/latest/common_use_cases/wizard_mixins.html#jsonfilewizard
 .. _`TOMLWizard`: https://dataclass-wizard.readthedocs.io/en/latest/common_use_cases/wizard_mixins.html#tomlwizard
@@ -1114,3 +1267,4 @@ This package was created with Cookiecutter_ and the `rnag/cookiecutter-pypackage
 .. _Easier Debug Mode: https://dataclass-wizard.readthedocs.io/en/latest/common_use_cases/easier_debug_mode.html
 .. _Handling Unknown JSON Keys: https://dataclass-wizard.readthedocs.io/en/latest/common_use_cases/handling_unknown_json_keys.html
 .. _custom paths to access nested keys: https://dataclass-wizard.readthedocs.io/en/latest/common_use_cases/nested_key_paths.html
+.. _annotations: https://docs.python.org/3/library/typing.html#typing.Annotated

dataclass_wizard/__init__.py

@@ -71,6 +71,7 @@
 __all__ = [
     # Base exports
     'JSONSerializable',
+    'JSONPyWizard',
     'JSONWizard',
     'LoadMixin',
     'DumpMixin',
@@ -90,34 +91,47 @@
     'json_field',
     'json_key',
     'path_field',
+    'skip_if_field',
     'KeyPath',
     'Container',
     'Pattern',
     'DatePattern',
     'TimePattern',
     'DateTimePattern',
     'CatchAll',
+    'SkipIf',
+    'SkipIfNone',
+    'EQ',
+    'NE',
+    'LT',
+    'LE',
+    'GT',
+    'GE',
+    'IS',
+    'IS_NOT',
+    'IS_TRUTHY',
+    'IS_FALSY',
 ]
 
 import logging
 
 from .bases_meta import LoadMeta, DumpMeta
 from .dumpers import DumpMixin, setup_default_dumper, asdict
 from .loaders import LoadMixin, setup_default_loader, fromlist, fromdict
-from .models import (json_field, json_key, path_field, KeyPath, Container,
-                     Pattern, DatePattern, TimePattern, DateTimePattern, CatchAll)
+from .models import (json_field, json_key, path_field, skip_if_field,
+                     KeyPath, Container,
+                     Pattern, DatePattern, TimePattern, DateTimePattern,
+                     CatchAll, SkipIf, SkipIfNone,
+                     EQ, NE, LT, LE, GT, GE, IS, IS_NOT, IS_TRUTHY, IS_FALSY)
 from .property_wizard import property_wizard
-from .serial_json import JSONSerializable
+from .serial_json import JSONWizard, JSONPyWizard, JSONSerializable
 from .wizard_mixins import JSONListWizard, JSONFileWizard, TOMLWizard, YAMLWizard
 
 
 # Set up logging to ``/dev/null`` like a library is supposed to.
 # http://docs.python.org/3.3/howto/logging.html#configuring-logging-for-a-library
 logging.getLogger('dataclass_wizard').addHandler(logging.NullHandler())
 
-# A handy alias in case it comes in useful to anyone :)
-JSONWizard = JSONSerializable
-
 # Setup the default type hooks to use when converting `str` (json) or a Python
 # `dict` object to a `dataclass` instance.
 setup_default_loader()

dataclass_wizard/bases.py

@@ -4,6 +4,7 @@
 from .constants import TAG
 from .decorators import cached_class_property
 from .enums import DateTimeTo, LetterCase
+from .models import Condition
 from .type_def import FrozenKeys
 
 
@@ -113,6 +114,9 @@ class AbstractMeta(metaclass=ABCOrAndMeta):
 
     # True to enable Debug mode for additional (more verbose) log output.
     #
+    # The value can also be a `str` or `int` which specifies
+    # the minimum level for logs in this library to show up.
+    #
     # For example, a message is logged whenever an unknown JSON key is
     # encountered when `from_dict` or `from_json` is called.
     #
@@ -205,6 +209,15 @@ class AbstractMeta(metaclass=ABCOrAndMeta):
     # the :func:`dataclasses.field`) in the serialization process.
     skip_defaults: ClassVar[bool] = False
 
+    # Determines the :class:`Condition` to skip / omit dataclass
+    # fields in the serialization process.
+    skip_if: ClassVar[Condition] = None
+
+    # Determines the condition to skip / omit fields with default values
+    # (based on the `default` or `default_factory` argument specified for
+    # the :func:`dataclasses.field`) in the serialization process.
+    skip_defaults_if: ClassVar[Condition] = None
+
     # noinspection PyMethodParameters
     @cached_class_property
     def all_fields(cls) -> FrozenKeys:

dataclass_wizard/bases_meta.py

@@ -11,7 +11,7 @@
 from .abstractions import AbstractJSONWizard
 from .bases import AbstractMeta, META
 from .class_helper import (
-    _META_INITIALIZER, _META,
+    META_INITIALIZER, _META,
     get_outer_class_name, get_class_name, create_new_class,
     json_field_to_dataclass_field, dataclass_field_to_json_field
 )
@@ -22,6 +22,7 @@
 from .errors import ParseError
 from .loaders import get_loader
 from .log import LOG
+from .models import Condition
 from .type_def import E
 from .utils.type_conv import date_to_timestamp, as_enum
 
@@ -59,7 +60,7 @@ def _init_subclass(cls):
         # `__init_subclass__` method of any inner classes are run before the
         # one for the outer class.
         if outer_cls_name is not None:
-            _META_INITIALIZER[outer_cls_name] = cls.bind_to
+            META_INITIALIZER[outer_cls_name] = cls.bind_to
         else:
             # The `Meta` class is defined as an outer class. Emit a warning
             # here, just so we can ensure awareness of this special case.
@@ -230,7 +231,10 @@ def DumpMeta(*, debug_enabled: 'bool | int | str' = False,
              marshal_date_time_as: Union[DateTimeTo, str] = None,
              key_transform: Union[LetterCase, str] = None,
              tag: str = None,
-             skip_defaults: bool = False) -> META:
+             skip_defaults: bool = False,
+             skip_if: Condition = None,
+             skip_defaults_if: Condition = None,
+             ) -> META:
     """
     Helper function to setup the ``Meta`` Config for the JSON dump
     (serialization) process, which is intended for use alongside the
@@ -254,6 +258,8 @@ def DumpMeta(*, debug_enabled: 'bool | int | str' = False,
         'marshal_date_time_as': marshal_date_time_as,
         'key_transform_with_dump': key_transform,
         'skip_defaults': skip_defaults,
+        'skip_if': skip_if,
+        'skip_defaults_if': skip_defaults_if,
         'debug_enabled': debug_enabled,
         'recursive': recursive,
         'tag': tag,