check_for_updates

check_for_updates#

Check for a newer release#

Ask PyPI whether a newer release of PyIBS is available:

import pyibs

check = pyibs.check_for_updates()

The function prints one line. When PyPI has a newer release, the line names it and gives the command that installs it, for example:

PyIBS 1.6.0 is available; you have 1.5.0. Update with: python -m pip install --upgrade pyibs

The command uses the installer recorded in the package metadata: python -m pip install --upgrade pyibs for pip, conda update --channel=conda-forge pyibs for conda (the conda-forge package can follow PyPI by a few days), and both when the installer is another or unknown. The reference below describes all outcomes and the returned named tuple, which scripts can inspect. Network failures are reported without raising an exception.

Network access#

PyIBS contacts PyPI only when you call this function, and makes no other network request. The request names the installed version of PyIBS and nothing else about your installation, and the call writes nothing to disk.

pyibs.check_for_updates(*, timeout: float = 5.0) → UpdateCheck[source]#

Ask PyPI for the latest release of PyIBS and say how to update.

Prints one message comparing the installed version with PyPI’s latest release: an update is available, the versions match, or the installed version is newer. For a development or unknown installed version, it reports the latest release without a comparison. If the request fails, the message explains why.

When an update is available, the message includes an installation command for pip or conda, based on the installer recorded in the package metadata. It gives both commands for other or unknown installers. The conda-forge package may follow PyPI by a few days.

The latest release is the highest final release (X.Y.Z) on PyPI; pre-releases, development releases and yanked releases are ignored. An installed version of another form, such as a development install, is reported beside the latest release without being compared with it.

Parameters:
timeoutfloat, optional

Timeout in seconds for connecting to PyPI and for each read of its reply. Must be > 0 and <= 3600. Default 5.0.

Returns:
UpdateCheck

A named tuple with three fields:

  • installed: installed version, or None if its metadata is unavailable.

  • latest: latest PyPI release, or None if the request or parsing failed.

  • update_available: whether latest is newer than installed. None if either is unknown or the installed version is a development version.

Raises:
ValueError

If timeout is not a positive number of seconds at most 3600.

Notes

Network, HTTP and parsing failures are reported in the printed message and return latest=None; they do not raise an exception.

This function sends an HTTPS GET request to https://pypi.org/pypi/pyibs/json with the User-Agent header pyibs/<installed version> (check_for_updates). It sends no other information about the installation or user. Proxy environment variables such as HTTPS_PROXY are honored. This is PyIBS’s only network access, occurs only when the function is called, and writes nothing to disk.