Version

ghflowgen.version

Contain functions to manage package versions.

ghflowgen.version.compare_version

compare_version(
    package: str, op: Callable, version: str
) -> bool

Compare a package version to a given version.

Parameters:

Name	Type	Description	Default
package	str	Specifies the package to check.	required
op	Callable	Specifies the comparison operator.	required
version	str	Specifies the version to compare with.	required

Returns:

Type	Description
bool	The comparison status.

Example usage:

>>> import operator
>>> from ghflowgen.version import compare_version
>>> compare_version("pytest", op=operator.ge, version="7.3.0")
True

ghflowgen.version.filter_range_versions

filter_range_versions(
    versions: Sequence[str],
    lower: str | None = None,
    upper: str | None = None,
) -> list[str]

Filter a list of version strings to include only versions within optional bounds.

Parameters:

Name	Type	Description	Default
versions	Sequence[str]	A list of version strings.	required
lower	str | None	The lower version bound (inclusive). If None, no lower limit is applied.	None
upper	str | None	The upper version bound (exclusive). If None, no upper limit is applied.	None

Returns:

Type	Description
list[str]	A list of version strings that fall within the specified bounds.

Example usage:

>>> from ghflowgen.version import filter_range_versions
>>> versions = filter_range_versions(
...     ["1.0.0", "1.2.0", "1.3.0", "2.0.0"], lower="1.1.0", upper="2.0.0"
... )
>>> versions
['1.2.0', '1.3.0']
>>> versions = filter_range_versions(["0.9.0", "1.0.0", "1.1.0"], lower="1.0.0")
>>> versions
['1.0.0', '1.1.0']

ghflowgen.version.filter_stable_versions

filter_stable_versions(
    versions: Sequence[str],
) -> list[str]

Filter out pre-release, post-release, and dev-release versions from a list of version strings.

A stable version is defined as

• Not a pre-release (e.g., alpha a, beta b, release candidate rc)
• Not a post-release (e.g., 1.0.0.post1)
• Not a development release (e.g., 1.0.0.dev1)

Parameters:

Name	Type	Description	Default
versions	Sequence[str]	A list of version strings.	required

Returns:

Type	Description
list[str]	A list containing only stable version strings.

Example usage:

>>> from ghflowgen.version import filter_stable_versions
>>> versions = filter_stable_versions(
...     ["1.0.0", "1.0.0a1", "2.0.0", "2.0.0.dev1", "3.0.0.post1"]
... )
>>> versions
['1.0.0', '2.0.0']

ghflowgen.version.filter_valid_versions

filter_valid_versions(versions: Sequence[str]) -> list[str]

Filter out invalid version strings based on PEP 440.

A valid version is one that can be parsed by packaging.version.Version. Invalid versions include strings that don't conform to semantic versioning rules.

Parameters:

Name	Type	Description	Default
versions	Sequence[str]	A list of version strings.	required

Returns:

Type	Description
list[str]	A list containing only valid version strings.

Example usage:

>>> from ghflowgen.version import filter_valid_versions
>>> versions = filter_valid_versions(
...     [
...         "1.0.0",
...         "1.0.0a1",
...         "2.0.0.post1",
...         "not-a-version",
...         "",
...         "2",
...         "3.0",
...         "v1.0.0",
...         "1.0.0.0.0",
...         "4.0.0.dev1",
...     ]
... )
>>> versions
['1.0.0', '1.0.0a1', '2.0.0.post1', '2', '3.0', 'v1.0.0', '1.0.0.0.0', '4.0.0.dev1']

ghflowgen.version.get_latest_major_versions

get_latest_major_versions(
    package: str,
    lower: str | None = None,
    upper: str | None = None,
) -> tuple[str, ...]

Get the latest version for each major version for a given package.

Parameters:

Name	Type	Description	Default
package	str	The package name.	required
lower	str | None	The lower version bound (inclusive). If None, no lower limit is applied.	None
upper	str | None	The upper version bound (exclusive). If None, no upper limit is applied.	None

Returns:

Type	Description
tuple[str, ...]	A tuple containing the latest version for each major version, sorted by major version number.

Example usage:

>>> from ghflowgen.version import get_latest_major_versions
>>> versions = get_latest_major_versions("requests")  # doctest: +SKIP

ghflowgen.version.get_latest_minor_versions

get_latest_minor_versions(
    package: str,
    lower: str | None = None,
    upper: str | None = None,
) -> tuple[str, ...]

Get the latest version for each minor version for a given package.

Parameters:

Name	Type	Description	Default
package	str	The package name.	required
lower	str | None	The lower version bound (inclusive). If None, no lower limit is applied.	None
upper	str | None	The upper version bound (exclusive). If None, no upper limit is applied.	None

