nvchecker Documentation

If you are upgrading from the 1.x branch to the 2.x branch, be aware of the following breaking changes:

• Python Version: 2.x requires Python 3.7+.
• Command Syntax: You must use the -c switch to specify your software version configuration file.
• Config Format: Configuration files have changed from .ini to .toml. Use the nvchecker-ini2toml script to convert them (note: comments and formatting will be lost).
• Option Renaming: max_concurrent is now max_concurrency. All option names now use underscores (_) instead of hyphens (-).
• Source Requirement: All software configuration tables must now include a source option to specify the plugin.
• Version Records: Version record files now use JSON format.
• Removed Features: The vcs source is removed (use git instead). include_tags_pattern and ignored_tags are also removed.

nvchecker source plugins are implemented as Python modules within namespace packages named nvchecker_source. To make your plugins discoverable, they must be located in a directory named nvchecker_source that is present in your sys.path.

Common ways to include your plugins:

• Place them in your local site-packages: ~/.local/lib/pythonX.Y/site-packages/nvchecker_source/.
• Use the PYTHONPATH environment variable to point to a directory containing your nvchecker_source folder.

In your configuration file, reference the plugin by its module name using source = "xxx".

To check for software updates, run nvchecker using the -c flag to specify your TOML configuration file.

Example configuration file (config_file.toml):

[nvchecker]
source = "github"
git = "lilydjwg/nvchecker"

[python-toml]
source = "pypi"
pypi = "toml"

nvchecker -c config_file.toml

Ensure your environment meets the following requirements:

• Python: 3.9 or higher.
• Core Libraries: structlog, platformdirs, and tomli (if using Python < 3.11).
• HTTP/Network Clients (one of the following combinations is required, in order of preference):
  1. tornado + pycurl
  2. aiohttp
  3. httpx (with http2 support; experimental and only latest version supported)
  4. tornado
• Configuration Dependencies: Any libraries required by the specific commands used in your software version configuration files.

You can install nvchecker using pip3. To use the latest development code, you can clone the repository and run the setup script.

Dependencies

• Python 3.9+
• Python libraries: structlog, platformdirs, tomli (for Python < 3.11)
• One of the following networking combinations (ordered by preference):
  1. tornado + pycurl
  2. aiohttp
  3. httpx with http2 support (experimental)
  4. tornado

# Install via pip
pip3 install nvchecker

# Or install from source
python3 setup.py install

Use the bitbucket source to track BitBucket repositories. You can use use_max_tag to get the largest tag name, or use_sorted_tags to perform custom filtering and sorting using the BitBucket API query and sort parameters.

source = "bitbucket"
bitbucket = "lilydjwg/dotvim"
use_sorted_tags = true
query = "version > 1.0"
sort = "-target.date"
max_page = 5

Use the repology source to track updates via Repology. The repo field is required.

source = "repology"
repology = "my-project"
repo = "debian"
subrepo = "optional-subrepo"

Use the pypi source to track Python packages on PyPI. Note that an additional dependency packaging is required. You can install it using pip install 'nvchecker[pypi]'.

source = "pypi"
pypi = "PySide"
use_pre_release = true

If a source requires a token (like GitHub), you can specify a keyfile. This file must contain a [keys] table mapping key names to values. For GitHub, you can use the github key.

Example keyfile.toml:

[keys]
github = "ghp_your_token_here"

[keys]
github = "ghp_stripped"

Use the npm source to track packages on the NPM registry. You can specify a custom registry URL.

source = "npm"
npm = "coffee-script"

[__config__.source.npm]
registry = "https://registry.npm.taobao.org"

The __config__ table provides configuration options that apply to the execution environment. Relative paths are relative to the source files, and ~ or environment variables are expanded.

Supported options:

• oldver: Path to a version record file containing old version info.
• newver: Path to a version record file to store new version info.
• proxy: HTTP proxy in proto://host:port format (e.g., http://localhost:8087).
• max_concurrency: Max concurrent jobs (Default: 20).
• http_timeout: HTTP request timeout in seconds (Default: 20).
• keyfile: Path to a TOML file containing a [keys] table for authentication tokens.

[__config__]
oldver = "./old_versions.toml"
newver = "./new_versions.toml"
max_concurrency = 10

nvchecker uses toml files for configuration. Each software entry is defined by a table where the key name is the software name. Within these tables, you specify fields that tell nvchecker how to determine the current version.

To manage global settings or specific file paths, use the special __config__ table.

[software_name]
source = "github"
github = "author/repo"