janware/jw-pkg
Watch
1
Code Pull requests Activity Actions

lib.version: Add API docstrings
All checks were successful
CI / Packaging - Kali Linux (push) Successful in 4m4s
Details
CI / Packaging - OpenSUSE Tumbleweed (push) Successful in 4m9s
Details
CI / Packaging test (push) Successful in 0s
Details

Browse source 
The lib.version module carries no documentation: the Syntax, Component and
Boundary types, the Version and Dependency classes and their public methods
are bare, and the compatibility tiers the next_* stepping methods implement
are not documented anywhere.

Add docstrings: a line each for the base.py types, the compatibility
tier table in the Version class, and a short description for every
public method, with the three next_* methods citing the tier each one
steps to.

Assisted-by: unsloth/Qwen3.8-27B-GGUF:Q4_K_M with pi.dev v0.84.2
Signed-off-by: Jan Lindemann <jan@janware.com>
This commit is contained in:
Jan Lindemann 2026-09-09 13:52:30 +02:00
commit 831cff524a
3 changed files with 65 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

18
src/python/jw/pkg/lib/version/Dependency.py
View file

@ -14,6 +14,10 @@ if TYPE_CHECKING:
from typing import ClassVar
class Dependency: # export
"""A single package dependency: a package name and an optional
version boundary, parsed from a specification such as
'foo-devel >= 1.2.3-4'. Rendering happens in constraint_str().
"""
class Error(ValueError):
pass
@ -106,6 +110,9 @@ class Dependency: # export
return Version.strip_package_suffix(self.full_name)
def version_boundaries(self, expanded: bool = False) -> Sequence[Boundary]:
"""The parsed version boundary, or the range it spans when
expanded is True and it pins a full version.
"""
return self.__version_boundaries(expanded)
def constraint_str(
@ -117,6 +124,16 @@ class Dependency: # export
no_subpackages: bool = False,
quote: str | None = None,
) -> str:
"""Render the dependency as a version constraint string.
NAMES_ONLY renders the name alone. untemplated keeps the
VERSION, VERSION-REVISION and REVISION macros as written instead
of the resolved versions. include_revision = False drops the
revision of VERSION specs. as_range expands a boundary that
pins a full version into the range it spans. no_subpackages
renders the base name, quote wraps the result in the given
string.
"""
def __str() -> str:
name = self.base_name if no_subpackages else self.full_name
@ -139,6 +156,7 @@ class Dependency: # export
spec: str,
lookup_version: Lookup | None = None,
) -> Sequence[Dependency]:
"""Split a comma-separated specification into Dependency objects"""
return [
Dependency(spec = spec.strip(), lookup_version = lookup_version)
for spec in spec.split(',')