Added _ prefix to module names to be explicit about non-public API.

.pre-commit-config.yaml

@@ -1,3 +1,5 @@
+fail_fast: true
+
 ci:
   skip:
   - mypy

CHANGELOG.rst

@@ -30,6 +30,15 @@ Fixed
 - Stop subclass dive if you hit bad import (`#304
   <https://github.com/omni-us/jsonargparse/issues/304>`__).
 
+Changed
+^^^^^^^
+- Added ``_`` prefix to module names to be explicit about non-public API.
+
+Deprecated
+^^^^^^^^^^
+- Importing from original non-public module paths (without ``_`` prefix) now
+  gives a ``DeprecationWarning``. From v5.0.0 these imports will fail.
+
 
 v4.21.2 (2023-06-08)
 --------------------

jsonargparse/__init__.py

@@ -8,20 +8,21 @@
     ArgumentError,
 )
 
-from .actions import *  # noqa: F403
-from .cli import *  # noqa: F403
-from .core import *  # noqa: F403
-from .deprecated import *  # noqa: F403
-from .formatters import *  # noqa: F403
-from .jsonnet import *  # noqa: F403
-from .jsonschema import *  # noqa: F403
-from .link_arguments import *  # noqa: F403
-from .loaders_dumpers import *  # noqa: F403
-from .namespace import *  # noqa: F403
-from .optionals import *  # noqa: F403
-from .signatures import *  # noqa: F403
-from .typehints import *  # noqa: F403
-from .util import *  # noqa: F403
+from ._actions import *  # noqa: F403
+from ._cli import *  # noqa: F403
+from ._core import *  # noqa: F403
+from ._deprecated import *  # noqa: F403
+from ._deprecated import py36_set_deprecated_module_attributes
+from ._formatters import *  # noqa: F403
+from ._jsonnet import *  # noqa: F403
+from ._jsonschema import *  # noqa: F403
+from ._link_arguments import *  # noqa: F403
+from ._loaders_dumpers import *  # noqa: F403
+from ._namespace import *  # noqa: F403
+from ._optionals import *  # noqa: F403
+from ._signatures import *  # noqa: F403
+from ._typehints import *  # noqa: F403
+from ._util import *  # noqa: F403
 
 __all__ = [
     "ArgumentError",
@@ -35,36 +36,39 @@
 
 
 from . import (
-    actions,
-    cli,
-    core,
-    deprecated,
-    formatters,
-    jsonnet,
-    jsonschema,
-    link_arguments,
-    loaders_dumpers,
-    namespace,
-    optionals,
-    signatures,
-    typehints,
-    util,
+    _actions,
+    _cli,
+    _core,
+    _deprecated,
+    _formatters,
+    _jsonnet,
+    _jsonschema,
+    _link_arguments,
+    _loaders_dumpers,
+    _namespace,
+    _optionals,
+    _signatures,
+    _typehints,
+    _util,
 )
 
-__all__ += cli.__all__
-__all__ += core.__all__
-__all__ += signatures.__all__
-__all__ += typehints.__all__
-__all__ += link_arguments.__all__
-__all__ += jsonschema.__all__
-__all__ += jsonnet.__all__
-__all__ += actions.__all__
-__all__ += namespace.__all__
-__all__ += formatters.__all__
-__all__ += optionals.__all__
-__all__ += loaders_dumpers.__all__
-__all__ += util.__all__
-__all__ += deprecated.__all__
+__all__ += _cli.__all__
+__all__ += _core.__all__
+__all__ += _signatures.__all__
+__all__ += _typehints.__all__
+__all__ += _link_arguments.__all__
+__all__ += _jsonschema.__all__
+__all__ += _jsonnet.__all__
+__all__ += _actions.__all__
+__all__ += _namespace.__all__
+__all__ += _formatters.__all__
+__all__ += _optionals.__all__
+__all__ += _loaders_dumpers.__all__
+__all__ += _util.__all__
+__all__ += _deprecated.__all__
 
 
 __version__ = "4.21.2"
+
+
+py36_set_deprecated_module_attributes(globals())

jsonargparse/actions.py → jsonargparse/_actions.py

@@ -10,11 +10,11 @@
 from typing import Any, Dict, List, Optional, Tuple, Type, Union
 
 from ._common import is_subclass, parser_context
-from .loaders_dumpers import get_loader_exceptions, load_value
-from .namespace import Namespace, split_key, split_key_root
-from .optionals import FilesCompleterMethod, get_config_read_mode
-from .type_checking import ArgumentParser
-from .util import (
+from ._loaders_dumpers import get_loader_exceptions, load_value
+from ._namespace import Namespace, split_key, split_key_root
+from ._optionals import FilesCompleterMethod, get_config_read_mode
+from ._type_checking import ArgumentParser
+from ._util import (
     LoggerProperty,
     NoneType,
     Path,
@@ -179,7 +179,7 @@ def set_default_error():
 
     @staticmethod
     def apply_config(parser, cfg, dest, value) -> None:
-        from .link_arguments import skip_apply_links
+        from ._link_arguments import skip_apply_links
 
         with _ActionSubCommands.not_single_subcommand(), previous_config_context(cfg), skip_apply_links():
             kwargs = {"env": False, "defaults": False, "_skip_check": True, "_fail_no_subcommand": False}
@@ -334,7 +334,7 @@ def __init__(self, baseclass=None, **kwargs):
 
     def update_init_kwargs(self, kwargs):
         if get_typehint_origin(self._baseclass) == Union:
-            from .typehints import ActionTypeHint
+            from ._typehints import ActionTypeHint
 
             self._basename = iter_to_set_str(
                 c.__name__ for c in self._baseclass.__args__ if ActionTypeHint.is_subclass_typehint(c)
@@ -357,7 +357,7 @@ def __call__(self, *args, **kwargs):
         return self.print_help(args, self._baseclass, dest)
 
     def print_help(self, call_args, baseclass, dest):
-        from .typehints import resolve_class_path_by_name
+        from ._typehints import resolve_class_path_by_name
 
         parser, _, value, option_string = call_args
         try:

jsonargparse/cli.py → jsonargparse/_cli.py

@@ -3,11 +3,11 @@
 import inspect
 from typing import Any, Callable, Dict, List, Optional, Type, Union
 
-from .actions import ActionConfigFile, _ActionPrintConfig, remove_actions
-from .core import ArgumentParser
-from .deprecated import deprecation_warning_cli_return_parser
-from .optionals import get_doc_short_description
-from .util import default_config_option_help
+from ._actions import ActionConfigFile, _ActionPrintConfig, remove_actions
+from ._core import ArgumentParser
+from ._deprecated import deprecation_warning_cli_return_parser
+from ._optionals import get_doc_short_description
+from ._util import default_config_option_help
 
 __all__ = ["CLI"]
 

jsonargparse/_common.py

@@ -4,8 +4,8 @@
 from contextvars import ContextVar
 from typing import Optional, Union
 
-from .namespace import Namespace
-from .type_checking import ArgumentParser
+from ._namespace import Namespace
+from ._type_checking import ArgumentParser
 
 parent_parser: ContextVar["ArgumentParser"] = ContextVar("parent_parser")
 parser_capture: ContextVar[bool] = ContextVar("parser_capture", default=False)
@@ -57,7 +57,7 @@ def is_dataclass_like(cls) -> bool:
         return True
     classes = [c for c in inspect.getmro(cls) if c != object]
     all_dataclasses = all(dataclasses.is_dataclass(c) for c in classes)
-    from .optionals import attrs_support, pydantic_support
+    from ._optionals import attrs_support, pydantic_support
 
     if not all_dataclasses and pydantic_support:
         import pydantic.utils

jsonargparse/core.py → jsonargparse/_core.py

@@ -22,8 +22,7 @@
     Union,
 )
 
-from ._common import is_dataclass_like, is_subclass, lenient_check, parser_context
-from .actions import (
+from ._actions import (
     ActionConfigFile,
     ActionParser,
     _ActionConfigLoad,
@@ -39,12 +38,13 @@
     parent_parsers,
     previous_config,
 )
-from .deprecated import ParserDeprecations
-from .formatters import DefaultHelpFormatter, empty_help, get_env_var
-from .jsonnet import ActionJsonnet, ActionJsonnetExtVars
-from .jsonschema import ActionJsonSchema
-from .link_arguments import ActionLink, ArgumentLinking
-from .loaders_dumpers import (
+from ._common import is_dataclass_like, is_subclass, lenient_check, parser_context
+from ._deprecated import ParserDeprecations
+from ._formatters import DefaultHelpFormatter, empty_help, get_env_var
+from ._jsonnet import ActionJsonnet, ActionJsonnetExtVars
+from ._jsonschema import ActionJsonSchema
+from ._link_arguments import ActionLink, ArgumentLinking
+from ._loaders_dumpers import (
     check_valid_dump_format,
     dump_using_format,
     get_loader_exceptions,
@@ -53,7 +53,7 @@
     set_omegaconf_loader,
     yaml_load,
 )
-from .namespace import (
+from ._namespace import (
     Namespace,
     is_meta_key,
     patch_namespace,
@@ -62,18 +62,18 @@
     split_key_leaf,
     strip_meta,
 )
-from .optionals import (
+from ._optionals import (
     argcomplete_autocomplete,
     argcomplete_namespace,
     fsspec_support,
     get_config_read_mode,
     import_fsspec,
     import_jsonnet,
 )
-from .parameter_resolvers import UnknownDefault
-from .signatures import SignatureArguments
-from .typehints import ActionTypeHint, is_subclass_spec
-from .util import (
+from ._parameter_resolvers import UnknownDefault
+from ._signatures import SignatureArguments
+from ._typehints import ActionTypeHint, is_subclass_spec
+from ._util import (
     Path,
     argument_error,
     change_to_path_dir,
@@ -1401,7 +1401,7 @@ def env_prefix(self) -> Union[bool, str]:
     @env_prefix.setter
     def env_prefix(self, env_prefix: Union[bool, str]):
         if env_prefix is None:
-            from .deprecated import (
+            from ._deprecated import (
                 deprecation_warning,
                 env_prefix_property_none_message,
             )
@@ -1460,7 +1460,7 @@ def dump_header(self, dump_header: Optional[List[str]]):
         self._dump_header = dump_header
 
 
-from .deprecated import instantiate_subclasses_patch, parse_as_dict_patch  # noqa: E402
+from ._deprecated import instantiate_subclasses_patch, parse_as_dict_patch  # noqa: E402
 
 instantiate_subclasses_patch()
 if "SPHINX_BUILD" not in os.environ: