lib.version: Add module #91
Loading…
Reference in a new issue
No description provided.
Delete branch "jan/feature/20260909-lib-version-add-api-docstrings"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
This commit refactors version and dependency handling in jw-pkg in the pkg_relations() function. It provides a more versatile framework for version handling that's also easier to understand.
lib.version: Add module to parse dependency specs
pkg_relations() parses dependency specifications such as
foo-devel >= 1.2.3-4with inline regular expressions and mixes the parsing with version macro expansion and rendering in three different syntaxes.This commit adds the lib.version module that owns the parsing of a single specification: the base and full name and the version boundary with its operator. Rendering happens in
constraint_str()inSEM_VER, DEBIANorNAMES_ONLYsyntax, withuntemplated,include_revision,as_range,no_subpackagesandquoteoptions. TheVERSION,VERSION-REVISIONandREVISIONmacros are resolved through a version lookup callback,lib.version.Version.parse_deps_spec()splits comma-separated specification strings intoVersionobjects, andVersion` breaks a version down into its major, minor, micro and revision parts.Unit tests cover parsing, macro resolution, rendering in all syntaxes and the range expansion.
The module is designed to be integrated into the status quo and intentionally does not address a couple of further TODOs. Notably
version.Syntax.SEM_VERis intended to replacepkg_relations.VersionSyntax.SemVer, but neither are really semantic versioning according to spec. They are close but more targeted toward RPM and Debian package versioning. And the naming and semantics differ from SemVer.TODOs: RELEASE over the rest of jw-pkg needs to be adjusted by a later commit.
Syntax.SEM_VERshould also be renamed, toSyntax.JW_PKGmaybe, because, as said, it's not SemVer and will probably never be - SemVer doesn't provide the compatibility guarantees that the jw-pkg versioning scheme offers. To be documented.cmds.projects.lib.pkg_relations: Integrate lib.version
pkg_relations()function is a horribly bad read. It contains a mind-bending amount of interwoven case distinctions that are not clearly reflected in the participating variable and function names. Much of it is version handling. That's intricate by nature, but much of it has now been implemented in the lib.version module, so moving the logic there makes the function a good deal more readable than before. That's most of what this commit does.lib.versioninstead ofpkg_relations-defined macros, and fix the fallout inBaseCmdPkgRelationsandCmdCreateFile.lib.versionalso as a central place for dep string parsing fromApp.lib.version: Add API docstrings
The lib.version module carries no documentation: the
Syntax,ComponentandBoundarytypes, theVersionandDependencyclasses 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.pytypes, the compatibility tier table in the Version class, and a short description for every public method, with the threenext_*methods citing the tier each one steps to.pkg_relations() parses dependency specifications such as 'foo-devel >= 1.2.3-4' with inline regular expressions and mixes the parsing with version macro expansion and rendering in three different syntaxes. This commit adds the lib.version module that owns the parsing of a single specification: the base and full name and the version boundary with its operator. Rendering happens in constraint_str() in SEM_VER, DEBIAN or NAMES_ONLY syntax, with untemplated, include_revision, as_range, no_subpackages and quote options. The VERSION, VERSION-REVISION and REVISION macros are resolved through a version lookup callback, lib.version.Version.parse_deps_spec() splits comma-separated specification strings into Version objects, and Version breaks a version down into its major, minor, micro and revision parts. Unit tests cover parsing, macro resolution, rendering in all syntaxes and the range expansion. The module is designed to be integrated into the status quo and intentionally does not address a couple of further TODOs. Notably version.Syntax.SEM_VER is intended to replace pkg_relations.VersionSyntax.SemVer, but neither are really semantic versioning according to spec. They are close but more targeted toward RPM and Debian package versioning. And the naming and semantics differ from SemVer. Naming of the four components (major and minor version) is identical, semantic meaning aside, there's no disagreement between real SemVer, Debian, RPM and jw-pkg. The third and fourth component deviate: SemVer Debian RPM jw-pkg lib.version 3 PATCH RELEASE MICRO 4 PRERELEASE Revision Release REVISION REVISION TODOs: RELEASE over the rest of jw-pkg needs to be adjusted by a later commit. Syntax.SEM_VER should also be renamed, to Syntax.JW_PKG maybe, because, as said, it's not SemVer and will probably never be - SemVer doesn't provide the compatibility guarantees that the jw-pkg versioning scheme offers. To be documented. Signed-off-by: Jan Lindemann <jan@janware.com>lib.version: Add API docstringsto lib.version: Add module01a0c406476d60df44976d60df4497a805972a3e