config_read_mode and docstring_parse options can now be set using set_parsing_settings

CHANGELOG.rst

@@ -33,6 +33,9 @@ Changed
 - Untyped parameters with ``None`` default no longer skipped when
   ``fail_untyped=True`` (`#697
   <https://github.com/omni-us/jsonargparse/pull/697>`__).
+- ``config_read_mode`` and ``docstring_parse`` options can now be set using
+  ``set_parsing_settings`` (`#712
+  <https://github.com/omni-us/jsonargparse/pull/712>`__).
 
 Fixed
 ^^^^^
@@ -43,6 +46,15 @@ Fixed
 - List append nested in subclass not working (`#710
   <https://github.com/omni-us/jsonargparse/pull/710>`__).
 
+Deprecated
+^^^^^^^^^^
+- ``get_config_read_mode`` and ``set_docstring_parse_options`` are deprecated
+  and will be removed in v5.0.0, instead use ``set_parsing_settings`` (`#712
+  <https://github.com/omni-us/jsonargparse/pull/712>`__).
+- ``get_config_read_mode`` is deprecated and will be removed in v5.0.0. There will
+  be no replacement since this is considered internal (`#712
+  <https://github.com/omni-us/jsonargparse/pull/712>`__).
+
 
 v4.38.0 (2025-03-26)
 --------------------

DOCUMENTATION.rst

@@ -701,10 +701,10 @@ triggered to check if it is accessible. To get the content of the parsed path,
 without needing to care if it is a local file or a URL, the
 :py:meth:`.Path.get_content` method Scan be used.
 
-If you import ``from jsonargparse import set_config_read_mode`` and then run
-``set_config_read_mode(urls_enabled=True)`` or
-``set_config_read_mode(fsspec_enabled=True)``, the following functions and
-classes will also support loading from URLs:
+If you import ``from jsonargparse import set_parsing_settings`` and then run
+``set_parsing_settings(config_read_mode_urls_enabled=True)`` or
+``set_parsing_settings(config_read_mode_fsspec_enabled=True)``, the following
+functions and classes will also support loading from URLs:
 :py:meth:`.ArgumentParser.parse_path`, :py:meth:`.ArgumentParser.get_defaults`
 (``default_config_files`` argument), `action="config"`,
 :class:`.ActionJsonSchema`, :class:`.ActionJsonnet` and :class:`.ActionParser`.
@@ -1576,9 +1576,9 @@ single style, this is inefficient. A single style can be configured as follows:
 .. testcode:: docstrings
 
     from docstring_parser import DocstringStyle
-    from jsonargparse import set_docstring_parse_options
+    from jsonargparse import set_parsing_settings
 
