# NiBabel

### Access a cacophony of neuro-imaging file formats

# `optpkg`

Routines to support optional packages

`optional_package`(name[, trip_msg, min_version]) | Return package-like thing and module setup for package name

## optional_package

nibabel.optpkg.optional_package(name: str, trip_msg: str | None = None, min_version: str | Version | ty.Callable[[ModuleType], bool] | None = None) → tuple[ModuleType | TripWire, bool, ty.Callable[[], None]]

  Return package-like thing and module setup for package name

  Parameters:
    name str

      package name

    trip_msg None or str

      message to give when someone tries to use the return package, but we could not import it at an acceptable version, and have returned a TripWire object instead. Default message if None.

    min_version None or str or Version or callable

      If None, do not specify a minimum version. If str, convert to a `packaging.version.Version`. If str or `Version` compare to version of package name with `min_version <= pkg.__version__`. If callable, accepts imported `pkg` as argument, and returns value of callable is True for acceptable package versions, False otherwise.

  Returns:
    pkg_like module or `TripWire` instance

      If we can import the package, return it. Otherwise return an object raising an error when accessed

    have_pkg bool

      True if import for package was successful, false otherwise

    module_setup function

      callable usually set as `setup_module` in calling namespace, to allow skipping tests.

  Examples

  Typical use would be something like this at the top of a module using an optional package:

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

  Of course in this case the package doesn’t exist, and so, in the module:

      >>> have_pkg
      False

  and

      >>> pkg.some_function()
      Traceback (most recent call last):
          ...
      TripWireError: We need package not_a_package for these functions,
          but ``import not_a_package`` raised an ImportError

  If the module does exist - we get the module

      >>> pkg, _, _ = optional_package('os')
      >>> hasattr(pkg, 'path')
      True

  Or a submodule if that’s what we asked for

      >>> subpkg, _, _ = optional_package('os.path')
      >>> hasattr(subpkg, 'dirname')
      True