Testing for features of the environment at runtime¶
A computation can require a certain package to be installed in the runtime
environment. Abstractly such a package describes a :class`Feature` which can
be tested for at runtime. It can be of various kinds, most prominently an
Executable
in the PATH or an additional package for some installed
system such as a GapPackage
.
AUTHORS:
- Julian Rüth (2016-04-07): Initial version
- Jeroen Demeyer (2018-02-12): Refactoring and clean up
EXAMPLES:
Some generic features are available for common cases. For example, to
test for the existence of a binary, one can use an Executable
feature:
sage: from sage.features import Executable
sage: Executable(name="sh", executable="sh").is_present()
FeatureTestResult('sh', True)
Here we test whether the grape GAP package is available:
sage: from sage.features.gap import GapPackage
sage: GapPackage("grape", spkg="gap_packages").is_present() # optional: gap_packages
FeatureTestResult('GAP package grape', True)
Note that a FeatureTestResult
acts like a bool in most contexts:
sage: if Executable(name="sh", executable="sh").is_present(): "present."
'present.'
When one wants to raise an error if the feature is not available, one
can use the require
method:
sage: Executable(name="sh", executable="sh").require()
sage: Executable(name="random", executable="randomOochoz6x", spkg="random", url="http://rand.om").require()
Traceback (most recent call last):
...
FeatureNotPresentError: random is not available.
Executable 'randomOochoz6x' not found on PATH.
To install random you can try to run 'sage -i random'.
Further installation instructions might be available at http://rand.om.
As can be seen above, features try to produce helpful error messages.
-
sage.features.
CythonFeature
¶ A
Feature
which describes the ability to compile and import a particular piece of Cython code.To test the presence of
name
, the cython compiler is run ontest_code
and the resulting module is imported.EXAMPLES:
sage: from sage.features import CythonFeature sage: fabs_test_code = ''' ....: cdef extern from "<math.h>": ....: double fabs(double x) ....: ....: assert fabs(-1) == 1 ....: ''' sage: fabs = CythonFeature("fabs", test_code=fabs_test_code, spkg="gcc", url="https://gnu.org") sage: fabs.is_present() FeatureTestResult('fabs', True)
Test various failures:
sage: broken_code = '''this is not a valid Cython program!''' sage: broken = CythonFeature("broken", test_code=broken_code) sage: broken.is_present() FeatureTestResult('broken', False)
sage: broken_code = '''cdef extern from "no_such_header_file": pass''' sage: broken = CythonFeature("broken", test_code=broken_code) sage: broken.is_present() FeatureTestResult('broken', False)
sage: broken_code = '''import no_such_python_module''' sage: broken = CythonFeature("broken", test_code=broken_code) sage: broken.is_present() FeatureTestResult('broken', False)
sage: broken_code = '''raise AssertionError("sorry!")''' sage: broken = CythonFeature("broken", test_code=broken_code) sage: broken.is_present() FeatureTestResult('broken', False)
-
sage.features.
Executable
¶ A feature describing an executable in the PATH.
Note
Overwrite
is_functional()
if you also want to check whether the executable shows proper behaviour.Calls to
is_present()
are cached. You might want to cache theExecutable
object to prevent unnecessary calls to the executable.EXAMPLES:
sage: from sage.features import Executable sage: Executable(name="sh", executable="sh").is_present() FeatureTestResult('sh', True)
-
sage.features.
Feature
¶ A feature of the runtime environment
Overwrite
_is_present()
to add feature checks.EXAMPLES:
sage: from sage.features.gap import GapPackage sage: GapPackage("grape", spkg="gap_packages") # indirect doctest Feature('GAP package grape')
For efficiency, features are unique:
sage: GapPackage("grape") is GapPackage("grape") True
-
exception
sage.features.
FeatureNotPresentError
(feature, reason=None, resolution=None)¶ Bases:
RuntimeError
A missing feature error.
EXAMPLES:
sage: from sage.features import Feature, FeatureTestResult sage: class Missing(Feature): ....: def _is_present(self): ....: return False sage: Missing(name="missing").require() Traceback (most recent call last): ... FeatureNotPresentError: missing is not available.
-
class
sage.features.
FeatureTestResult
(feature, is_present, reason=None, resolution=None)¶ Bases:
object
The result of a
Feature.is_present()
call.Behaves like a boolean with some extra data which may explain why a feature is not present and how this may be resolved.
EXAMPLES:
sage: from sage.features.gap import GapPackage sage: presence = GapPackage("NOT_A_PACKAGE").is_present(); presence # indirect doctest FeatureTestResult('GAP package NOT_A_PACKAGE', False) sage: bool(presence) False
Explanatory messages might be available as
reason
andresolution
:sage: presence.reason '`TestPackageAvailability("NOT_A_PACKAGE")` evaluated to `fail` in GAP.' sage: print(presence.resolution) None
If a feature is not present,
resolution
defaults tofeature.resolution()
if this is defined. If you do not want to use this default you need explicitly setresolution
to a string:sage: from sage.features import FeatureTestResult sage: package = GapPackage("NOT_A_PACKAGE", spkg="no_package") sage: FeatureTestResult(package, True).resolution "To install GAP package NOT_A_PACKAGE you can try to run 'sage -i no_package'." sage: FeatureTestResult(package, False).resolution "To install GAP package NOT_A_PACKAGE you can try to run 'sage -i no_package'." sage: FeatureTestResult(package, False, resolution="rtm").resolution 'rtm'
-
sage.features.
PythonModule
¶ A
Feature
which describes whether a python module can be imported.EXAMPLES:
Not all builds of python include the
ssl
module, so you could check whether it is available:sage: from sage.features import PythonModule sage: PythonModule("ssl").require() # not tested - output depends on the python build
-
sage.features.
StaticFile
¶ A
Feature
which describes the presence of a certain file such as a database.EXAMPLES:
sage: from sage.features import StaticFile sage: StaticFile(name="no_such_file", filename="KaT1aihu", search_path=("/",), spkg="some_spkg", url="http://rand.om").require() Traceback (most recent call last): ... FeatureNotPresentError: no_such_file is not available. 'KaT1aihu' not found in any of ['/'] To install no_such_file you can try to run 'sage -i some_spkg'. Further installation instructions might be available at http://rand.om.