More places where Unset sentinel is needed.

Author: mauvilsa

CHANGELOG.rst

@@ -20,6 +20,10 @@ Added
 - ``FromConfigMixin.from_config`` with ``config_read_mode_fsspec_enabled=True``
   now supports fsspec config loading including the resolving of relative paths
   (`#918 <https://github.com/omni-us/jsonargparse/pull/918>`__).
+- Add :obj:`.Unset` sentinel and ``unset_sentinel`` setting in
+  ``.set_parsing_settings`` to distinguish between arguments not provided and
+  those explicitly set to ``null`` (`#909
+  <https://github.com/omni-us/jsonargparse/pull/909>`__).
 
 Fixed
 ^^^^^
@@ -32,6 +36,16 @@ Changed
 - Drop support for Python 3.9. The minimum supported Python version is now
   3.10 (`#916 <https://github.com/omni-us/jsonargparse/pull/916>`__).
 
+Deprecated
+^^^^^^^^^^
+- ``skip_none`` parameter of :meth:`dump <.ArgumentParser.dump>`, :meth:`save
+  <.ArgumentParser.save>`, and :meth:`validate <.ArgumentParser.validate>` was
+  deprecated and will be removed in v5.0.0. Use ``skip_unset`` instead (`#909
+  <https://github.com/omni-us/jsonargparse/pull/909>`__).
+- ``skip_null`` flag for ``--print_config`` was deprecated and will be removed
+  in v5.0.0. Use ``skip_unset`` instead (`#909
+  <https://github.com/omni-us/jsonargparse/pull/909>`__).
+
 
 v4.49.0 (2026-05-15)
 --------------------
@@ -40,10 +54,6 @@ Added
 ^^^^^
 - Support ``Deque`` and ``FrozenSet`` in type hints (`#905
   <https://github.com/omni-us/jsonargparse/pull/905>`__).
-- Add :obj:`.Unset` sentinel and ``unset_sentinel`` setting in
-  ``.set_parsing_settings`` to distinguish between arguments not provided and
-  those explicitly set to ``null`` (`#909
-  <https://github.com/omni-us/jsonargparse/pull/909>`__).
 
 Fixed
 ^^^^^
@@ -86,13 +96,6 @@ Deprecated
 - ``enable_path`` parameter of ``ActionJsonSchema`` was deprecated and will be
   removed in v5.0.0. Use ``sub_config`` instead (`#907
   <https://github.com/omni-us/jsonargparse/pull/907>`__).
-- ``skip_none`` parameter of :meth:`dump <.ArgumentParser.dump>`, :meth:`save
-  <.ArgumentParser.save>`, and :meth:`validate <.ArgumentParser.validate>` was
-  deprecated and will be removed in v5.0.0. Use ``skip_unset`` instead (`#909
-  <https://github.com/omni-us/jsonargparse/pull/909>`__).
-- ``skip_null`` flag for ``--print_config`` was deprecated and will be removed
-  in v5.0.0. Use ``skip_unset`` instead (`#909
-  <https://github.com/omni-us/jsonargparse/pull/909>`__).
 
 
 v4.48.0 (2026-04-10)

jsonargparse/_actions.py

@@ -8,7 +8,7 @@
 from contextvars import ContextVar
 from typing import Any
 
-from ._common import Action, NonParsingAction, is_subclass, is_subclasses_disabled, parser_context
+from ._common import Action, NonParsingAction, get_parsing_setting, is_subclass, is_subclasses_disabled, parser_context
 from ._loaders_dumpers import get_loader_exceptions, load_value
 from ._namespace import Namespace
 from ._optionals import _get_config_read_mode, ruamel_support
@@ -129,7 +129,7 @@ def apply_config(parser, cfg, dest, value) -> None:
                 cfg_file = parser.parse_path(value, **kwargs)
             cfg_merged = parser.merge_config(cfg_file, cfg)
             cfg.__dict__.update(cfg_merged.__dict__)
-            if cfg.get(dest) is None:
+            if cfg.get(dest) is get_parsing_setting("unset_sentinel"):
                 cfg[dest] = []
             cfg[dest].append(cfg_path)
 

jsonargparse/_core.py

