Repository: ipython/ipython

Issue:
deprecate IPython.utils.tz
It is not used in IPython itself, and uses functions that are marked for removal in Python


Discussion:
Hey @Carreau, I'm currently looking for a good first issue in the IPython project and this looks like one to me. :)

I couldn't find anything in the docs related to the deprecation process of IPython and looking at the code base, there are different approaches to this. Do you have an opinion on this?
There are multiple things to do:

1) add documentation (various docstrings)
2) Use a module level getattr to warn on _import, you can get inspiration [from scipy misc](https://github.com/scipy/scipy/blob/ae9dc13161cb227d7651c58dc47971193510221d/scipy/misc/__init__.py)
3) emit a warning when the function is called (when relevant).

No need to do all all once even just one docstring in one PR is already a good start. 
Thank you for the quick answer! That sounds manageable, I'll have a look. :+1: 

Resolving patch:
diff --git a/IPython/utils/tz.py b/IPython/utils/tz.py
--- a/IPython/utils/tz.py
+++ b/IPython/utils/tz.py
@@ -3,29 +3,56 @@
 Timezone utilities
 
 Just UTC-awareness right now
+
+Deprecated since IPython 8.19.0.
 """
 
-#-----------------------------------------------------------------------------
+# -----------------------------------------------------------------------------
 #  Copyright (C) 2013 The IPython Development Team
 #
 #  Distributed under the terms of the BSD License.  The full license is in
 #  the file COPYING, distributed as part of this software.
-#-----------------------------------------------------------------------------
+# -----------------------------------------------------------------------------
 
-#-----------------------------------------------------------------------------
+# -----------------------------------------------------------------------------
 # Imports
-#-----------------------------------------------------------------------------
+# -----------------------------------------------------------------------------
 
+import warnings
 from datetime import tzinfo, timedelta, datetime
 
-#-----------------------------------------------------------------------------
+# -----------------------------------------------------------------------------
 # Code
-#-----------------------------------------------------------------------------
+# -----------------------------------------------------------------------------
+__all__ = ["tzUTC", "utc_aware", "utcfromtimestamp", "utcnow"]
+
+
 # constant for zero offset
 ZERO = timedelta(0)
 
+
+def __getattr__(name):
+    if name not in __all__:
+        err = f"IPython.utils.tz is deprecated and has no attribute {name}"
+        raise AttributeError(err)
+
+    _warn_deprecated()
+
+    return getattr(name)
+
+
+def _warn_deprecated():
+    msg = "The module `IPython.utils.tz` is deprecated and will be completely removed."
+    warnings.warn(msg, category=DeprecationWarning, stacklevel=2)
+
+
 class tzUTC(tzinfo):
-    """tzinfo object for UTC (zero offset)"""
+    """tzinfo object for UTC (zero offset)
+
+    Deprecated since IPython 8.19.0.
+    """
+
+    _warn_deprecated()
 
     def utcoffset(self, d):
         return ZERO
@@ -38,11 +65,18 @@ def dst(self, d):
 
 
 def utc_aware(unaware):
-    """decorator for adding UTC tzinfo to datetime's utcfoo methods"""
+    """decorator for adding UTC tzinfo to datetime's utcfoo methods
+
+    Deprecated since IPython 8.19.0.
+    """
+
     def utc_method(*args, **kwargs):
+        _warn_deprecated()
         dt = unaware(*args, **kwargs)
         return dt.replace(tzinfo=UTC)
+
     return utc_method
 
+
 utcfromtimestamp = utc_aware(datetime.utcfromtimestamp)
 utcnow = utc_aware(datetime.utcnow)


Test patch: