弃用政策¶
aeon releases 遵循 semantic versioning。发布号表示
一般来说，如果某个更改在更新到下一个版本时可能会意外导致使用aeon的代码崩溃，那么应该将其弃用，以便给用户一个准备的机会。
何时弃用：
移除或重命名公共类或函数
移除或重命名公共类参数或函数参数
添加没有默认值的位置参数
弃用警告应至少包含一个完整的小版本周期，然后才能进行更改或删除。如果某个项目在v0.6.0发布时被弃用，它可以在v0.7.0中被移除。如果某个项目在v0.6.0和v0.7.0之间被弃用（例如v0.6.1），它可以在v0.8.0中被移除。
请注意，弃用政策不一定适用于我们归类为仍处于实验阶段的模块。目前实验性的模块有：
anomaly_detectionforecastingsegmentationsimilarity_search可视化
当我们引入一个新模块时，我们可能会将其分类为实验性的，直到API稳定为止。我们会尽量避免对实验性模块进行剧烈的更改，但在这些情况下，我们需要保留设计的灵活性。
弃用过程¶
要弃用函数和类，请编写一个“TODO”注释，说明代码应在哪个版本中删除，并使用deprecated包发出警告。这会引发一个FutureWarning，说明该功能已被弃用。从deprecated.sphinx导入，以便弃用消息自动添加到文档中。
在重命名项目时，理想情况下，当添加弃用警告时，新名称的功能应该已经可用。例如，包括位置参数的旧名称和新名称，或者具有旧名称和新名称的函数/类。这并不总是可能的，但这样做是良好的实践。
在大多数情况下，重命名或删除函数和类的关键字参数时，不需要使用deprecated包。可以将参数的默认值设置为"deprecated"。如果更改此值，可以引发FutureWarning。这将弃用警告隔离到参数，而不是整个函数或类。如果重命名，可以同时添加新的关键字参数，并警告用户使用新的关键字参数。
如果下一个版本号尚未确定，请使用下一个次要版本号作为弃用包的version参数。
示例¶
函数和方法¶
弃用一个函数。
from deprecated.sphinx import deprecated
# TODO: remove in v0.7.0
@deprecated(
version="0.6.0",
reason="my_function will be removed in v0.7.0.",
category=FutureWarning,
)
def my_function(x, y):
"""Return x + y."""
return x + y
弃用一个函数以添加一个新的位置参数。在某些情况下，您可以添加一个带有默认值的关键字参数，以简化过渡。
from deprecated.sphinx import deprecated
# TODO: remove in v0.7.0 and remove z default
@deprecated(
version="0.6.0",
reason="my_function will be include a third positional argument 'z' in v0.7.0, used for reasons.",
category=FutureWarning,
)
def my_function(x, y, z=0):
"""Return x + y + z."""
return x + y + z
弃用一个类方法以移除一个位置参数。
from deprecated.sphinx import deprecated
class MyClass:
"""Contains my_method."""
# TODO: remove in v0.7.0
@deprecated(
version="0.6.0",
reason="my_method first positional argument 'x' will be removed in v0.7.0.",
category=FutureWarning,
)
def my_method(self, x, y):
"""Return y."""
return y
类¶
弃用一个类。
由于此示例在补丁版本中已弃用，因此无法从下一个次要版本中移除。
from deprecated.sphinx import deprecated
# TODO: remove in v0.8.0
@deprecated(
version="0.6.1",
reason="MyClass will be removed in v0.8.0.",
category=FutureWarning,
)
class MyClass:
"""Exists (for now)."""
pass
弃用一个公共类属性。如果我们正在重命名，我们可以添加新名称并引导用户使用新名称，同时更新两者。
from deprecated.sphinx import deprecated
# TODO: remove in v0.7.0
@deprecated(
version="0.6.0",
reason="The my_attribute attribute will be removed in v0.7.0.",
category=FutureWarning,
)
class MyClass:
"""Contains my_attribute."""
my_attribute = 1
弃用一个类参数。
import warnings
class MyClass:
"""Contains x and y.
Parameters
----------
x : int, default=1
The x parameter.
y : int, default="deprecated"
The y parameter.
Deprecated and will be removed in v0.7.0.
"""
# TODO remove 'y' in v0.7.0
def __init__(self, x=1, y="deprecated"):
self.x = x
if y != "deprecated":
warnings.warn("The 'y' parameter will be removed in v0.7.0.", FutureWarning)
重命名¶
弃用一个类参数以重命名它。
import warnings
class MyClass:
"""Does stuff.
Parameters
----------
x : int, default=1
The x parameter.
new_param : int, default=2
New identifier for old_param.
old_param : int, default="deprecated"
Old identifier for new_param. If used will set new_param.
Deprecated and will be removed in v0.7.0.
"""
# TODO remove 'old_param' in v0.7.0
def __init__(self, x=1, new_param=2, old_param="deprecated"):
self.x = x
self.new_param = new_param
if old_param != "deprecated":
warnings.warn("The 'old_param' parameter will be removed in v0.7.0. Use 'new_param' instead.", FutureWarning)
self.new_param = old_param
弃用一个类以重命名它。
from deprecated.sphinx import deprecated
class MyNewClass:
"""Exists."""
@staticmethod
def return_one():
"""Return 1."""
return 1
# TODO: remove in v0.7.0
@deprecated(
version="0.6.0",
reason="The MyOldClass class has been renamed to MyNewClass and will be removed in v0.7.0.",
category=FutureWarning,
)
class MyOldClass(MyNewClass):
"""Exists."""
pass
弃用一个函数以重命名它。
from deprecated.sphinx import deprecated
def my_new_function(x, y):
"""Return x + y."""
return x + y
# TODO: remove in v0.7.0
@deprecated(
version="0.6.0",
reason="my_old_function has been renamed to my_new_function and will be removed in v0.7.0.",
category=FutureWarning,
)
def my_old_function(x, y):
"""Return x + y."""
return my_new_function(x, y)