check_for_updates

Check for a newer release

Ask PyPI whether a newer release of PyBADS is available:

import pybads

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

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

The command follows the installer recorded with your installation: python -m pip install --upgrade pybads for pip, conda update --channel=conda-forge pybads for conda (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

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

The old-release reminder

When a run starts in an interactive session (a terminal or a Jupyter notebook) and the installed release is more than a year old, BADS suggests calling this function, in place of the tip before the first iteration line:

Note: PyBADS 1.5.0 was released more than a year ago. Run pybads.check_for_updates() to see whether a newer version is available.
https://pypi.org/project/pybads/

The reminder makes no network request: it compares the release date shipped with PyBADS with the date of the run. It appears at most once per Python session and records the dates of its showings in update_reminder.json in PyBADS’s cache directory: %LOCALAPPDATA%\pybads on Windows, ~/Library/Caches/pybads on macOS, ~/.cache/pybads on Linux (or under $XDG_CACHE_HOME), or the directory that PYBADS_CACHE_DIR names.

The saved dates limit reminders to three showings for each installed version, at least 90 days apart. If the state file cannot be read or updated, these limits may not hold across sessions; any dates that can be read still count.

To turn it off, pass options={"show_tips": False} to BADS, which also turns off the tips, or set the environment variable PYBADS_NO_UPDATE_REMINDER=1.

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

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

Sends one HTTPS GET request to https://pypi.org/pypi/pybads/json, with the User-Agent header pybads/<installed version> (check_for_updates); the request carries nothing else about the installation or the user. This is the only network access in PyBADS, and it happens only when this function is called. The proxy environment variables (HTTPS_PROXY and its kin) are honored. 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.

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, at most 3600. By default 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 or its reply could not be read); 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. A network, HTTP or parse failure raises nothing: the printed message gives its reason, and the returned tuple holds latest=None.