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.

import stouputils as stp

# Versions of stouputils and of every package it depends on
stp.show_version()
Terminal output of the example, every dependency with its version
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.

>>> 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, collapsed into one line 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 – Name of the package

Returns:

“1.0.0”

Return type:

Version of the package, ex

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

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

Parameters:

requirement – Requirement as written in the metadata, ex: “msgspec[toml,yaml]>=0.20.0”

Returns:

“msgspec”

Return type:

Name of the required package, ex

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 – Name of the package

  • with_extras – Whether the dependencies of the optional extras are included

Returns:

[“numpy”, “tqdm”]

Return type:

Names of the dependencies, ex

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

Build the two separator lines framing the main package.

Parameters:

length – Width of the separators, in characters

Returns:

Separator holding the Python version, and plain separator

property minimum_width: int[source]#

Width leaving at least five dashes on each side of the Python version.

package_line(
package_name: str,
version: str,
suffix: str = '',
) → str[source]#

Build the line describing one package.

Parameters:

  • package_name – Name of the package

  • version – Version of the package

  • suffix – Text written after the version, ex: the already shown marker

Returns:

“stouputils v1.0.0”

Return type:

Colored line, ex

already_shown_line(
package_names: list[str],
) → str[source]#

Build the line collapsing every dependency whose own tree was printed earlier.

Parameters:

package_names – Names of the packages already printed

Returns:

“Already shown ^: markdown, pygments”

Return type:

Colored line, ex

static indent_block(
lines: list[str],
is_last: bool,
) → list[str][source]#

Hang a subtree under its parent, the first line carrying the connector.

Parameters:

  • lines – Lines of the subtree, indented relative to its own root

  • is_last – Whether the subtree is the last child of its parent

Returns:

Lines indented relative to the parent

>>> VersionPrinter.indent_block(["numpy", "└── tqdm"], is_last=False)
['├── numpy', '│   └── tqdm']
>>> VersionPrinter.indent_block(["numpy", "└── tqdm"], is_last=True)
['└── numpy', '    └── tqdm']
render_tree(
package_name: str,
visited: frozenset[str] = frozenset({}),
depth: int = 0,
) → list[str][source]#

Render a package and its dependencies, indented relative to that package.

Dependencies whose own tree was printed earlier are collapsed into a single line at the end, since repeating their name, version and marker on one line each drowns the ones worth reading.

Parameters:

  • package_name – Name of the package to render

  • visited – Packages already rendered in this branch, to stop cycles

  • depth – Current depth, the main package being at 0

Returns:

Lines of the subtree, the package itself being the first one

print_tree(package_name: str) → None[source]#

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

Parameters:

package_name – Name of the package to print

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 – Name of the main package to show version for

  • primary_color – Color to use for the primary package name (defaults to cyan)

  • secondary_color – Color to use for the secondary package names (defaults to green)

  • max_depth – Maximum depth for dependency tree (<= 2 for flat, >=3 for tree)

show_version_cli() → None[source]#

Handle the “stouputils –version” CLI command