1
""" Routines to support optional packages """
2 33
from distutils.version import LooseVersion
3 33
from .tripwire import TripWire
4

5

6 33
def _check_pkg_version(pkg, min_version):
7
    # Default version checking function
8 33
    if isinstance(min_version, str):
9 33
        min_version = LooseVersion(min_version)
10 33
    try:
11 33
        return min_version <= pkg.__version__
12 33
    except AttributeError:
13 33
        return False
14

15

16 33
def optional_package(name, trip_msg=None, min_version=None):
17
    """ Return package-like thing and module setup for package `name`
18

19
    Parameters
20
    ----------
21
    name : str
22
        package name
23
    trip_msg : None or str
24
        message to give when someone tries to use the return package, but we
25
        could not import it at an acceptable version, and have returned a
26
        TripWire object instead. Default message if None.
27
    min_version : None or str or LooseVersion or callable
28
        If None, do not specify a minimum version.  If str, convert to a
29
        `distutils.version.LooseVersion`.  If str or LooseVersion` compare to
30
        version of package `name` with ``min_version <= pkg.__version__``.   If
31
        callable, accepts imported ``pkg`` as argument, and returns value of
32
        callable is True for acceptable package versions, False otherwise.
33

34
    Returns
35
    -------
36
    pkg_like : module or ``TripWire`` instance
37
        If we can import the package, return it.  Otherwise return an object
38
        raising an error when accessed
39
    have_pkg : bool
40
        True if import for package was successful, false otherwise
41
    module_setup : function
42
        callable usually set as ``setup_module`` in calling namespace, to allow
43
        skipping tests.
44

45
    Examples
46
    --------
47
    Typical use would be something like this at the top of a module using an
48
    optional package:
49

50
    >>> from nibabel.optpkg import optional_package
51
    >>> pkg, have_pkg, setup_module = optional_package('not_a_package')
52

53
    Of course in this case the package doesn't exist, and so, in the module:
54

55
    >>> have_pkg
56
    False
57

58
    and
59

60
    >>> pkg.some_function() #doctest: +IGNORE_EXCEPTION_DETAIL
61
    Traceback (most recent call last):
62
        ...
63
    TripWireError: We need package not_a_package for these functions,
64
        but ``import not_a_package`` raised an ImportError
65

66
    If the module does exist - we get the module
67

68
    >>> pkg, _, _ = optional_package('os')
69
    >>> hasattr(pkg, 'path')
70
    True
71

72
    Or a submodule if that's what we asked for
73

74
    >>> subpkg, _, _ = optional_package('os.path')
75
    >>> hasattr(subpkg, 'dirname')
76
    True
77
    """
78 33
    if callable(min_version):
79 33
        check_version = min_version
80 33
    elif min_version is None:
81 33
        check_version = lambda pkg: True
82
    else:
83 33
        check_version = lambda pkg: _check_pkg_version(pkg, min_version)
84
    # fromlist=[''] results in submodule being returned, rather than the top
85
    # level module.  See help(__import__)
86 33
    fromlist = [''] if '.' in name else []
87 33
    exc = None
88 33
    try:
89 33
        pkg = __import__(name, fromlist=fromlist)
90 33
    except Exception as exc_:
91
        # Could fail due to some ImportError or for some other reason
92
        # e.g. h5py might have been checking file system to support UTF-8
93
        # etc.  We should not blow if they blow
94 33
        exc = exc_  # So it is accessible outside of the code block
95
    else:  # import worked
96
        # top level module
97 33
        if check_version(pkg):
98 33
            return pkg, True, lambda: None
99
        # Failed version check
100 33
        if trip_msg is None:
101 33
            if callable(min_version):
102 33
                trip_msg = f'Package {min_version} fails version check'
103
            else:
104 33
                trip_msg = f'These functions need {name} version >= {min_version}'
105 33
    if trip_msg is None:
106 33
        trip_msg = (f'We need package {name} for these functions, '
107
                    f'but ``import {name}`` raised {exc}')
108 33
    pkg = TripWire(trip_msg)
109

110 33
    def setup_module():
111 33
        import unittest
112 33
        raise unittest.SkipTest(f'No {name} for these tests')
113

114 33
    return pkg, False, setup_module

Read our documentation on viewing source code .

Loading