@@ -772,7 +772,7 @@ def dump(
             cfg: The configuration object to dump.
             format: The output format: ``yaml``, ``json``, ``json_indented``, ``toml``, ``parser_mode`` or ones added
                 via :func:`.set_dumper`.
-            skip_unset: Whether to exclude entries whose value is the configured unset value.
+            skip_unset: Whether to exclude entries whose value is the configured None/Unset value.
             skip_default: Whether to exclude entries whose value is the same as the default.
             skip_validation: Whether to skip parser checking.
             with_comments: Whether to add help content as comments. Currently only supported for ``format="yaml"``.
@@ -884,7 +884,7 @@ def save(
             path: Path to the location where to save config.
             format: The output format: ``yaml``, ``json``, ``json_indented``, ``parser_mode`` or ones added via
                 :func:`.set_dumper`.
-            skip_unset: Whether to exclude entries whose value is the configured unset value.
+            skip_unset: Whether to exclude entries whose value is the configured None/Unset value.
             skip_validation: Whether to skip parser checking.
             overwrite: Whether to overwrite existing files.
             multifile: Whether to save multiple config files by using the ``__path__`` metas.
@@ -1146,7 +1146,7 @@ def validate(
 
         Args:
             cfg: The configuration object to check.
-            skip_unset: Whether to skip checking of values that are the configured unset value.
+            skip_unset: Whether to skip checking of values that are the configured None/Unset value.
             skip_required: Whether to skip checking required arguments.
             branch: Base key in case cfg corresponds only to a branch.
 
@@ -1258,8 +1258,9 @@ def get_config_files(self, cfg: Namespace) -> list[str]:
         cfg_files = []
         if "__default_config__" in cfg:
             cfg_files.append(cfg["__default_config__"])
+        unset_sentinel = get_parsing_setting("unset_sentinel")
         for action in filter_non_parsing_actions(self._actions):
-            if isinstance(action, ActionConfigFile) and action.dest in cfg and cfg[action.dest] is not None:
+            if isinstance(action, ActionConfigFile) and action.dest in cfg and cfg[action.dest] is not unset_sentinel:
                 cfg_files.extend(p for p in cfg[action.dest] if p is not None)
         return cfg_files
 
@@ -1389,7 +1390,8 @@ def _check_value_key(
         Raises:
             TypeError: If the value is not valid.
         """
-        if value is None and lenient_check.get():
+        unset_sentinel = get_parsing_setting("unset_sentinel")
+        if value is unset_sentinel and lenient_check.get():
             return value
         is_subcommand = isinstance(action, ActionSubCommands)
         if is_subcommand and action.choices:

jsonargparse/_instantiation.py

@@ -6,6 +6,7 @@
     InstantiatorsDictType,
     applied_instantiation_links,
     class_instantiators,
+    get_parsing_setting,
     is_subclass,
     parser_context,
 )
@@ -84,6 +85,7 @@ def instantiate(
         components = ActionLink.reorder(order, components)
 
         cfg = cfg.clone(with_meta=False)
+        unset_sentinel = get_parsing_setting("unset_sentinel")
         for component in components:
             ActionLink.apply_instantiation_links(self, cfg, target=component.dest)
             if isinstance(component, ActionTypeHint):
@@ -92,7 +94,7 @@ def instantiate(
                 except (KeyError, AttributeError):
                     pass
                 else:
-                    if value is not None:
+                    if value is not unset_sentinel:
                         with parser_context(
                             parent_parser=self,
                             nested_links=ActionLink.get_nested_links(self, component),

jsonargparse/_loaders_dumpers.py

@@ -243,6 +243,8 @@ def replace_unset(data):
         return Unset._SERIALIZED
     if isinstance(data, dict):
         return {k: replace_unset(v) for k, v in data.items()}
+    if isinstance(data, list):
+        return [replace_unset(v) for v in data]
     return data
 
 

jsonargparse/_signatures.py

@@ -11,6 +11,7 @@
 from ._common import (
     LoggerProperty,
     get_generic_origin,
+    get_parsing_setting,
     get_unaliased_type,
     is_final_class,
     is_subclass,
@@ -337,7 +338,8 @@ def _add_signature_parameter(
             default = param.default
             if default == inspect_empty:
                 if is_optional(annotation):
-                    default = None
+                    unset_sentinel = get_parsing_setting("unset_sentinel")
+                    default = unset_sentinel if unset_sentinel is not None else None
                 elif get_typehint_origin(annotation) in not_required_types:
                     default = SUPPRESS
         # Determine argument characteristics based on parameter kind and default value

jsonargparse/_typehints.py

@@ -47,6 +47,7 @@
     remove_actions,
 )
 from ._common import (
+    get_parsing_setting,
     get_unaliased_type,
     is_generic_class,
     is_instance,
@@ -246,6 +247,7 @@ def cached_get_class_parser(*, val_class, sub_add_kwargs, skip_args, parent_pars
         freeze(sub_add_kwargs),
         freeze(skip_args),
         freeze(nested_links),
+        get_parsing_setting("unset_sentinel"),
     )
     if cache_key in _cached_class_parsers:
         parser = _cached_class_parsers[cache_key]
@@ -622,8 +624,9 @@ def _check_type(self, value, append=False, cfg=None, mode=None):
                     config_path = None
                 path_meta = val.pop("__path__", None) if isinstance(val, dict) else None
 
-                prev_val = cfg.get(self.dest) if cfg else None
-                if prev_val is None and not sub_defaults.get() and is_subclass_spec(self.default):
+                unset_sentinel = get_parsing_setting("unset_sentinel")
+                prev_val = cfg.get(self.dest) if cfg else unset_sentinel
+                if prev_val is unset_sentinel and not sub_defaults.get() and is_subclass_spec(self.default):
                     prev_val = Namespace(class_path=self.default["class_path"])
 
                 kwargs = {
@@ -815,6 +818,7 @@ def adapt_typehints(
     }
     subtypehints = getattr(typehint, "__args__", None)
     typehint_origin = get_typehint_origin(typehint) or typehint
+    unset_sentinel = get_parsing_setting("unset_sentinel")
 
     # Any
     if typehint == Any:
@@ -930,7 +934,7 @@ def adapt_typehints(
     elif typehint_origin in sequence_origin_types:
         if append:
             adapt_kwargs.pop("prev_val")
-            if prev_val is None:
+            if prev_val is unset_sentinel:
                 prev_val = []
             elif not isinstance(prev_val, list):
                 try:
@@ -1064,7 +1068,7 @@ def adapt_typehints(
                     else:
                         raise ImportError(f"Unexpected import object {val_obj}")
                 if isinstance(val, (dict, Namespace, NestedArg)):
-                    if prev_val is None:
+                    if prev_val is unset_sentinel:
                         return_type = get_callable_return_type(typehint)
                         if return_type and not inspect.isabstract(return_type):
                             with suppress(ValueError):
@@ -1104,7 +1108,7 @@ def adapt_typehints(
             return val
 
         prev_implicit_defaults = False
-        if prev_val is None and not inspect.isabstract(typehint) and not is_protocol(typehint):
+        if prev_val is unset_sentinel and not inspect.isabstract(typehint) and not is_protocol(typehint):
             with suppress(ValueError):
                 # implicit prev_val class_path
                 prev_val = Namespace(class_path=get_import_path(typehint))
@@ -1123,6 +1127,9 @@ def adapt_typehints(
             val = subclass_spec_as_namespace(val, type_class_path)
         else:
             val = subclass_spec_as_namespace(val, prev_val)
+        if val and not is_subclass_spec(val) and "init_args" not in val:
+            # implicit val class_path
+            val = Namespace(class_path=get_import_path(typehint), init_args=val)
 
         if not is_subclass_spec(val):
             msg = "Does not implement protocol" if is_protocol(typehint) else "Not a valid subclass of"

jsonargparse_tests/test_parsing_settings.py

@@ -1,6 +1,6 @@
 import re
 from dataclasses import dataclass
-from typing import Literal, Optional
+from typing import List, Literal, Optional
 from unittest.mock import patch
 
 import pytest
@@ -254,6 +254,14 @@ def test_unset_sentinel_default_is_none(parser):
     assert get_parsing_setting("unset_sentinel") is None
 
 
+def test_unset_sentinel_get_defaults(parser):
+    set_parsing_settings(unset_sentinel=True)
+
+    parser.add_argument("--num", type=int)
+    defaults = parser.get_defaults()
+    assert defaults.num is Unset
+
+
 def test_unset_sentinel_optional_int(parser):
     set_parsing_settings(unset_sentinel=True)
 
@@ -281,15 +289,7 @@ def test_unset_sentinel_explicit_none_default_stays_none(parser):
     assert defaults.num is None
 
 
-def test_unset_sentinel_get_defaults(parser):
-    set_parsing_settings(unset_sentinel=True)
-
-    parser.add_argument("--num", type=int)
-    defaults = parser.get_defaults()
-    assert defaults.num is Unset
-
-
-def test_unset_sentinel_skip_unset_dump(parser):
+def test_unset_sentinel_dump_skip_unset(parser):
     set_parsing_settings(unset_sentinel=True)
 
     parser.add_argument("--num", type=Optional[int])
@@ -306,6 +306,30 @@ def test_unset_sentinel_skip_unset_dump(parser):
     assert json_or_yaml_load(dump_no_skip) == {"num": "==UNSET==", "name": "hello"}
 
 
+@dataclass
+class UnsetListItem:
+    name: str
+    value: Optional[int]
+
+
+def test_unset_sentinel_dump_list_of_dataclasses(parser):
+    set_parsing_settings(unset_sentinel=True)
+
+    parser.add_argument("--records", type=List[UnsetListItem])
+
+    cfg = parser.parse_args(['--records=[{"name":"a"},{"name":"b","value":2}]'])
+    assert cfg.records[0] == Namespace(name="a", value=Unset)
+    assert cfg.records[1] == Namespace(name="b", value=2)
+
+    dump_skip = parser.dump(cfg, skip_unset=True)
+    loaded_skip = json_or_yaml_load(dump_skip)
+    assert loaded_skip == {"records": [{"name": "a"}, {"name": "b", "value": 2}]}
+
+    dump_no_skip = parser.dump(cfg, skip_unset=False)
+    loaded_no_skip = json_or_yaml_load(dump_no_skip)
+    assert loaded_no_skip == {"records": [{"name": "a", "value": "==UNSET=="}, {"name": "b", "value": 2}]}
+
+
 def test_unset_sentinel_validate_skip_unset(parser):
     set_parsing_settings(unset_sentinel=True)
 
@@ -333,13 +357,51 @@ def test_unset_repr():
 
 
 def test_unset_bool():
-    assert not Unset
+    assert bool(Unset) is False
+    assert bool(not Unset) is True
 
 
 def test_unset_is_singleton():
     assert _UnsetType() is Unset
 
 
+# add_function_arguments with unset_sentinel
+
+
+def test_unset_sentinel_function_arguments_no_default_is_unset(parser):
+    """Optional param with no default in function signature should be Unset when unset_sentinel=True."""
+    set_parsing_settings(unset_sentinel=True)
+
+    def my_func(num: Optional[int], name: str = "hello"):
+        pass  # pragma: no cover
+
+    parser.add_function_arguments(my_func)
+
+    cfg = parser.parse_args([])
+    assert cfg.num is Unset  # no default in signature → Unset
+    assert cfg.name == "hello"  # has default → kept
+
+    cfg = parser.parse_args(["--num=null"])
+    assert cfg.num is None  # explicitly set to null → None
+
+    cfg = parser.parse_args(["--num=5"])
+    assert cfg.num == 5
+
+
+def test_unset_sentinel_function_arguments_explicit_none_default_stays_none(parser):
+    """Optional param with explicit default=None in function signature stays None."""
+    set_parsing_settings(unset_sentinel=True)
+
+    def my_func(num: Optional[int] = None, flag: Optional[int] = 0):
+        pass  # pragma: no cover
+
+    parser.add_function_arguments(my_func)
+
+    cfg = parser.parse_args([])
+    assert cfg.num is None  # explicit default=None → None (not Unset)
+    assert cfg.flag == 0  # explicit default=0 → 0
+
+
 # Interaction between Unset and default SUPPRESS
 
 
@@ -377,3 +439,17 @@ def test_unset_and_argument_default_suppress(parser):
     cfg = parser.parse_args(["--num=7"])
     assert cfg.num == 7
     assert not hasattr(cfg, "name")  # still absent
+
+
+def test_unset_parse_and_print_config(parser):
+    set_parsing_settings(unset_sentinel=True)
+
+    parser.add_argument("--num", type=int)
+    parser.add_argument("--name", type=str, default="a")
+    parser.add_argument("--cfg", action="config")
+
+    cfg = parser.parse_args(["--cfg={}"])
+    assert cfg == Namespace(num=Unset, name="a", cfg=[None])
+
+    out = get_parse_args_stdout(parser, ["--print_config"])
+    assert json_or_yaml_load(out) == {"num": "==UNSET==", "name": "a"}