From 60a45e9e8a939aeb75c91a14fc779af4b8a2c6e2 Mon Sep 17 00:00:00 2001 From: Tzu-ping Chung Date: Mon, 2 Oct 2023 14:51:28 +0800 Subject: [PATCH] Clarify version split/join usage This adds a docstring on _version_join to clarify its expectation on the input value. Since this is a strictly internal function, I also removed the assert statement so it does not fire at runtime and break user code. If it ever does fire, it would be due to a bug in packaging and we should fix it instead. Both _version_split and _version_join also received slight refactoring. --- src/packaging/specifiers.py | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/src/packaging/specifiers.py b/src/packaging/specifiers.py index 87d0e0ad..94448327 100644 --- a/src/packaging/specifiers.py +++ b/src/packaging/specifiers.py @@ -644,14 +644,17 @@ def filter( def _version_split(version: str) -> List[str]: - result: List[str] = [] + """Split version into components. - epoch, sep, rest = version.rpartition("!") + The split components are intended for version comparison. The logic does + not attempt to retain the original version string, so joining the + components back with :func:`_version_join` may not produce the original + version string. + """ + result: List[str] = [] - if sep: - result.append(epoch) - else: - result.append("0") + epoch, _, rest = version.rpartition("!") + result.append(epoch or "0") for item in rest.split("."): match = _prefix_regex.search(item) @@ -663,12 +666,14 @@ def _version_split(version: str) -> List[str]: def _version_join(components: List[str]) -> str: - # This function only works with numeric components. - assert all(c.isdigit() for c in components) + """Join split version components into a version string. + This function assumes the input came from :func:`_version_split`, where the + first component must be the epoch (either empty or numeric), and all other + components numeric. + """ epoch, *rest = components - - return epoch + "!" + ".".join(rest) + return f"{epoch}!{'.'.join(rest)}" def _is_not_suffix(segment: str) -> bool: