vspect

vspect (version inspect) is a simple and lightweight command-line utility for working with Python package version strings. It was created to make it easier to read and format version strings when doing automated package releases in CI.

There are two main parts to using vspect:

1. Get a version string by using one of three approaches:
   • Use the package command with a package name, and vspect will look up that package's version in the current virtual environment.
   • Use the read command to read a statically-defined version from a pyproject.toml file. Give it either the file path or its parent directory path.
   • Use the parse command to with a version string you provide directly.
2. Render it according to a specified format by optionally providing a Python formatting string. If not specified, the full version will be printed.

Here are some examples:

# Look up a package's version
vspect package pip
#> 25.0.1

# Provide a format string to customize the format
vspect package pip "{major_minor_version}"
#> 25.0

# Read from pyproject.toml. Can either be direct path or its parent directory
vspect read . "{major_minor_version}"
#> 0.1

# Parse a directly given version string
vspect parse 1.2.3.post4.dev5 "v{major}.{minor}.{patch}{post}"
#> v1.2.3post4

See the "Format string" section for all available replacement fields.

While it's primarily intended for use with Python packages, you can easily use the parse command to manipulate generic dotted version strings in any context.

vspect is lightweight with minimal dependencies. It only depends on the packaging package published by the Python Packaging Authority (PyPA) and a backport of the standard library's tomllib for older versions of Python.

Installation

vspect is available from PyPI:

pip install vspect

Basic usage

vspect package PACKAGE_NAME [FORMAT_STRING]
# or
vspect read FILE_OR_DIR_PATH [FORMAT_STRING]
# or
vspect parse VERSION [FORMAT_STRING]

The package subcommand requires that vspect is installed in the same virtual environment as the package you are trying to look up.

Format string

Both the package and parse subcommands take an optional FORMAT_STRING. The format string is just a regular Python format string that gets passed to str.format(). See "Format String Syntax" in Python's documentation for additional help. The following replacement field names are passed in: