Listing Sage packages

This module can be used to see which Sage packages are installed and which packages are available for installation.

For more information about creating Sage packages, see the “Packaging Third-Party Code” section of the Sage Developer’s Guide.

Actually installing the packages should be done via the command line, using the following commands:

  • sage -i PACKAGE_NAME – install the given package
  • sage -f PACKAGE_NAME – re-install the given package, even if it was already installed

To list the packages available, either use in a terminal one of sage -standard, sage -optional or sage -experimental. Or the following command inside Sage:

sage: from sage.misc.package import list_packages
sage: pkgs = list_packages(local=True)  # optional - build
sage: sorted(pkgs.keys())  # optional - build, random
['4ti2',
 'alabaster',
 'arb',
 ...
 'zlib',
 'zn_poly',
 'zope_interface']

Functions

exception sage.misc.package.PackageNotFoundError

Bases: RuntimeError

This class defines the exception that should be raised when a function, method, or class cannot detect a Sage package that it depends on.

This exception should be raised with a single argument, namely the name of the package.

When a PackageNotFoundError is raised, this means one of the following:

  • The required optional package is not installed.
  • The required optional package is installed, but the relevant interface to that package is unable to detect the package.

EXAMPLES:

sage: from sage.misc.package import PackageNotFoundError
sage: raise PackageNotFoundError("my_package")
Traceback (most recent call last):
...
PackageNotFoundError: the package 'my_package' was not found. You can install it by running 'sage -i my_package' in a shell
sage.misc.package.experimental_packages()

Return two lists. The first contains the installed and the second contains the not-installed experimental packages that are available from the Sage repository.

OUTPUT:

  • installed experimental packages (as a list)
  • NOT installed experimental packages (as a list)

Run sage -i package_name from a shell to install a given package or sage -f package_name to re-install it.

EXAMPLES:

sage: from sage.misc.package import experimental_packages
sage: installed, not_installed = experimental_packages()  # optional - build
sage.misc.package.installed_packages(exclude_pip=True)

Return a dictionary of all installed packages, with version numbers.

INPUT:

  • exclude_pip – (optional, default: True) whether “pip” packages are excluded from the list

EXAMPLES:

sage: sorted(installed_packages().keys())  # optional - build
[...'alabaster', ...'sage_conf', ...]
sage: installed_packages()['alabaster']  # optional - build, random
'0.7.12'
sage: installed_packages()['sage_conf']  # optional - build
'none'
sage.misc.package.is_package_installed(package, exclude_pip=True)

Return whether (any version of) package is installed.

INPUT:

  • package – the name of the package
  • exclude_pip – (optional, default: True) whether to consider pip type packages

EXAMPLES:

sage: is_package_installed('gap')  # optional - build
True

Giving just the beginning of the package name is not good enough:

sage: is_package_installed('matplotli')  # optional - build
False

Otherwise, installing “pillow” would cause this function to think that “pil” is installed, for example.

Check that the option exclude_pip is turned on by default:

sage: from sage.misc.package import list_packages
sage: for pkg in list_packages(pkg_sources=('pip'), local=True):  # optional - build
....:     assert not is_package_installed(pkg), "pip package is installed: {}".format(pkg)

Note

Do not use this function to check whether you can use a feature from an external library. This only checks whether something was installed with sage -i but it may have been installed by other means (for example if this copy of Sage has been installed as part of a distribution.) Use the framework provided by sage.features to check whether a library is installed and functional.

sage.misc.package.list_packages(*pkg_types, **opts)

Return a dictionary of information about each package.

The keys are package names and values are dictionaries with the following keys:

  • 'type': either 'base, 'standard', 'optional', or 'experimental'
  • 'source': either 'normal', ``'pip', or 'script'
  • 'installed': boolean
  • 'installed_version': None or a string
  • 'remote_version': string

INPUT:

  • pkg_types – (optional) a sublist of 'base, 'standard', 'optional', or 'experimental'. If provided, list only the packages with the given type(s), otherwise list all packages.
  • pkg_sources – (optional) a sublist of 'normal', ``'pip', or 'script'. If provided, list only the packages with the given source(s), otherwise list all packages.
  • local – (optional, default: False) if set to True, then do not consult remote (PyPI) repositories for package versions (only applicable for 'pip' type)
  • exclude_pip – (optional, default: False) if set to True, then pip packages are not considered.
  • ignore_URLError – (default: False) if set to True, then connection errors will be ignored

EXAMPLES:

sage: from sage.misc.package import list_packages
sage: L = list_packages('standard')  # optional - build
sage: sorted(L.keys())  # optional - build, random
['alabaster',
 'arb',
 'babel',
 ...
 'zn_poly',
 'zope_interface']
sage: sage_conf_info = L['sage_conf']  # optional - build
sage: sage_conf_info['type'] # optional - build
'standard'
sage: sage_conf_info['installed'] # optional - build
True
sage: sage_conf_info['source'] # optional - build
'script'

