Trac #33114: Feature.require vs. is_present, is_functional

(from slabbe in
https://trac.sagemath.org/ticket/33092?replyto=23#comment:23)

Maybe changes needs to be done with respect to `is_present()`,
`is_functional()` and `require()`. In particular, I have the following
questions for @mkoeppe:
- why `Feature.require()` does not check that `is_functional()` is True?
- should `is_present()` always return False when `is_functional` return
False (even if the vocabulary that is used should logically allow it)?

URL: https://trac.sagemath.org/33114
Reported by: mkoeppe
Ticket author(s): Matthias Koeppe
Reviewer(s): Sébastien Labbé

src/sage/features/__init__.py

@@ -571,6 +571,10 @@ def is_functional(self):
         r"""
         Return whether an executable in the path is functional.
 
+        This method is used internally and can be overridden in subclasses
+        in order to implement a feature test. It should not be called directly.
+        Use :meth:`Feature.is_present` instead.
+
         EXAMPLES:
 
         The function returns ``True`` unless explicitly overwritten::

src/sage/features/imagemagick.py

@@ -115,8 +115,6 @@ class ImageMagick(JoinFeature):
         sage: from sage.features.imagemagick import ImageMagick
         sage: ImageMagick().is_present()  # optional - imagemagick
         FeatureTestResult('imagemagick', True)
-        sage: ImageMagick().is_functional()  # optional - imagemagick
-        FeatureTestResult('imagemagick', True)
     """
     def __init__(self):
         r"""

src/sage/features/join_feature.py

@@ -69,12 +69,26 @@ def is_functional(self):
         r"""
         Test whether the join feature is functional.
 
+        This method is deprecated. Use :meth:`Feature.is_present` instead.
+
         EXAMPLES::
 
             sage: from sage.features.latte import Latte
             sage: Latte().is_functional()  # optional - latte_int
+            doctest:warning...
+            DeprecationWarning: method JoinFeature.is_functional; use is_present instead
+            See https://trac.sagemath.org/33114 for details.
             FeatureTestResult('latte_int', True)
         """
+        try:
+            from sage.misc.superseded import deprecation
+        except ImportError:
+            # The import can fail because sage.misc.superseded is provided by
+            # the distribution sagemath-objects, which is not an
+            # install-requires of the distribution sagemath-environment.
+            pass
+        else:
+            deprecation(33114, 'method JoinFeature.is_functional; use is_present instead')
         for f in self._features:
             test = f.is_functional()
             if not test: