How to deprecate a feature

Since the 4.0.0 release, deprecation happens on a per-release basis. A functionality can be marked as deprecated using ~yt._maintenance.deprecation.issue_deprecation_warning, which takes a warning message and two version numbers, indicating the earliest release deprecating the feature and the one in which it will be removed completely.

The message should indicate a viable alternative to replace the deprecated feature at the user level. since and removal arguments should indicate in which release something was first deprecated, and when it’s expected to be removed. While since is required, removal is optional.

Here’s an example call.

If a whole function or class is marked as deprecated, it should be removed from doc/source/reference/api/api.rst.

Deprecating Derived Fields

Occasionally, one may want to deprecate a derived field in yt, normally because naming conventions for fields have changed, or simply because a field has outlived its usefulness. There are two ways to mark fields as deprecated in yt.

The first way is if you simply want to mark a specific derived field as deprecated. In that case, you call add_deprecated_field():

def _cylindrical_radial_absolute(field, data):
    """This field is deprecated and will be removed in a future version"""
    return np.abs(data[ftype, f"{basename}_cylindrical_radius"])


registry.add_deprecated_field(
    (ftype, f"cylindrical_radial_{basename}_absolute"),
    sampling_type="local",
    function=_cylindrical_radial_absolute,
    since="4.0",
    removal="4.1.0",
    units=field_units,
    validators=[ValidateParameter("normal")],
)

Note that the signature for add_deprecated_field() is the same as add_field(), with the exception of the since and removal arguments which indicate in what version the field was deprecated and in what version it will be removed. The effect is to add a warning to the logger when the field is first used:

import yt

ds = yt.load("GasSloshing/sloshing_nomag2_hdf5_plt_cnt_0100")
sp = ds.sphere("c", (100.0, "kpc"))
print(sp["gas", "cylindrical_radial_velocity_absolute"])

yt : [WARNING  ] 2021-03-09 16:30:47,460 The Derived Field
('gas', 'cylindrical_radial_velocity_absolute') is deprecated
as of yt v4.0.0 and will be removed in yt v4.1.0

The second way to deprecate a derived field is to take an existing field definition and change its name. In order to mark the original name as deprecated, use the alias() method and pass the since and removal arguments (see above) as a tuple in the deprecate keyword argument:

registry.alias(
    (ftype, "kinetic_energy"),
    (ftype, "kinetic_energy_density"),
    deprecate=("4.0.0", "4.1.0"),
)

Note that the old field name which is to be deprecated goes first, and the new, replacement field name goes second. In this case, the log message reports to the user what field they should use:

print(sp["gas", "kinetic_energy"])

yt : [WARNING  ] 2021-03-09 16:29:12,911 The Derived Field
('gas', 'kinetic_energy') is deprecated as of yt v4.0.0 and will be removed
in yt v4.1.0 Use ('gas', 'kinetic_energy_density') instead.

In most cases, the since and removal arguments should have a delta of one minor release, and that should be the minimum value. However, the developer is free to use their judgment about whether or not the delta should be multiple minor releases if the field has a long provenance.