sage: L = list_packages(pkg_sources=['pip'], local=True)  # optional - build internet
sage: bs4_info = L['beautifulsoup4'] # optional - build internet
sage: bs4_info['type'] # optional - build internet
'optional'
sage: bs4_info['source'] # optional - build internet
'pip'

Check the option exclude_pip:

sage: [p for p, d in list_packages('optional', exclude_pip=True).items()  # optional - build
....:  if d['source'] == 'pip']
[]
sage.misc.package.optional_packages()

Return two lists. The first contains the installed and the second contains the not-installed optional packages that are available from the Sage repository.

OUTPUT:

  • installed optional packages (as a list)
  • NOT installed optional packages (as a list)

Run sage -i package_name from a shell to install a given package or sage -f package_name to re-install it.

EXAMPLES:

sage: from sage.misc.package import optional_packages
sage: installed, not_installed = optional_packages()  # optional - build
sage: 'beautifulsoup4' in installed+not_installed  # optional - build
True

sage: 'beautifulsoup4' in installed   # optional - build beautifulsoup4
True
sage.misc.package.package_manifest(package)

Return the manifest for package.

INPUT:

  • package – package name

The manifest is written in the file SAGE_SPKG_INST/package-VERSION. It is a JSON file containing a dictionary with the package name, version, installation date, list of installed files, etc.

EXAMPLES:

sage: from sage.misc.package import package_manifest
sage: sagetex_manifest = package_manifest('sagetex')  # optional - build
sage: sagetex_manifest['package_name'] == 'sagetex'  # optional - build
True
sage: 'files' in sagetex_manifest  # optional - build
True

Test a nonexistent package:

sage: package_manifest('dummy-package')  # optional - build
Traceback (most recent call last):
...
KeyError: 'dummy-package'
sage.misc.package.package_versions(package_type, local=False)

Return version information for each Sage package.

INPUT:

  • package_type – (string) one of "standard", "optional" or "experimental"
  • local – (boolean, default: False) only query local data (no internet needed)

For packages of the given type, return a dictionary whose entries are of the form 'package': (installed, latest), where installed is the installed version (or None if not installed) and latest is the latest available version. If the package has a directory in SAGE_ROOT/build/pkgs/, then latest is determined by the file package-version.txt in that directory. If local is False, then Sage’s servers are queried for package information.

EXAMPLES:

sage: std = package_versions('standard', local=True)  # optional - build
sage: 'gap' in std  # optional - build
True
sage: std['zn_poly']  # optional - build, random
('0.9.p12', '0.9.p12')
sage.misc.package.pip_installed_packages()

Return a dictionary \(name->version\) of installed pip packages.

This command returns all pip-installed packages. Not only Sage packages.

EXAMPLES:

sage: from sage.misc.package import pip_installed_packages
sage: d = pip_installed_packages()  # optional - build
sage: 'scipy' in d  # optional - build
True
sage: d['scipy']  # optional - build
u'...'
sage: d['beautifulsoup4']   # optional - build beautifulsoup4
u'...'
sage.misc.package.pip_remote_version(pkg, pypi_url='https://pypi.python.org/pypi', ignore_URLError=False)

Return the version of this pip package available on PyPI.

INPUT:

  • pkg – the package
  • pypi_url – (string, default: standard PyPI url) an optional Python package repository to use
  • ignore_URLError – (default: False) if set to True then no error is raised if the connection fails and the function returns None

EXAMPLES:

The following test does fail if there is no TLS support (see e.g. trac ticket #19213):

sage: from sage.misc.package import pip_remote_version
sage: pip_remote_version('beautifulsoup4') # optional - internet # not tested
u'...'

These tests are reliable since the tested package does not exist:

sage: nap = 'hey_this_is_NOT_a_python_package'
sage: pypi = 'http://this.is.not.pypi.com/'
sage: pip_remote_version(nap, pypi_url=pypi, ignore_URLError=True) # optional - internet
doctest:...: UserWarning: failed to fetch the version of
pkg='hey_this_is_NOT_a_python_package' at http://this.is.not.pypi.com/
sage: pip_remote_version(nap, pypi_url=pypi, ignore_URLError=False) # optional - internet
Traceback (most recent call last):
...
HTTPError: HTTP Error 404: Not Found
sage.misc.package.pkgname_split(name)

Split a pkgname into a list of strings, ‘name, version’.

For some packages, the version string might be empty.

EXAMPLES:

sage: from sage.misc.package import pkgname_split
sage: pkgname_split('hello_world-1.2')
['hello_world', '1.2']
sage.misc.package.standard_packages()

Return two lists. The first contains the installed and the second contains the not-installed standard packages that are available from the Sage repository.

OUTPUT:

  • installed standard packages (as a list)
  • NOT installed standard packages (as a list)

Run sage -i package_name from a shell to install a given package or sage -f package_name to re-install it.

EXAMPLES:

sage: from sage.misc.package import standard_packages
sage: installed, not_installed = standard_packages()  # optional - build
sage: installed[0], installed[-1]  # optional - build
('alabaster', 'zope_interface')