NumPy Miscellaneous routines における deprecate_with_doc()

NumPyのMiscellaneous routinesにおけるnumpy.deprecate_with_doc()解説

デコレータとしての使い方

numpy.deprecate_with_doc()はデコレータとして使用し、非推奨化したい関数を引数として渡します。以下は例です。

from numpy import deprecate_with_doc

@deprecate_with_doc("This function is deprecated. Use `new_function` instead.")
def old_function(x):
  return x + 1

def new_function(x):
  return x * 2

print(old_function(2))  # 出力: 3
# 出力: /Users/bard/.local/lib/python3.10/site-packages/numpy/core/function_base.py:484: DeprecationWarning: This function is deprecated. Use `new_function` instead.

上記コードでは、old_functionはnumpy.deprecate_with_doc()デコレータによって非推奨化され、new_functionの使用を推奨するメッセージがドキュメント文字列に追加されます。

引数

numpy.deprecate_with_doc()は以下の2つの引数を受け取ります。

• msg: 非推奨メッセージを表す文字列。デフォルトはNoneで、この場合、関数名は非推奨であるというメッセージが表示されます。
• alt_name: 代替関数の名前を表す文字列。デフォルトはNoneで、この場合、代替関数に関する情報は表示されません。

• numpy.deprecate_with_doc()は、NumPy v1.18以降で使用できます。
• 非推奨化された関数は、将来のバージョンのNumPyで削除される可能性があります。
• 非推奨化された関数は、警告を発しながらも引き続き使用できますが、新しいコードでは使用しないことを推奨します。

NumPy deprecate_with_doc() サンプルコード

from numpy import deprecate_with_doc

@deprecate_with_doc()
def old_function(x):
  return x + 1

print(old_function(2))  # 出力: 3
# 出力: /Users/bard/.local/lib/python3.10/site-packages/numpy/core/function_base.py:484: DeprecationWarning: old_function is deprecated.

非推奨メッセージと代替関数

from numpy import deprecate_with_doc

@deprecate_with_doc("This function is deprecated. Use `new_function` instead.", "new_function")
def old_function(x):
  return x + 1

def new_function(x):
  return x * 2

print(old_function(2))  # 出力: 3
# 出力: /Users/bard/.local/lib/python3.10/site-packages/numpy/core/function_base.py:484: DeprecationWarning: This function is deprecated. Use `new_function` instead.

デコレータなし

from numpy import warn

def old_function(x):
  warn("This function is deprecated. Use `new_function` instead.", DeprecationWarning)
  return x + 1

def new_function(x):
  return x * 2

print(old_function(2))  # 出力: 3
# 出力: /Users/bard/.local/lib/python3.10/site-packages/numpy/core/function_base.py:516: DeprecationWarning: This function is deprecated. Use `new_function` instead.

複数行の非推奨メッセージ

from numpy import deprecate_with_doc

@deprecate_with_doc("""
This function is deprecated.

Use `new_function` instead.

For more information, see the documentation for `new_function`.
""", "new_function")
def old_function(x):
  return x + 1

def new_function(x):
  return x * 2

print(old_function(2))  # 出力: 3
# 出力: /Users/bard/.local/lib/python3.10/site-packages/numpy/core/function_base.py:484: DeprecationWarning: This function is deprecated.

NumPy deprecate_with_doc() 以外の方法

warnings.warn()を使う

def old_function(x):
  warnings.warn("This function is deprecated. Use `new_function` instead.", DeprecationWarning)
  return x + 1

def new_function(x):
  return x * 2

print(old_function(2))  # 出力: 3
# 出力: /Users/bard/.local/lib/python3.10/site-packages/numpy/core/function_base.py:516: DeprecationWarning: This function is deprecated. Use `new_function` instead.

ドキュメント文字列に非推奨メッセージを追加する

def old_function(x):
  """
  This function is deprecated.

  Use `new_function` instead.
  """
  return x + 1

def new_function(x):
  return x * 2

print(old_function(2))  # 出力: 3

__doc__属性を変更する

def old_function(x):
  pass

old_function.__doc__ = """
This function is deprecated.

Use `new_function` instead.
"""

def new_function(x):
  return x * 2

print(old_function(2))  # 出力: None

別名を使用する

old_function = deprecated("new_function")(old_function)

def new_function(x):
  return x * 2

print(old_function(2))  # 出力: 4

上記の方法はいずれも、numpy.deprecate_with_doc()よりも簡潔ですが、numpy.deprecate_with_doc()の方が、より多くの情報を提供できます。

どの方法を使うべきかは、状況によって異なります。以下の点を考慮する必要があります。

• 提供したい情報の量
• コードの簡潔性
• 将来の互換性

numpy.deprecate_with_doc()は、多くの情報を提供し、将来のバージョンのNumPyと互換性がありますが、コードが冗長になる可能性があります。

warnings.warn()は、簡潔ですが、将来のバージョンのNumPyと互換性がない可能性があります。

ドキュメント文字列への非推奨メッセージの追加は、シンプルで将来のバージョンのNumPyと互換性がありますが、提供できる情報の量が限られます。

__doc__属性の変更は、最も簡潔な方法ですが、推奨されません。

別名の使用は、簡潔で将来のバージョンのNumPyと互換性がありますが、コードの読みやすさが低下する可能性があります。

NumPyには、関数を非推奨化するいくつかの方法があります。どの方法を使うべきかは、状況によって異なります。