alexmojaki / outdated

Check if a version of a PyPI package is outdated

outdated

This is a mini-library which, given a package name and a version, checks if it's the latest version available on PyPI.

To install:

pip install outdated

Quickstart:

from outdated import warn_if_outdated

warn_if_outdated('my-package-name', '1.2.3')

This will:

• Show a warning if the given version is not the latest. The warning includes the package name, the given version, and the latest version.
• Perform the check in a background thread (so it doesn't delay anything)
• Make at most one HTTP call (unless there is an HTTP error, in which case it will try 3 times) to the PyPI server for that specific package
• Cache the result of the HTTP call on disk for 24 hours
• Show a warning if any exception occurs during the check

This will not check what version is currently installed, it will only use the given version. Library authors must make sure that the version in their setup.py matches the version here.

The package name argument must be exactly the name used on PyPI, so that e.g. https://pypi.python.org/pypi/my-package-name is a valid URL.

Optional arguments:

• background (default True): run the check in a separate thread. Set to False to run immediately.
• raise_exceptions (default: False): if True, allow exceptions to bubble to the top. Otherwise, show a warning including the exception message. If background is True and this is True then this will result in a full traceback showing but the process continuing.

Lower level API

from outdated import check_outdated

is_outdated, latest_version = check_outdated('my-package-name', '1.2.3')

is_outdated is a boolean which is True if the given version is earlier than the latest version, which is the string latest_version.

Optional arguments:

• repository_url (default https://pypi.python.org/pypi/%s/json): a % style format string to use a different repository PyPI repository URL, e.g. test.pypi.org or a private repository. The string is formatted with the package name.

This still makes the HTTP call with retries and caches the result on disk. It doesn't use a separate thread or emit any warnings (unless there is an exception specifically while using the cache, in which case the check will be done without the cache).

Additional configuration

To disable all warnings from this library, set the environment variable OUTDATED_IGNORE to any non-empty value.

To always raise exceptions instead of converting them to warnings (both in general in warn_if_outdated and more specifically when there's a caching problem) set the environment variable OUTDATED_RAISE_EXCEPTION=1.

The warnings are also categorised so that you can easily control them with standard warning filters. The classes are here and can be imported directly from the outdated module.

Performance

This library works by fetching a URL such as this - the time it takes to visit that link is essentially the speed of the library. This is much faster than the command pip list --outdated or any equivalent code.

outdated's Issues

Docu: PyPi restriction

Please be clear in your documentation (e.g. README) that your package does check the "latest version" from PyPi only. PyPi is not the whole universe and also extrem uncommon in the current days because of security issues.

The point is that there are much more ways to distribute packages then PyPi. You don't have to support all these ways but you should clear about that you serve PyPi only.

Stop querying pypi when OUTDATED_IGNORE is on

My understanding of how outdated works is that if the environment variable OUTDATED_IGNORE is set (to any non empty value), then it will stop warning when a package is outdated.

But this will still query pypi in the background. Again, my understanding is that this will happen in a different thread and should not have a detrimental impact on performance.

Nevertheless, some people don't want to have their production environment attempt to query pypi, for various reason (security being the main one).

Would it be possible to change the behaviour of OUTDATED_IGNORE so that it makes outdated do absolutely nothing. or alternatively add another environment variable to disable checks altogether.

Thanks.

Undeclared runtime dependency: `setuptools`

setuptools is an undeclared runtime dependency currently, it is used here:

outdated/outdated/__init__.py

Line 36 in 591f80b

from pkg_resources import parse_version

pyproject.toml declares it as a build dependency, but build dependencies do not need to be kept around during installation and afterwards in isolated build environments, which python stuff is moving towards. For many people this problem might not manifest if they have setuptools installed in their environment in the first place, but for people who don't it causes issues.

Include license file in PyPI package

It would be great if a copy of the LICENSE file could be included in the PyPI package. Not only is this a good idea in general, it would assist people in packaging this software for Linux distributions.

great package! can we have a flag that disables the cache check. I want to check for updates all the time

Include source on PyPI

Betwwen versions 0.2.0 and 0.2.1 this package switched from providing a source tarball to a wheel. Would it be possible to still supply the source tarball? The Flatpak-Pip-Generator tries to grab the source tarball when compiling dependency data which ends up being a bit of a blocker.