jpayne@69: # This file is dual licensed under the terms of the Apache License, Version jpayne@69: # 2.0, and the BSD License. See the LICENSE file in the root of this repository jpayne@69: # for complete details. jpayne@69: jpayne@69: from __future__ import annotations jpayne@69: jpayne@69: import functools jpayne@69: import re jpayne@69: from typing import NewType, Tuple, Union, cast jpayne@69: jpayne@69: from .tags import Tag, parse_tag jpayne@69: from .version import InvalidVersion, Version, _TrimmedRelease jpayne@69: jpayne@69: BuildTag = Union[Tuple[()], Tuple[int, str]] jpayne@69: NormalizedName = NewType("NormalizedName", str) jpayne@69: jpayne@69: jpayne@69: class InvalidName(ValueError): jpayne@69: """ jpayne@69: An invalid distribution name; users should refer to the packaging user guide. jpayne@69: """ jpayne@69: jpayne@69: jpayne@69: class InvalidWheelFilename(ValueError): jpayne@69: """ jpayne@69: An invalid wheel filename was found, users should refer to PEP 427. jpayne@69: """ jpayne@69: jpayne@69: jpayne@69: class InvalidSdistFilename(ValueError): jpayne@69: """ jpayne@69: An invalid sdist filename was found, users should refer to the packaging user guide. jpayne@69: """ jpayne@69: jpayne@69: jpayne@69: # Core metadata spec for `Name` jpayne@69: _validate_regex = re.compile( jpayne@69: r"^([A-Z0-9]|[A-Z0-9][A-Z0-9._-]*[A-Z0-9])$", re.IGNORECASE jpayne@69: ) jpayne@69: _canonicalize_regex = re.compile(r"[-_.]+") jpayne@69: _normalized_regex = re.compile(r"^([a-z0-9]|[a-z0-9]([a-z0-9-](?!--))*[a-z0-9])$") jpayne@69: # PEP 427: The build number must start with a digit. jpayne@69: _build_tag_regex = re.compile(r"(\d+)(.*)") jpayne@69: jpayne@69: jpayne@69: def canonicalize_name(name: str, *, validate: bool = False) -> NormalizedName: jpayne@69: if validate and not _validate_regex.match(name): jpayne@69: raise InvalidName(f"name is invalid: {name!r}") jpayne@69: # This is taken from PEP 503. jpayne@69: value = _canonicalize_regex.sub("-", name).lower() jpayne@69: return cast(NormalizedName, value) jpayne@69: jpayne@69: jpayne@69: def is_normalized_name(name: str) -> bool: jpayne@69: return _normalized_regex.match(name) is not None jpayne@69: jpayne@69: jpayne@69: @functools.singledispatch jpayne@69: def canonicalize_version( jpayne@69: version: Version | str, *, strip_trailing_zero: bool = True jpayne@69: ) -> str: jpayne@69: """ jpayne@69: Return a canonical form of a version as a string. jpayne@69: jpayne@69: >>> canonicalize_version('1.0.1') jpayne@69: '1.0.1' jpayne@69: jpayne@69: Per PEP 625, versions may have multiple canonical forms, differing jpayne@69: only by trailing zeros. jpayne@69: jpayne@69: >>> canonicalize_version('1.0.0') jpayne@69: '1' jpayne@69: >>> canonicalize_version('1.0.0', strip_trailing_zero=False) jpayne@69: '1.0.0' jpayne@69: jpayne@69: Invalid versions are returned unaltered. jpayne@69: jpayne@69: >>> canonicalize_version('foo bar baz') jpayne@69: 'foo bar baz' jpayne@69: """ jpayne@69: return str(_TrimmedRelease(str(version)) if strip_trailing_zero else version) jpayne@69: jpayne@69: jpayne@69: @canonicalize_version.register jpayne@69: def _(version: str, *, strip_trailing_zero: bool = True) -> str: jpayne@69: try: jpayne@69: parsed = Version(version) jpayne@69: except InvalidVersion: jpayne@69: # Legacy versions cannot be normalized jpayne@69: return version jpayne@69: return canonicalize_version(parsed, strip_trailing_zero=strip_trailing_zero) jpayne@69: jpayne@69: jpayne@69: def parse_wheel_filename( jpayne@69: filename: str, jpayne@69: ) -> tuple[NormalizedName, Version, BuildTag, frozenset[Tag]]: jpayne@69: if not filename.endswith(".whl"): jpayne@69: raise InvalidWheelFilename( jpayne@69: f"Invalid wheel filename (extension must be '.whl'): {filename!r}" jpayne@69: ) jpayne@69: jpayne@69: filename = filename[:-4] jpayne@69: dashes = filename.count("-") jpayne@69: if dashes not in (4, 5): jpayne@69: raise InvalidWheelFilename( jpayne@69: f"Invalid wheel filename (wrong number of parts): {filename!r}" jpayne@69: ) jpayne@69: jpayne@69: parts = filename.split("-", dashes - 2) jpayne@69: name_part = parts[0] jpayne@69: # See PEP 427 for the rules on escaping the project name. jpayne@69: if "__" in name_part or re.match(r"^[\w\d._]*$", name_part, re.UNICODE) is None: jpayne@69: raise InvalidWheelFilename(f"Invalid project name: {filename!r}") jpayne@69: name = canonicalize_name(name_part) jpayne@69: jpayne@69: try: jpayne@69: version = Version(parts[1]) jpayne@69: except InvalidVersion as e: jpayne@69: raise InvalidWheelFilename( jpayne@69: f"Invalid wheel filename (invalid version): {filename!r}" jpayne@69: ) from e jpayne@69: jpayne@69: if dashes == 5: jpayne@69: build_part = parts[2] jpayne@69: build_match = _build_tag_regex.match(build_part) jpayne@69: if build_match is None: jpayne@69: raise InvalidWheelFilename( jpayne@69: f"Invalid build number: {build_part} in {filename!r}" jpayne@69: ) jpayne@69: build = cast(BuildTag, (int(build_match.group(1)), build_match.group(2))) jpayne@69: else: jpayne@69: build = () jpayne@69: tags = parse_tag(parts[-1]) jpayne@69: return (name, version, build, tags) jpayne@69: jpayne@69: jpayne@69: def parse_sdist_filename(filename: str) -> tuple[NormalizedName, Version]: jpayne@69: if filename.endswith(".tar.gz"): jpayne@69: file_stem = filename[: -len(".tar.gz")] jpayne@69: elif filename.endswith(".zip"): jpayne@69: file_stem = filename[: -len(".zip")] jpayne@69: else: jpayne@69: raise InvalidSdistFilename( jpayne@69: f"Invalid sdist filename (extension must be '.tar.gz' or '.zip'):" jpayne@69: f" {filename!r}" jpayne@69: ) jpayne@69: jpayne@69: # We are requiring a PEP 440 version, which cannot contain dashes, jpayne@69: # so we split on the last dash. jpayne@69: name_part, sep, version_part = file_stem.rpartition("-") jpayne@69: if not sep: jpayne@69: raise InvalidSdistFilename(f"Invalid sdist filename: {filename!r}") jpayne@69: jpayne@69: name = canonicalize_name(name_part) jpayne@69: jpayne@69: try: jpayne@69: version = Version(version_part) jpayne@69: except InvalidVersion as e: jpayne@69: raise InvalidSdistFilename( jpayne@69: f"Invalid sdist filename (invalid version): {filename!r}" jpayne@69: ) from e jpayne@69: jpayne@69: return (name, version)