From 47e1ecb748c5d86fb8285babd5521c3a3fc4015b Mon Sep 17 00:00:00 2001
From: CodyCBakerPhD <codycbakerphd@gmail.com>
Date: Tue, 13 Aug 2024 13:10:25 -0400
Subject: [PATCH] add soft deprecation cycle to public methods

---
 CHANGELOG.md                                 |  9 ++++++++-
 src/nwbinspector/inspector_tools/__init__.py | 21 +++++++++++++++++++-
 src/nwbinspector/nwbinspector/__init__.py    | 10 ++++++++++
 src/nwbinspector/register_checks/__init__.py | 10 ++++++++++
 src/nwbinspector/version/__init__.py         | 12 +++++++++++
 5 files changed, 60 insertions(+), 2 deletions(-)
 create mode 100644 src/nwbinspector/nwbinspector/__init__.py
 create mode 100644 src/nwbinspector/register_checks/__init__.py
 create mode 100644 src/nwbinspector/version/__init__.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1009bd935..da2b326c0 100644
--- a/CHANGELOG.md
+++ b/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)
 
 
 
diff --git a/src/nwbinspector/inspector_tools/__init__.py b/src/nwbinspector/inspector_tools/__init__.py
index bcc1d67a4..6fa9d0933 100644
--- a/src/nwbinspector/inspector_tools/__init__.py
+++ b/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,
+)
diff --git a/src/nwbinspector/nwbinspector/__init__.py b/src/nwbinspector/nwbinspector/__init__.py
new file mode 100644
index 000000000..db27f589c
--- /dev/null
+++ b/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
diff --git a/src/nwbinspector/register_checks/__init__.py b/src/nwbinspector/register_checks/__init__.py
new file mode 100644
index 000000000..249d4d0e6
--- /dev/null
+++ b/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
diff --git a/src/nwbinspector/version/__init__.py b/src/nwbinspector/version/__init__.py
new file mode 100644
index 000000000..8f08c343b
--- /dev/null
+++ b/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__