chore(utils): add as_of and removed_in to util.deprecated

ibis/backends/duckdb/datatypes.py

@@ -155,8 +155,7 @@ def struct():
 
 
 @util.deprecated(
-    instead=f"use {parse.__module__}.{parse.__name__}",
-    version="4.0",
+    instead=f"use {parse.__module__}.{parse.__name__}", as_of="4.0", removed_in="5.0"
 )
 def parse_type(*args, **kwargs):
     return parse(*args, **kwargs)

ibis/backends/impala/__init__.py

@@ -381,8 +381,7 @@ def _get_list(self, cur):
         return list(map(operator.itemgetter(0), tuples))
 
     @util.deprecated(
-        version='2.0',
-        instead='use a new connection to the database',
+        as_of="2.0", removed_in="5.0", instead="use a new connection to the database"
     )
     def set_database(self, name):
         # XXX The parent `Client` has a generic method that calls this same

ibis/backends/impala/client.py

@@ -115,7 +115,7 @@ def _new_cursor(self):
         wrapper.set_options()
         return wrapper
 
-    @util.deprecated(instead="", version="4.0")
+    @util.deprecated(instead="", as_of="4.0", removed_in="5.0")
     def ping(self):  # pragma: no cover
         self.pool.connect()._cursor.ping()
 

ibis/backends/pyspark/__init__.py

@@ -159,8 +159,7 @@ def version(self):
         return pyspark.__version__
 
     @util.deprecated(
-        version='2.0',
-        instead='use a new connection to the database',
+        as_of="2.0", removed_in="5.0", instead="use a new connection to the database"
     )
     def set_database(self, name):
         self._catalog.setCurrentDatabase(name)

ibis/expr/operations/core.py

@@ -6,9 +6,9 @@
 from public import public
 
 import ibis.expr.rules as rlz
+from ibis import util
 from ibis.common.graph import Node as Traversable
 from ibis.common.grounds import Concrete
-from ibis.util import deprecated
 
 if TYPE_CHECKING:
     import ibis.expr.datatypes as dt
@@ -23,7 +23,7 @@ def equals(self, other):
             )
         return self.__cached_equals__(other)
 
-    @deprecated(version='4.0', instead='remove intermediate .op() calls')
+    @util.deprecated(as_of='4.0', instead='remove intermediate .op() calls')
     def op(self):
         """Make `Node` backwards compatible with code that uses `Expr.op()`."""
         return self

ibis/expr/operations/relations.py

@@ -59,7 +59,7 @@ class DatabaseTable(PhysicalTable):
     schema = rlz.instance_of(sch.Schema)
     source = rlz.client
 
-    @util.deprecated(instead=".copy(name=new_name)", version="4.1")
+    @util.deprecated(instead=".copy(name=new_name)", as_of="4.1", removed_in="5.0")
     def change_name(self, new_name):
         return self.copy(name=new_name)
 

ibis/expr/operations/strings.py

@@ -4,9 +4,9 @@
 
 import ibis.expr.datatypes as dt
 import ibis.expr.rules as rlz
+from ibis import util
 from ibis.common.annotations import attribute
 from ibis.expr.operations.core import Unary, Value
-from ibis.util import deprecated
 
 
 @public
@@ -245,7 +245,9 @@ class ParseURL(Value):
     output_shape = rlz.shape_like("arg")
     output_dtype = dt.string
 
-    @deprecated(version="4.0", instead="use ExtractURLField and its subclasses")
+    @util.deprecated(
+        as_of="4.0", removed_in="5.0", instead="use ExtractURLField and its subclasses"
+    )
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 

ibis/expr/types/generic.py

@@ -481,7 +481,7 @@ def desc(self) -> ir.Value:
         """Sort an expression descending."""
         return ops.SortKey(self, ascending=False).to_expr()
 
-    @util.deprecated(version="5.0", instead="use `.as_table()`")
+    @util.deprecated(as_of="4.1", removed_in="5.0", instead="use `.as_table()`")
     def to_projection(self) -> ir.Table:
         return self.as_table()
 

ibis/expr/types/relations.py

