Add deprecated_generic(), deprecated_class(), and deprecated_property()

DESCRIPTION

@@ -34,6 +34,7 @@ Suggests:
     callr,
     covr,
     knitr,
+    lifecycle,
     methods,
     rmarkdown,
     testthat (>= 3.2.0),

NAMESPACE

@@ -18,6 +18,8 @@ S3method(print,S7_any)
 S3method(print,S7_base_class)
 S3method(print,S7_class)
 S3method(print,S7_constructor)
+S3method(print,S7_deprecated_class)
+S3method(print,S7_deprecated_generic)
 S3method(print,S7_external_class)
 S3method(print,S7_external_generic)
 S3method(print,S7_generic)
@@ -87,6 +89,9 @@ export(class_raw)
 export(class_vector)
 export(convert)
 export(convert_lazy)
+export(deprecated_class)
+export(deprecated_generic)
+export(deprecated_property)
 export(method)
 export(method_explain)
 export(methods_register)

NEWS.md

@@ -13,6 +13,7 @@
 * `convert()` accepts a single unnamed list of property overrides when downcasting, as a shortcut for individual name-value pairs (#497).
 * `convert()` no longer errors when `from` is a base or S3 object and `to` is an S7 class that inherits from `from`'s class. The base/S3 value is now passed as `.data` to the `to` constructor (#537).
 * New `convert_lazy()` is a non-strict variant of `convert()` that returns `from` unchanged if it already inherits from `to`, preserving any extra properties instead of stripping them (#428).
+* New `deprecated_generic()`, `deprecated_class()`, and `deprecated_property()` provide a standard way to deprecate a generic, class, or property. Old code keeps working (calls delegate to the replacement and method registrations are silently redirected to it) but signals a deprecation warning. They use `.Deprecated()`-style warnings by default; set `method` to `"lifecycle(warn)"` or `"lifecycle(stop)"` to use the lifecycle package instead (#727, #730).
 * `method<-` now works for double-dispatch operators (e.g. `+`, `==`, `%*%`) with plain S3 or S4 classes, even when neither operand is an S7 object (#544).
 * `method<-` no longer embeds a copy of a generic owned by another package in your package namespace. Instead it returns a sentinel value that the new `S7_on_build()` removes from the namespace at build time; call `S7_on_build()` at the top level of `zzz.R` (see `vignette("packages")`) (#364).
 * `method<-` now accepts `NULL` to unregister an existing method, e.g. `method(foo, class_character) <- NULL` (#613).
@@ -28,6 +29,7 @@
 * `new_class()` generates a working default constructor for a subclass of a class with a custom constructor: the subclass takes `...` and forwards it to the parent constructor (followed by a named argument for each property the subclass adds), so the parent's argument defaults are matched and evaluated by the parent itself. This is a breaking change: such a subclass constructor no longer exposes the parent's properties as named or positional arguments, only via `...` (#609, #317).
 * `new_class()`'s default constructor now respects properties overridden in a subclass: the subclass's default is used (#467) and its setter is run during construction (#585). Values for overridden properties are passed to both the parent constructor and the new object, so a subclass can override a parent property whose default is mandatory.
 * `new_external_class()` creates a delayed reference to an S7 class in another package (or your own package, but not yet defined). It is useful for registering methods on classes from suggested packages (#573), for creating self-referential or mutually recursive classes (#250), and for extending class from other packages (#317).
+* `new_external_class()` references now resolve through exported aliases: the exported object no longer needs matching `@name` and `@package` properties, so a class renamed with an alias (`Foo <- Bar` or `deprecated_class()`) keeps working for downstream packages (#727).
 * `new_object()` now allows an abstract class's constructor to run when it is building the parent part of a subclass, so a subclass of an abstract class from another package (via `new_external_class()`) can be constructed (#717).
 * `new_object()` is now substantially faster, because each class caches its own name and dispatch vector, and class type detection has moved to C. Construction is 1.4x faster for a class that directly extends `S7_object`, rising to 2.4x faster for a class with 10 ancestors; `S7_inherits()` is 1.5x faster and `super()` is 2.1x faster (#723).
 * `new_object()` now gives an informative error when `.parent` is a class specification rather than an instance of the parent class (#409).

R/class-spec.R

@@ -23,6 +23,10 @@
 as_class <- function(x, arg = deparse(substitute(x))) {
   error_base <- sprintf("Can't convert `%s` to a valid class.", arg)
 
+  if (is_deprecated_class(x)) {
+    x <- deprecated_target(x)
+  }
+
   if (is_foundation_class(x)) {
     x
   } else if (is.null(x)) {