-    set_docstring_parse_options(style=DocstringStyle.REST)
+    set_parsing_settings(docstring_parse_style=DocstringStyle.REST)
 
 The second option that can be configured is the support for `attribute
 docstrings <https://peps.python.org/pep-0257/#what-is-a-docstring>`__ (i.e.
@@ -1589,9 +1589,9 @@ that don't have attribute docstrings. To enable, do as follows:
 .. testcode:: docstrings
 
     from dataclasses import dataclass
-    from jsonargparse import set_docstring_parse_options
+    from jsonargparse import set_parsing_settings
 
-    set_docstring_parse_options(attribute_docstrings=True)
+    set_parsing_settings(docstring_parse_attribute_docstrings=True)
 
 
     @dataclass
@@ -1606,8 +1606,8 @@ that don't have attribute docstrings. To enable, do as follows:
 
 .. testcleanup:: docstrings
 
-    set_docstring_parse_options(style=DocstringStyle.GOOGLE)
-    set_docstring_parse_options(attribute_docstrings=False)
+    set_parsing_settings(docstring_parse_style=DocstringStyle.GOOGLE)
+    set_parsing_settings(docstring_parse_attribute_docstrings=False)
 
 Customization of arguments
 --------------------------

jsonargparse/__init__.py

@@ -64,9 +64,9 @@
 __all__ += _namespace.__all__
 __all__ += _formatters.__all__
 __all__ += _optionals.__all__
+__all__ += _common.__all__
 __all__ += _loaders_dumpers.__all__
 __all__ += _util.__all__
-__all__ += _common.__all__
 __all__ += _deprecated.__all__
 
 

jsonargparse/_actions.py

@@ -12,7 +12,7 @@
 from ._common import Action, is_subclass, parser_context
 from ._loaders_dumpers import get_loader_exceptions, load_value
 from ._namespace import Namespace, NSKeyError, split_key, split_key_root
-from ._optionals import get_config_read_mode
+from ._optionals import _get_config_read_mode
 from ._type_checking import ActionsContainer, ArgumentParser
 from ._util import (
     Path,
@@ -194,7 +194,7 @@ def apply_config(parser, cfg, dest, value) -> None:
         with _ActionSubCommands.not_single_subcommand(), previous_config_context(cfg), skip_apply_links():
             kwargs = {"env": False, "defaults": False, "_skip_validation": True, "_fail_no_subcommand": False}
             try:
-                cfg_path: Optional[Path] = Path(value, mode=get_config_read_mode())
+                cfg_path: Optional[Path] = Path(value, mode=_get_config_read_mode())
             except TypeError as ex_path:
                 try:
                     if isinstance(load_value(value), str):

jsonargparse/_common.py

@@ -6,6 +6,7 @@
 from contextlib import contextmanager
 from contextvars import ContextVar
 from typing import (  # type: ignore[attr-defined]
+    TYPE_CHECKING,
     Dict,
     Generic,
     List,
@@ -20,6 +21,8 @@
 
 from ._namespace import Namespace
 from ._optionals import (
+    _set_config_read_mode,
+    _set_docstring_parse_options,
     capture_typing_extension_shadows,
     get_alias_target,
     get_annotated_base_type,
@@ -31,6 +34,9 @@
 )
 from ._type_checking import ActionsContainer, ArgumentParser
 
+if TYPE_CHECKING:
+    import docstring_parser
+
 __all__ = [
     "LoggerProperty",
     "null_logger",
@@ -98,6 +104,10 @@
 def set_parsing_settings(
     *,
     validate_defaults: Optional[bool] = None,
+    config_read_mode_urls_enabled: Optional[bool] = None,
+    config_read_mode_fsspec_enabled: Optional[bool] = None,
+    docstring_parse_style: Optional["docstring_parser.DocstringStyle"] = None,
+    docstring_parse_attribute_docstrings: Optional[bool] = None,
     parse_optionals_as_positionals: Optional[bool] = None,
 ) -> None:
     """
@@ -107,17 +117,37 @@
         validate_defaults: Whether default values must be valid according to the
             argument type. The default is False, meaning no default validation,
             like in argparse.
+        config_read_mode_urls_enabled: Whether to read config files from URLs
+            using requests package. Default is False.
+        config_read_mode_fsspec_enabled: Whether to read config files from
+            fsspec supported file systems. Default is False.
+        docstring_parse_style: The docstring style to expect. Default is
+            DocstringStyle.AUTO.
+        docstring_parse_attribute_docstrings: Whether to parse attribute
+            docstrings (slower). Default is False.
         parse_optionals_as_positionals: [EXPERIMENTAL] If True, the parser will
             take extra positional command line arguments as values for optional
             arguments. This means that optional arguments can be given by name
             --key=value as usual, but also as positional. The extra positionals
             are applied to optionals in the order that they were added to the
             parser. By default, this is False.
     """
+    # validate_defaults
     if isinstance(validate_defaults, bool):
         parsing_settings["validate_defaults"] = validate_defaults
     elif validate_defaults is not None:
         raise ValueError(f"validate_defaults must be a boolean, but got {validate_defaults}.")
+    # config_read_mode
+    if config_read_mode_urls_enabled is not None:
+        _set_config_read_mode(urls_enabled=config_read_mode_urls_enabled)
+    if config_read_mode_fsspec_enabled is not None:
+        _set_config_read_mode(fsspec_enabled=config_read_mode_fsspec_enabled)
+    # docstring_parse
+    if docstring_parse_style is not None:
+        _set_docstring_parse_options(style=docstring_parse_style)
+    if docstring_parse_attribute_docstrings is not None:
+        _set_docstring_parse_options(attribute_docstrings=docstring_parse_attribute_docstrings)
+    # parse_optionals_as_positionals
     if isinstance(parse_optionals_as_positionals, bool):
         parsing_settings["parse_optionals_as_positionals"] = parse_optionals_as_positionals
     elif parse_optionals_as_positionals is not None:

jsonargparse/_core.py

@@ -77,8 +77,8 @@
     strip_meta,
 )
 from ._optionals import (
+    _get_config_read_mode,
     fsspec_support,
-    get_config_read_mode,
     import_fsspec,
     import_jsonnet,
     pyyaml_available,
@@ -619,7 +619,7 @@ def parse_path(
         Raises:
             ArgumentError: If the parsing fails error and exit_on_error=True.
         """
-        fpath = Path(cfg_path, mode=get_config_read_mode())
+        fpath = Path(cfg_path, mode=_get_config_read_mode())
         with change_to_path_dir(fpath):
             cfg_str = fpath.get_content()
             parsed_cfg = self.parse_string(
@@ -971,7 +971,7 @@ def _get_default_config_files(self) -> List[Tuple[Optional[str], Path]]:
 
         if len(default_config_files) > 0:
             with suppress(TypeError):
-                return [(k, Path(v, mode=get_config_read_mode())) for k, v in default_config_files]
+                return [(k, Path(v, mode=_get_config_read_mode())) for k, v in default_config_files]
         return []
 
     def get_default(self, dest: str) -> Any:

jsonargparse/_deprecated.py

@@ -22,6 +22,9 @@
     "ActionPath",
     "ActionPathList",
     "ParserError",
+    "get_config_read_mode",
+    "set_docstring_parse_options",
+    "set_config_read_mode",
     "set_url_support",
     "usage_and_exit_error_handler",
 ]
@@ -350,16 +353,66 @@
     """
     set_url_support was deprecated in v3.12.0 and will be removed in v5.0.0.
     Optional config read modes should now be set using function
-    set_config_read_mode.
+    set_parsing_settings.
 """
 )
 def set_url_support(enabled: bool):
     """Enables/disables URL support for config read mode."""
-    from ._optionals import get_config_read_mode, set_config_read_mode
+    from ._optionals import _get_config_read_mode, _set_config_read_mode
 
-    set_config_read_mode(
+    _set_config_read_mode(
         urls_enabled=enabled,
-        fsspec_enabled=True if "s" in get_config_read_mode() else False,
+        fsspec_enabled=True if "s" in _get_config_read_mode() else False,
+    )
+
+
+@deprecated(
+    """
+    set_config_read_mode was deprecated in v4.39.0 and will be removed in
+    v5.0.0. Optional config read modes should now be set using function
+    set_parsing_settings.
+"""
+)
+def set_config_read_mode(
+    urls_enabled: bool = False,
+    fsspec_enabled: bool = False,
+):
+    """Enables/disables optional config read modes."""
+    from ._optionals import _set_config_read_mode
+
+    _set_config_read_mode(
+        urls_enabled=urls_enabled,
+        fsspec_enabled=fsspec_enabled,
+    )
+
+
+@deprecated(
+    """
+    get_config_read_mode was deprecated in v4.39.0 and will be removed in
+    v5.0.0. The config read mode is internal and thus shouldn't be used.
+"""
+)
+def get_config_read_mode() -> str:
+    """Returns the current config reading mode."""
+    from ._optionals import _get_config_read_mode
+
+    return _get_config_read_mode()
+
+
+@deprecated(
+    """
+    set_docstring_parse_options was deprecated in v4.39.0 and will be removed in
+    v5.0.0. Docstring parse options should now be set using function
+    set_parsing_settings.
+"""
+)
+def set_docstring_parse_options(style=None, attribute_docstrings: Optional[bool] = None):
+    """Sets options for docstring parsing."""
+    from ._optionals import _set_docstring_parse_options
+
+    _set_docstring_parse_options(
+        style=style,
+        attribute_docstrings=attribute_docstrings,
     )
 
 

jsonargparse/_jsonnet.py

@@ -7,7 +7,7 @@
 from ._jsonschema import ActionJsonSchema
 from ._loaders_dumpers import get_loader_exceptions, load_value
 from ._optionals import (
-    get_config_read_mode,
+    _get_config_read_mode,
     get_jsonschema_exceptions,
     import_jsonnet,
     import_jsonschema,
@@ -157,7 +157,7 @@ def parse(
         fname = "snippet"
         snippet = jsonnet
         try:
-            fpath = Path(jsonnet, mode=get_config_read_mode())
+            fpath = Path(jsonnet, mode=_get_config_read_mode())
         except TypeError:
             pass
         else:

jsonargparse/_optionals.py

@@ -8,9 +8,7 @@
 from typing import Optional, Union
 
 __all__ = [
-    "get_config_read_mode",
-    "set_config_read_mode",
-    "set_docstring_parse_options",
+    "_get_config_read_mode",
 ]
 
 
@@ -165,7 +163,7 @@ def import_reconplogger(importer):
     return reconplogger
 
 
-def set_config_read_mode(
+def _set_config_read_mode(
     urls_enabled: bool = False,
     fsspec_enabled: bool = False,
 ):
@@ -183,7 +181,7 @@ def set_config_read_mode(
     def update_mode(flag, enabled):
         global _config_read_mode
         if enabled:
-            imports[flag]("set_config_read_mode")
+            imports[flag]("_set_config_read_mode")
             if flag not in _config_read_mode:
                 _config_read_mode = _config_read_mode.replace("f", "f" + flag)
         else:
@@ -193,20 +191,20 @@ def update_mode(flag, enabled):
     update_mode("s", fsspec_enabled)
 
 
-def get_config_read_mode() -> str:
+def _get_config_read_mode() -> str:
     """Returns the current config reading mode."""
     return _config_read_mode
 
 
-def set_docstring_parse_options(style=None, attribute_docstrings: Optional[bool] = None):
+def _set_docstring_parse_options(style=None, attribute_docstrings: Optional[bool] = None):
     """Sets options for docstring parsing.
 
     Args:
         style (docstring_parser.DocstringStyle): The docstring style to expect.
         attribute_docstrings: Whether to parse attribute docstrings (slower).
     """
     global _docstring_parse_options
-    dp = import_docstring_parser("set_docstring_parse_options")
+    dp = import_docstring_parser("_set_docstring_parse_options")
     if style is not None:
         if not isinstance(style, dp.DocstringStyle):
             raise ValueError(f"Expected style to be of type {dp.DocstringStyle}.")

jsonargparse/_typehints.py

@@ -870,9 +870,9 @@ def adapt_typehints(
         list_path = None
         if enable_path and type(val) is str:
             with suppress(TypeError):
-                from ._optionals import get_config_read_mode
+                from ._optionals import _get_config_read_mode
 
-                list_path = Path(val, mode=get_config_read_mode())
+                list_path = Path(val, mode=_get_config_read_mode())
                 val = list_path.get_content().splitlines()
         if isinstance(val, NestedArg) and subtypehints is not None:
             val = (prev_val[:-1] if isinstance(prev_val, list) else []) + [val]

jsonargparse/_util.py

@@ -39,8 +39,8 @@
 from ._deprecated import PathDeprecations
 from ._loaders_dumpers import json_compact_dump, load_value
 from ._optionals import (
+    _get_config_read_mode,
     fsspec_support,
-    get_config_read_mode,
     import_fsspec,
     import_requests,
     url_support,
@@ -135,7 +135,7 @@ def parse_value_or_config(
     cfg_path = None
     if enable_path and type(value) is str and value != "-":
         try:
-            cfg_path = Path(value, mode=get_config_read_mode())
+            cfg_path = Path(value, mode=_get_config_read_mode())
         except TypeError:
             pass
         else: