如何将函数标记为`@ deprecate`d? [英] How to mark functions as `@deprecate`d?

问题描述

(问题指的是Julia版本v1.5)

我试图了解@deprecate宏在Julia中的工作方式.遗憾的是，文档不清楚:

I'm trying to understand how the @deprecate macro works in Julia. The documentation is unfortunately not clear to me:

@deprecate old new [ex=true]

弃用旧方法，并指定新的替换调用.防止 通过将ex设置为false，@ deprecate不再导出old. @不赞成 定义一个与旧签名相同的新方法.

Deprecate method old and specify the replacement call new. Prevent @deprecate from exporting old by setting ex to false. @deprecate defines a new method with the same signature as old.

警告: 从Julia 1.5开始，在未设置--depwarn = yes标志的情况下运行julia时，@ deprecate定义的函数不会显示警告，因为--depwarn选项的默认值为no.警告是从Pkg.test()运行的测试中打印出来的.

Warning: As of Julia 1.5, functions defined by @deprecate do not print warning when julia is run without the --depwarn=yes flag set, as the default value of --depwarn option is no. The warnings are printed from tests run by Pkg.test().

示例

julia> @deprecate old(x) new(x)

old(具有1个方法的泛型函数)

old (generic function with 1 method)

julia> @deprecate old(x) new(x)

假旧(具有1个方法的泛型函数)

false old (generic function with 1 method)

那我该怎么办?

function old(x::Int)
    print("Old behavior")
end

function new(x::Int)
    print("New behavior")
end

# Adding true/false argument doesn't change my observations.
@deprecate old(x) new(x)  # false 


old(3)
# Prints "Old behaviour". No warning. 
# Also: The deprecation is not mentioned in the help (julia>? old)

此@deprecate宏的目的似乎是替换功能?我发现这违反直觉.

The aim of this @deprecate macro seems to be replacing functions? I find that counterintuitive. How can mark a function as deprecated (i.e. users should receive a warning and a hint what to use as a replacement, also it should be in the documentation)?

我注意到我的错误.签名(在我的情况下为::Int)必须相同才能起作用.但是，如何获得警告?

edit: I noticed my error. The signatures (in my case the ::Int) have to be identical for this to work. However, how do I get a warning?

推荐答案

想象一下，您将此方法作为版本1中库的公共API的一部分.

Imagine you have this method as part of the public API of your library in version 1:

# v1.0.0
mult3(x::Int) = 3x

在版本2中，您想停止支持mult3(这是一项重大更改).但是，使用更通用的方法仍然可以使用相同的功能:

In version 2, you'd like to stop supporting mult3 (which is a breaking change). But the same feature will still be available using a more general method:

# v2.0.0
mult(x, y) = x * y

版本1的用户习惯使用mult3，这意味着他们的代码在更新到v2时会中断.因此，您可能想发布v1.x系列中的中间版本，该版本中存在mult3，但已根据mult弃用并实现了该版本:

Users of version 1 are used to using mult3, which means that their code will break when they will update to v2. Therefore, you might want to release an intermediate version in the v1.x family, where mult3 exists but is deprecated and implemented in terms of mult:

# v1.1 - transition

# This is the new API for v2
mult(x, y) = x*y

# The old API is still supported, but deprecated and implemented using the old one
@deprecate mult3(x::Int) mult(3, x)

# The above is more or less equivalent to defining
# function mult3(x::Int)
#    # print an error message is `--depwarn` has been set
#    return mult(3, x)
# end

v1.x的最新版本并未破坏v1 API，但是调用不推荐使用的方法的用户将看到以下消息，以帮助他们过渡到较新的v2 API:

The v1 API is not broken in late v1.x versions, but users calling deprecated methods will see the following kind of messages to help them transition to the newer v2 API:

julia> mult3(14)
┌ Warning: `mult3(x::Int)` is deprecated, use `mult(3, x)` instead.
│   caller = top-level scope at REPL[3]:1
└ @ Core REPL[3]:1
42

(但是从Julia 1.5开始，只有在Julia的命令行中提供了--depwarn=yes或出现在由Pkg.test()运行的测试套件中的警告才会显示)

(but starting with Julia 1.5, the warning will only be shown if --depwarn=yes has been provided in Julia's command line or if it appears in a test suite run by Pkg.test())

或者，如注释中所述，您可能希望保留旧的实现，只在用户调用它时警告用户.为此，您可以直接使用Base.depwarn:

Alternatively, and as mentioned in comments, you may want to leave the old implementation around, simply warning users when they call it. To this end, you can use Base.depwarn directly:

# v1.1 - transition

# This is the new API for v2
mult(x, y) = x*y

# The old API is still supported, but deprecated
# It is implemented by itself:
function mult3(x)
    Base.depwarn("`mult3(x)` is deprecated, use `mult(3,x)` instead.", :mult3)
    return 3x
end

在Julia的命令行中提供了--depwarn=yes时，这会产生与@deprecate相同的警告:

When --depwarn=yes has been provided in Julia's command line, this produces the same kind of warning as @deprecate:

julia> mult3(14)
┌ Warning: `mult3(x)` is deprecated, use `mult(3,x)` instead.
│   caller = top-level scope at REPL[4]:1
└ @ Core REPL[4]:1
42

从Julia 1.6开始，depwarn会接受关键字参数来强制发出警告，即使用户没有要求使用--depwarn=yes来发出警告:

Starting with Julia 1.6, depwarn will accept a keyword argument to force warning emission even when users haven't asked for them with --depwarn=yes:

julia> Base.depwarn("Foo is deprecated", :foo, force=true)
┌ Warning: Foo is deprecated
│   caller = ip:0x0
└ @ Core :-1

这篇关于如何将函数标记为`@ deprecate`d?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！