@@ -211,7 +211,9 @@ def _ensure_expr(self, expr):
             return expr
 
     @util.deprecated(
-        version="5.0", instead="use a list comprehension and attribute/getitem syntax"
+        as_of="4.1",
+        removed_in="5.0",
+        instead="use a list comprehension and attribute/getitem syntax",
     )
     def get_columns(self, iterable: Iterable[str]) -> list[Column]:
         """Get multiple columns from the table.
@@ -234,7 +236,7 @@ def get_columns(self, iterable: Iterable[str]) -> list[Column]:
         """
         return list(map(self.get_column, iterable))
 
-    @util.deprecated(version="5.0", instead="use t.<name> or t[name]")
+    @util.deprecated(as_of="4.1", removed_in="5.0", instead="use t.<name> or t[name]")
     def get_column(self, name: str) -> Column:
         """Get a reference to a single column from the table.
 

ibis/expr/types/strings.py

@@ -4,18 +4,16 @@
 import operator
 from typing import TYPE_CHECKING, Any, Iterable, Literal, Sequence
 
-from ibis.util import deprecated
-
-if TYPE_CHECKING:
-    from ibis.expr import types as ir
-
 from public import public
 
 import ibis.expr.operations as ops
 from ibis import util
 from ibis.expr.types.core import _binop
 from ibis.expr.types.generic import Column, Scalar, Value
 
+if TYPE_CHECKING:
+    from ibis.expr import types as ir
+
 
 @public
 class StringValue(Value):
@@ -637,8 +635,9 @@ def to_timestamp(self, format_str: str) -> ir.TimestampValue:
         """
         return ops.StringToTimestamp(self, format_str).to_expr()
 
-    @deprecated(
-        version='4.0',
+    @util.deprecated(
+        as_of='4.0',
+        removed_in='5.0',
         instead=(
             'use .protocol(), .authroity(), .userinfo(), .host(), .file(), .path(), .query(), or .fragment().'
         ),

ibis/util.py

@@ -402,22 +402,30 @@ def flatten_iterable(iterable):
             yield item
 
 
-def deprecated_msg(name, *, instead, version=''):
-    msg = f'`{name}` is deprecated'
-    if version:
-        msg += f' as of v{version}'
+def deprecated_msg(name, *, instead, as_of="", removed_in=""):
+    msg = f"`{name}` is deprecated"
 
+    msgs = []
+
+    if as_of:
+        msgs.append(f"as of v{as_of}")
+
+    if removed_in:
+        msgs.append(f"removed in v{removed_in}")
+
+    if msgs:
+        msg += f" {', '.join(msgs)}"
     msg += f'; {instead}'
     return msg
 
 
-def warn_deprecated(name, *, instead, version='', stacklevel=1):
+def warn_deprecated(name, *, instead, as_of="", removed_in="", stacklevel=1):
     """Warn about deprecated usage.
 
     The message includes a stacktrace and what to do instead.
     """
 
-    msg = deprecated_msg(name, instead=instead, version=version)
+    msg = deprecated_msg(name, instead=instead, as_of=as_of, removed_in=removed_in)
     warnings.warn(msg, FutureWarning, stacklevel=stacklevel + 1)
 
 
@@ -448,18 +456,24 @@ def append_admonition(
     return docstr
 
 
-def deprecated(*, instead, version=''):
-    """Decorate to warn of deprecated usage, with stacktrace, and what to do instead."""
+def deprecated(*, instead: str, as_of: str = "", removed_in: str = ""):
+    """Decorate to warn of deprecated usage and what to do instead."""
 
     def decorator(func):
-        msg = deprecated_msg(func.__qualname__, instead=instead, version=version)
+        msg = deprecated_msg(
+            func.__qualname__, instead=instead, as_of=as_of, removed_in=removed_in
+        )
 
         func.__doc__ = append_admonition(func, msg=f"DEPRECATED: {msg}")
 
         @functools.wraps(func)
         def wrapper(*args, **kwargs):
             warn_deprecated(
-                func.__qualname__, instead=instead, version=version, stacklevel=2
+                func.__qualname__,
+                instead=instead,
+                as_of=as_of,
+                removed_in=removed_in,
+                stacklevel=2,
             )
             return func(*args, **kwargs)