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 - sage_spkg
sage: sorted(pkgs.keys())  # optional - sage_spkg, random
['4ti2',
 'alabaster',
 'arb',
 ...
 'zlib']

Functions#

class sage.misc.package.PackageInfo(name: str, type: str | None = None, source: str | None = None, installed_version: str | None = None, remote_version: str | None = None)#

Bases: NamedTuple

Represents information about a package.

installed_version: str | None#

Alias for field number 3

is_installed()#

Whether the package is installed in the system.

name: str#

Alias for field number 0

remote_version: str | None#

Alias for field number 4

source: str | None#

Alias for field number 2

type: str | None#

Alias for field number 1

exception sage.misc.package.PackageNotFoundError(*args)#

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.

Raising a PackageNotFoundError is deprecated. Use sage.features.FeatureNotPresentError instead.

User code can continue to catch PackageNotFoundError exceptions for compatibility with older versions of the Sage library. This does not cause deprecation warnings.

EXAMPLES:

sage: from sage.misc.package import PackageNotFoundError
sage: try:
....:     pass
....: except PackageNotFoundError:
....:     pass
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 - sage_spkg
doctest:...: DeprecationWarning: ...
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:

Below we test for a standard package without spkg-configure.m4 script that should be installed in SAGE_LOCAL. When Sage is installed by the Sage distribution (indicated by feature sage_spkg), we should have the installation record for this package. (We do not test for installation records of Python packages. Our SAGE_VENV is not necessarily the main Sage venv; it could be a user-created venv or a venv created by tox.):

sage: # optional - sage_spkg
sage: from sage.misc.package import installed_packages
sage: sorted(installed_packages().keys())
[...'conway_polynomials', ...]
sage: installed_packages()['conway_polynomials']  # random
'0.5'
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: from sage.misc.package import is_package_installed
sage: is_package_installed('conway_polynomials')  # optional - sage_spkg
True

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

sage: is_package_installed('conway_poly')         # optional - sage_spkg
False

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

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.is_package_installed_and_updated(package)#

Return whether the given package is installed and up-to-date.

INPUT:

  • package – the name of the package.

EXAMPLES:

sage: from sage.misc.package import is_package_installed_and_updated
sage: is_package_installed_and_updated("alabaster")    # optional - build, random
False
sage.misc.package.list_packages(pkg_sources, local, ignore_URLError, exclude_pip, *pkg_types)#

Return a dictionary of information about each package.

The keys are package names and values are named tuples 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. This is the same as removing 'pip' from pkg_sources.

  • ignore_URLError – (default: False) if set to True, then connection errors will be ignored

EXAMPLES:

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

sage: # optional - sage_spkg internet
sage: L = list_packages(pkg_sources=['pip'], local=True)
sage: bp_info = L['biopython']
sage: bp_info.type
'optional'
sage: bp_info.source
'pip'

Check the option exclude_pip:

sage: [p for p, d in list_packages('optional', exclude_pip=True).items()  # optional - sage_spkg
....:  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: # optional - sage_spkg
sage: from sage.misc.package import optional_packages
sage: installed, not_installed = optional_packages()
doctest:...: DeprecationWarning: ...
sage: 'biopython' in installed + not_installed
True
sage: 'biopython' in installed          # optional - biopython
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: # optional - sage_spkg
sage: from sage.misc.package import package_manifest
sage: manifest = package_manifest('conway_polynomials')
sage: manifest['package_name'] == 'conway_polynomials'
True
sage: 'files' in manifest
True

Test a nonexistent package:

sage: package_manifest('dummy-package')                  # optional - sage_spkg
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: # optional - sage_spkg
sage: from sage.misc.package import package_versions
sage: std = package_versions('standard', local=True)
sage: 'gap' in std
True
sage: std['zlib']  # random
('1.2.11.p0', '1.2.11.p0')
sage.misc.package.pip_installed_packages(normalization=None)#

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

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

INPUT:

  • normalization – (optional, default: None) according to which rule to normalize the package name, either None (as is) or 'spkg' (format as in the Sage distribution in build/pkgs/), i.e., lowercased and dots and dashes replaced by underscores.

EXAMPLES:

sage: # optional - sage_spkg
sage: from sage.misc.package import pip_installed_packages
sage: d = pip_installed_packages()
sage: 'scipy' in d or 'SciPy' in d
True
sage: d['beautifulsoup4']                               # optional - beautifulsoup4
'...'
sage: d['prompt-toolkit']
'...'
sage: d = pip_installed_packages(normalization='spkg')
sage: d['prompt_toolkit']
'...'
sage: d['scipy']
'...'
sage.misc.package.pip_remote_version(pkg, pypi_url='https://pypi.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. github issue #19213):

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

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/.../json
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.spkg_type(name)#

Return the type of the Sage package with the given name.

INPUT:

  • name – string giving the subdirectory name of the package under SAGE_PKGS

EXAMPLES:

sage: from sage.misc.package import spkg_type
sage: spkg_type('pip')                                  # optional - sage_spkg
'standard'

OUTPUT:

The type as a string in ('base', 'standard', 'optional', 'experimental'). If no SPKG exists with the given name (or the directory SAGE_PKGS is not avaialble), None is returned.

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 - sage_spkg
doctest:...: DeprecationWarning: ...
sage: 'numpy' in installed                            # optional - sage_spkg
True