add soft deprecation cycle to public methods

CHANGELOG.md

@@ -1,9 +1,16 @@
 # Upcoming
 
+### Deprecation (API)
+* Certain low-level functions have been marked as private (such as the former `nwbinspector.register_checks.auto_parse`) indicating they should not have been imported by downstream users. [#485](https://github.com/NeurodataWithoutBorders/nwbinspector/issues/485)
+* Various inappropriate imports from certain submodules have been hard deprecated (e.g., `from inspector_tools import natsorted`). [#485](https://github.com/NeurodataWithoutBorders/nwbinspector/issues/485)
+
+### Pending Deprecation (API)
+* The `inspector_tools`, `register_check`, and `` submodules have been soft deprecated and will be removed in the next major release. [#485](https://github.com/NeurodataWithoutBorders/nwbinspector/issues/485)
+
 ### Improvements
 
 * Update util function `is_ascending_series` to discard nan values and add `check_timestamps_without_nans` fun to check if timestamps contain NaN values [#476](https://github.com/NeurodataWithoutBorders/nwbinspector/issues/476)
-* Updated the import structure to match modern Python packaging standards. This may deprecate previous undesirable imports that may have been unintentionally exposed. [#485](https://github.com/NeurodataWithoutBorders/nwbinspector/issues/485)
+* Updated the import structure to match modern Python packaging standards. [#485](https://github.com/NeurodataWithoutBorders/nwbinspector/issues/485)
 
 
 

src/nwbinspector/inspector_tools/__init__.py

@@ -1,7 +1,26 @@
 import warnings
 
 message = (
-    "The 'inspector_tools' module has been deprecated. Please import the helper functions from the top-level package."
+    "The 'nwbinspector.nwbinspector' submodule has been deprecated. "
+    "Please import the helper functions from the top-level package."
 )
 
 warnings.warn(message=message, category=DeprecationWarning)
+
+# Still keep imports functional with warning for soft deprecation cycle
+# TODO: remove after 9/15/2024
+from .._configuration import (
+    INTERNAL_CONFIGS,
+    InspectorOutputJSONEncoder,
+    validate_config,
+    copy_check,
+    load_config,
+    configure_checks,
+)
+from .._inspection import (
+    inspect_all,
+    inspect_nwb,  # TODO: remove
+    inspect_nwbfile,
+    inspect_nwbfile_object,
+    run_checks,
+)

src/nwbinspector/nwbinspector/__init__.py

@@ -0,0 +1,10 @@
+import warnings
+
+message = "The 'inspector_tools' submodule has been deprecated. Please import the helper functions from the top-level package."
+
+warnings.warn(message=message, category=DeprecationWarning)
+
+# Still keep imports functional with warning for soft deprecation cycle
+# TODO: remove after 9/15/2024
+from .._organization import organize_messages, _get_report_header
+from .._formatting import format_message, MessageFormatter, FormatterOptions, print_to_console, save_report

src/nwbinspector/register_checks/__init__.py

@@ -0,0 +1,10 @@
+import warnings
+
+message = "The 'register_checks' submodule has been deprecated. Please import the helper functions from the top-level package."
+
+warnings.warn(message=message, category=DeprecationWarning)
+
+# Still keep imports functional with warning for soft deprecation cycle
+# TODO: remove after 9/15/2024
+from .._types import InspectorMessage, Importance, Severity
+from .._registration import register_check, available_checks

src/nwbinspector/version/__init__.py

@@ -0,0 +1,12 @@
+import warnings
+
+message = (
+    "The 'version' submodule has been deprecated. "
+    "Please import the version using `importlib.metadata.version('nwbinspector')`."
+)
+
+warnings.warn(message=message, category=DeprecationWarning)
+
+# Still keep imports functional with warning for soft deprecation cycle
+# TODO: remove after 9/15/2024
+from .._version import __version__