stouputils.version_pkg module#

This module provides utility functions for printing package version information in a structured format, including the main package and its dependencies.

Functions:

show_version(): Print the version of the main package and its dependencies.

class VersionPrinter( main_package: str = 'stouputils', primary_color: str = '\x1b[96m', secondary_color: str = '\x1b[92m', max_depth: int = 2, fully_displayed: set[str] = <factory>, )[source]#

Bases: object

Prints a package and its dependencies, either as a flat list or as a tree.

Examples

>>> VersionPrinter.dependency_name('msgspec[toml,yaml]>=0.20.0')
'msgspec'
>>> VersionPrinter.dependency_name('numpy; python_version >= "3.14"')
'numpy'

main_package: str = 'stouputils'[source]#: Package the report starts from.

primary_color: str = '\x1b[96m'[source]#: Color of the package names and the separators.

secondary_color: str = '\x1b[92m'[source]#: Color of the version numbers.

max_depth: int = 2[source]#: Depth of the dependency tree, 2 or less printing a flat list instead.

fully_displayed: set[str][source]#: Packages whose dependencies were already printed once, marked as such on the next occurrence.

static version_of(package_name: str) → str[source]#

Installed version of a package, empty when it is not installed.

Parameters:: package_name (str) – Name of the package
Returns:: Version of the package, ex: “1.0.0”
Return type:: str

static dependency_name(requirement: str) → str[source]#

Name of the package a requirement refers to, without its version, extras or markers.

Parameters:: requirement (str) – Requirement as written in the metadata, ex: “msgspec[toml,yaml]>=0.20.0”
Returns:: Name of the required package, ex: “msgspec”
Return type:: str

classmethod dependencies_of( package_name: str, with_extras: bool = True, ) → list[str][source]#

Sorted names of the packages a package depends on, without duplicates.

Parameters:

package_name (str) – Name of the package
with_extras (bool) – Whether the dependencies of the optional extras are included

Returns:

Names of the dependencies, ex: [“numpy”, “tqdm”]

Return type:

list[str]

separators(length: int) → tuple[str, str][source]#

Build the two separator lines framing the main package.

Parameters:: length (int) – Width of the separators, in characters
Returns:: Separator holding the Python version, and plain separator
Return type:: tuple[str, str]

property minimum_width: int[source]#: Width leaving at least five dashes on each side of the Python version.

print_package( package_name: str, version: str, prefix: str = '', suffix: str = '', ) → None[source]#

Print one package line.

Parameters:

package_name (str) – Name of the package
version (str) – Version of the package
prefix (str) – Text written before the package name, ex: the tree branches
suffix (str) – Text written after the version, ex: the already shown marker

print_node( package_name: str, version: str, prefix: str, is_last: bool, depth: int, ) → bool[source]#

Print the line of one node of the tree.

Parameters:

package_name (str) – Name of the package
version (str) – Version of the package
prefix (str) – Branches already drawn on the left of this package
is_last (bool) – Whether the package is the last child of its parent
depth (int) – Current depth, the main package being at 0

Returns:

Whether the dependencies of this package are worth walking

Return type:

bool

print_tree( package_name: str, prefix: str = '', is_last: bool = True, visited: set[str] | None = None, depth: int = 0, ) → None[source]#

Print a package and its dependencies as a tree, walking each branch once.

Parameters:

package_name (str) – Name of the package to print
prefix (str) – Branches already drawn on the left of this package
is_last (bool) – Whether the package is the last child of its parent
visited (set[str]) – Packages already printed in this branch, to stop cycles
depth (int) – Current depth, the main package being at 0

print_flat() → None[source]#: Print the main package and its direct dependencies as an aligned list.

show() → None[source]#: Print the whole report, as a tree or as a flat list depending on the requested depth.

show_version( main_package: str = 'stouputils', primary_color: str = '\x1b[96m', secondary_color: str = '\x1b[92m', max_depth: int = 2, ) → None[source]#

Print the version of the main package and its dependencies.

Used by the “stouputils –version” command.

Parameters:

main_package (str) – Name of the main package to show version for
primary_color (str) – Color to use for the primary package name (defaults to cyan)
secondary_color (str) – Color to use for the secondary package names (defaults to green)
max_depth (int) – Maximum depth for dependency tree (<= 2 for flat, >=3 for tree)

show_version_cli() → None[source]#: Handle the “stouputils –version” CLI command