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.

>>> 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