check_for_updates

Check for a newer release

Ask PyPI whether a newer release of PyVBMC is available:

import pyvbmc

check = pyvbmc.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:

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

The command follows the installer recorded with your installation: python -m pip install --upgrade pyvbmc for pip, conda install --channel=conda-forge "pyvbmc>=1.6.0" for conda, naming the latest release (the conda-forge package can follow PyPI by a few days), and both when the installer is another or unknown. The other messages are listed below, with the returned named tuple, which gives a script the same answer. A network failure raises no error.

Network access

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

The old-release reminder

When a new run starts in an interactive session and the installed release is more than a year old, VBMC suggests calling this function, at most three times for each installed version. The reminder makes no network request: it compares the release date shipped with PyVBMC with the date of the run.

Pass options={"show_tips": False} to VBMC to disable the reminder together with startup tips, or use options={"display": "off"} for a quiet run. To disable only the reminder for an environment, set PYVBMC_NO_UPDATE_REMINDER. The common NO_UPDATE_NOTIFIER and CI environment variables also suppress it. An empty value, 0 or false counts as unset.

The reminder records that it was shown in PyVBMC’s per-user cache. It honors PYVBMC_CACHE_DIR when that variable overrides the cache location. This small state write is separate from check_for_updates(), which writes nothing. See the FAQ for the short workflow.

pyvbmc.check_for_updates(*, timeout: float = 5.0) → UpdateCheck

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

This is the only network access in PyVBMC, and it happens only when this function is called. The request tells PyPI the installed PyVBMC version and nothing else about the installation or the user. Proxy environment variables are honored, and nothing is written to disk.

Prints one message: that a newer release is available, with the command that installs it; that the installed version is the latest release; that it is newer than the latest release on PyPI; that it is a development version, with the latest release; that it is unknown, with the latest release; or that PyPI could not be reached, with the reason. The update command follows the installer recorded with the installed package: pip’s, conda’s (the conda-forge package can follow PyPI by a few days), or both when the installer is another or unknown.

Pre-releases, development releases and yanked releases on PyPI are ignored. An installed development version is reported beside the latest release without being compared with it.

Parameters:

timeoutfloat, optional

Timeout in seconds for each network operation: the connection, and each read of the reply. The lookup of PyPI’s address is not bounded by it. At most 3600; the default is 5.0.

Returns:

UpdateCheck

A named tuple of installed, the installed version (None when the package metadata cannot be found); latest, the latest release on PyPI (None when PyPI could not be reached, its reply could not be read or it named no release); and update_available, whether latest is newer than installed (None when either is unknown or the installed version is a development version).

Raises:

ValueError

If timeout is not a positive number of seconds of at most 3600, or is a bool. A network, HTTP or parse failure raises nothing: the printed message gives its reason, and the returned tuple holds latest=None.

See also the startup tips of VBMC.