deprecate: Add deprecation warning for diffpy.Structure

news/dep-warning1.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* Add deprecation warning for ``diffpy.Structure`` import.
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/structure/__init__.py

@@ -33,8 +33,10 @@
     * SymmetryError
 """
 
-# Interface definitions ------------------------------------------------------
 
+import sys
+
+import diffpy.structure as _structure
 from diffpy.structure.atom import Atom
 from diffpy.structure.lattice import Lattice
 from diffpy.structure.parsers import getParser
@@ -45,6 +47,28 @@
 # package version
 from diffpy.structure.version import __version__
 
+# Deprecations -------------------------------------------------------
+
+
+# @deprecated
+# custom deprecator for diffpy.Structure module
+class DeprecatedStructureModule:
+    """Proxy for backward compatibility of diffpy.Structure."""
+
+    def __getattr__(self, name):
+        import warnings
+
+        warnings.warn(
+            "Module 'diffpy.Structure' is deprecated and will be removed in version 4.0. "
+            "Use 'diffpy.structure' instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return getattr(_structure, name)
+
+
+sys.modules["diffpy.Structure"] = DeprecatedStructureModule()
+
 # top level routines