Returns:

Type	Description
tuple[str, ...]	A tuple containing the latest version for each minor version, sorted by minor version number.

Example usage:

>>> from ghflowgen.version import get_latest_minor_versions
>>> versions = get_latest_minor_versions("requests")  # doctest: +SKIP

ghflowgen.version.get_package_version

get_package_version(package: str) -> Version | None

Get the package version.

Parameters:

Name	Type	Description	Default
package	str	Specifies the package name.	required

Returns:

Type	Description
Version | None	The package version.

Example usage:

>>> from ghflowgen.version import get_package_version
>>> get_package_version("pytest")
<Version('...')>

ghflowgen.version.get_python_major_minor cached

get_python_major_minor() -> str

Get the MAJOR.MINOR version of the current python.

Returns:

Type	Description
str	The MAJOR.MINOR version of the current python.

Example usage:

>>> from ghflowgen.version import get_python_major_minor
>>> get_python_major_minor()  # doctest: +SKIP

ghflowgen.version.get_versions

get_versions(
    package: str,
    lower: str | None = None,
    upper: str | None = None,
) -> tuple[str, ...]

Get the valid versions for a given package.

Parameters:

Name	Type	Description	Default
package	str	The package name.	required
lower	str | None	The lower version bound (inclusive). If None, no lower limit is applied.	None
upper	str | None	The upper version bound (exclusive). If None, no upper limit is applied.	None

Returns:

Type	Description
tuple[str, ...]	A tuple containing the valid versions.

Example usage:

>>> from ghflowgen.version import get_versions
>>> versions = get_versions("requests")  # doctest: +SKIP

ghflowgen.version.latest_major_versions

latest_major_versions(versions: Sequence[str]) -> list[str]

Return the latest version for each major version in a list of semantic versions.

This function takes a list of semantic version strings (e.g. "1.0.0", "1.2.1", "2.0.0"), groups them by their major version number, and returns only the latest version from each major group (based on minor and patch numbers).

Parameters:

Name	Type	Description	Default
versions	Sequence[str]	A list of version strings in semantic version format.	required

Returns:

Type	Description
list[str]	A list containing the latest version for each major version, sorted by major version number.

Example usage:

>>> from ghflowgen.version import latest_major_versions
>>> versions = latest_major_versions(["1.0.0", "1.1.0", "1.2.0", "1.2.1", "2.0.0"])
>>> versions
['1.2.1', '2.0.0']

ghflowgen.version.latest_minor_versions

latest_minor_versions(versions: Sequence[str]) -> list[str]

Return the latest version for each minor version in a list of semantic versions.

This function takes a list of semantic version strings (e.g. "1.0.0", "1.0.1", "1.1.0", "2.0.0"), groups them by their major and minor version numbers, and returns only the latest version from each minor group (based on the patch number).

Parameters:

Name	Type	Description	Default
versions	Sequence[str]	A list of version strings in semantic version format.	required

Returns:

Type	Description
list[str]	A list containing the latest version for each minor version, sorted by major and minor version numbers.

Example usage:

>>> from ghflowgen.version import latest_major_versions
>>> versions = latest_minor_versions(["1.0.0", "1.0.1", "1.1.0", "1.1.2", "2.0.0", "2.0.3"])
>>> versions
['1.0.1', '1.1.2', '2.0.3']

ghflowgen.version.sort_versions

sort_versions(
    versions: Sequence[str], reverse: bool = False
) -> list[str]

Sort a list of version strings in ascending or descending order.

Parameters:

Name	Type	Description	Default
versions	Sequence[str]	A list of version strings.	required
reverse	bool	If False, sort in ascending order; if True, sort in descending order.	False

Returns:

Type	Description
list[str]	A new list of version strings sorted according to semantic version order.

Example usage:

>>> import operator
>>> from ghflowgen.version import compare_version
>>> sort_versions(["1.0.0", "1.2.0", "1.1.0"])
['1.0.0', '1.1.0', '1.2.0']
>>> sort_versions(["1.0.0", "1.2.0", "1.1.0"], reverse=True)
['1.2.0', '1.1.0', '1.0.0']

ghflowgen.version.unique_versions

unique_versions(versions: Sequence[str]) -> list[str]

Return a list of unique versions while preserving order.

Parameters:

Name	Type	Description	Default
versions	Sequence[str]	A list of version strings.	required

Returns:

Type	Description
list[str]	A list containing only unique version strings, preserving the original order of first occurrence.

Example usage:

>>> from ghflowgen.version import unique_versions, sort_versions
>>> versions = sort_versions(unique_versions(["1.0.0", "1.0.1", "1.0.0", "1.2.0"]))
>>> versions
['1.0.0', '1.0.1', '1.2.0']