setuptools-us4us 0.1.0__py3-none-any.whl

setuptools_us4us/__init__.py

@@ -0,0 +1,28 @@
+"""
+setuptools-us4us: shared build-time helpers for the us4us Python packages.
+"""
+from setuptools_us4us.setup_helpers import (
+    is_dev_version,
+    read_version_file,
+    setup_version,
+    write_version_file,
+)
+from setuptools_us4us.version import __version__
+from setuptools_us4us.versioning import (
+    VersioningError,
+    find_parent_release_branch,
+    get_version,
+    get_version_for_release_branch,
+)
+
+__all__ = [
+    "VersioningError",
+    "__version__",
+    "find_parent_release_branch",
+    "get_version",
+    "get_version_for_release_branch",
+    "is_dev_version",
+    "read_version_file",
+    "setup_version",
+    "write_version_file",
+]

setuptools_us4us/cmd.py

@@ -0,0 +1,36 @@
+import subprocess
+from typing import Tuple, Union
+
+
+def run_cmd(cmd: str, return_code: bool = False,
+            cwd: str = None) -> Union[str, Tuple[str, str, int]]:
+    """
+    Runs the given command and returns its output.
+
+    :param cmd: command to run, split by whitespaces
+    :param return_code: when true, returns the ``(stdout, stderr, returncode)``
+      tuple instead of raising an exception on a non-zero exit code
+    :param cwd: working directory in which the command should be run,
+      ``None`` means the current working directory
+    :return: command's stdout (stripped), or the
+      ``(stdout, stderr, returncode)`` tuple when ``return_code`` is true
+    :raises RuntimeError: when the command exited with a non-zero code and
+      ``return_code`` is false
+    """
+    argv = cmd.strip().split(" ")
+    result = subprocess.run(
+        argv,
+        capture_output=True,
+        text=True,
+        check=False,
+        cwd=cwd,
+    )
+    stdout = result.stdout.strip()
+    stderr = result.stderr.strip()
+    if return_code:
+        return stdout, stderr, result.returncode
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"The process {argv} exited with code {result.returncode}, "
+            f"stdout: '{stdout}', stderr: '{stderr}'")
+    return stdout

setuptools_us4us/setup_helpers.py

@@ -0,0 +1,108 @@
+"""
+Helpers to be used directly from a project's ``setup.py``.
+
+Typical usage::
+
+    import setuptools
+    from setuptools_us4us import setup_version
+
+    version = setup_version("us4r_vandv")
+
+    setuptools.setup(
+        name="us4r_vandv",
+        version=version,
+        ...
+    )
+"""
+import os
+import re
+from typing import Optional
+
+from setuptools_us4us.versioning import VersioningError, get_version
+
+VERSION_FILE_TEMPLATE = '''\
+# This file is generated by setuptools-us4us, DO NOT EDIT.
+__version__ = "{version}"
+
+
+def is_dev() -> bool:
+    """
+    Returns true if this version is a development (non-release) build.
+    """
+    return {is_dev}
+
+
+def is_stable() -> bool:
+    """
+    Returns true if this version is a stable (release) build.
+    """
+    return not is_dev()
+'''
+
+
+def is_dev_version(version: str) -> bool:
+    """
+    Returns true when the given PEP 440 version is a development version,
+    i.e. it carries a ``.devN`` segment and/or a local version label.
+    """
+    return ".dev" in version or "+" in version
+
+
+def write_version_file(path: str, version: str) -> None:
+    """
+    Writes the ``version.py`` file with the given version number.
+
+    :param path: path of the file to write, e.g. ``us4r_vandv/version.py``
+    :param version: version number to write
+    """
+    directory = os.path.dirname(path)
+    if directory:
+        os.makedirs(directory, exist_ok=True)
+    with open(path, "w") as f:
+        f.write(VERSION_FILE_TEMPLATE.format(
+            version=version,
+            is_dev=is_dev_version(version),
+        ))
+
+
+def read_version_file(path: str) -> Optional[str]:
+    """
+    Reads the ``__version__`` value from the given ``version.py`` file.
+    Returns ``None`` when the file does not exist or has no ``__version__``.
+    """
+    if not os.path.exists(path):
+        return None
+    with open(path) as f:
+        match = re.search(r'^__version__\s*=\s*["\'](.+)["\']\s*$',
+                          f.read(), re.MULTILINE)
+    return match.group(1) if match is not None else None
+
+
+def setup_version(package_name: str, root: str = ".") -> str:
+    """
+    Determines the package version from git, writes it to
+    ``<root>/<package_name>/version.py`` and returns it.
+
+    When the version cannot be determined from git (e.g. the package is built
+    from an sdist, outside of a git repository), the version already present in
+    ``version.py`` is used instead; the file is then left untouched.
+
+    :param package_name: name of the Python package (directory) that holds
+      the ``version.py`` file, e.g. ``us4r_vandv``
+    :param root: project root directory
+    :return: the version number
+    :raises VersioningError: when the version can be determined neither from
+      git nor from an existing ``version.py``
+    """
+    version_file = os.path.join(root, package_name, "version.py")
+    try:
+        version = get_version(cwd=root)
+    except (VersioningError, RuntimeError, OSError) as e:
+        fallback = read_version_file(version_file)
+        if fallback is None:
+            raise VersioningError(
+                f"Could not determine the version of '{package_name}' from "
+                f"git ({e}), and there is no usable '{version_file}'.")
+        return fallback
+    write_version_file(version_file, version)
+    return version

setuptools_us4us/version.py

@@ -0,0 +1,16 @@
+# This file is generated by setuptools-us4us, DO NOT EDIT.
+__version__ = "0.1.0"
+
+
+def is_dev() -> bool:
+    """
+    Returns true if this version is a development (non-release) build.
+    """
+    return False
+
+
+def is_stable() -> bool:
+    """
+    Returns true if this version is a stable (release) build.
+    """
+    return not is_dev()

setuptools_us4us/versioning.py

@@ -0,0 +1,188 @@
+"""
+The rules implemented here are the ones used across the us4us Python
+projects:
+
+- a commit tagged with a release tag (``va.b.c``) marks the stable
+  version ``a.b.c``,
+- a commit on a **release branch** (``va.b.x`` or the legacy ``va.b.0-dev``)
+  produces a development version of the next major.minor, i.e.
+  ``a.b.(c+1).devYYYYMMDD``, where ``va.b.c`` is the latest release tag
+  reachable from that branch; when there is no reachable release tag,
+  ``a.b.0.devYYYYMMDD`` is used,
+- a commit on a feature branch produces the dev version of its
+  parent release branch, with the branch name local
+  version label, e.g. ``0.7.0.dev20260823+ref.mvandv.194``.
+"""
+import datetime
+import re
+from typing import Optional, Sequence, Tuple
+
+from setuptools_us4us.cmd import run_cmd
+
+RELEASE_BRANCH_PATTERNS = (
+    # Example: v0.7.x
+    r"^v(?P<major>\d+)\.(?P<minor>\d+)\.x$",
+    # Legacy example: v0.3.0-dev 
+    r"^v(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)-dev$",
+)
+
+#: Tag names denoting a stable release, e.g. v0.7.1
+RELEASE_TAG_PATTERN = r"^v(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)$"
+
+
+class VersioningError(RuntimeError):
+    """
+    Raised when the version number cannot be determined from git.
+    """
+    pass
+
+
+def get_today() -> str:
+    """
+    Returns the current date, formatted as ``YYYYMMDD``.
+    """
+    return datetime.datetime.now().strftime("%Y%m%d")
+
+
+def match_release_branch(branch: str) -> Optional[Tuple[int, int]]:
+    """
+    Returns the ``(major, minor)`` pair for the given release branch name,
+    or ``None`` when the name is not a release branch name.
+    """
+    for pattern in RELEASE_BRANCH_PATTERNS:
+        match = re.match(pattern, branch.strip())
+        if match is not None:
+            return int(match.group("major")), int(match.group("minor"))
+    return None
+
+
+def match_release_tag(tag: str) -> Optional[Tuple[int, int, int]]:
+    """
+    Returns the ``(major, minor, patch)`` triple for the given release tag,
+    or ``None`` when the name is not a release tag name.
+    """
+    match = re.match(RELEASE_TAG_PATTERN, tag.strip())
+    if match is None:
+        return None
+    return (int(match.group("major")), int(match.group("minor")),
+            int(match.group("patch")))
+
+
+def normalize_local_label(branch: str) -> str:
+    """
+    Converts a branch name to a PEP 440 local version label
+    e.g. ref-MVANDV-194 -> ref.mvandv.194.
+    """
+    label = re.sub(r"[^a-z0-9]+", ".", branch.strip().lower())
+    return label.strip(".")
+
+
+def _strip_v(version: str) -> str:
+    return version[1:] if version.startswith("v") else version
+
+
+def get_version_for_release_branch(branch: str, cwd: str = None,
+                                   today: str = None) -> str:
+    """
+    Returns the development version for the given release branch.
+
+    :param branch: release branch name e.g. v0.7.x
+    :param cwd: repository directory
+    :param today: date timestamp to use, YYYYMMDD; default: current date
+    :return: version string (e.g. v0.7.1)
+    """
+    today = today if today is not None else get_today()
+    major_minor = match_release_branch(branch)
+    if major_minor is None:
+        raise VersioningError(f"Not a release branch name: '{branch}'")
+    major, minor = major_minor
+    base = f"v{major}.{minor}"
+    tag, _, ret = run_cmd(
+        cmd=f"git describe --tags --match {base}.* --abbrev=0",
+        return_code=True, cwd=cwd,
+    )
+    if ret == 0 and tag:
+        release = match_release_tag(tag)
+        if release is not None:
+            # There already is a stable release on this branch: the next
+            # thing we are going to release is the next patch version.
+            tag_major, tag_minor, tag_patch = release
+            return f"v{tag_major}.{tag_minor}.{tag_patch + 1}.dev{today}"
+        # Non-conformant tag (e.g. v0.7.0-rc1): ignore it.
+    return f"{base}.0.dev{today}"
+
+
+def _list_branches(cwd: str = None) -> Sequence[str]:
+    """Returns the names of all local and remote-tracking branches."""
+    stdout, _, ret = run_cmd(
+        cmd="git branch --all --format=%(refname:short)",
+        return_code=True, cwd=cwd,
+    )
+    if ret != 0:
+        return ()
+    branches = []
+    for line in stdout.split("\n"):
+        name = line.strip()
+        if not name or "->" in name:
+            continue
+        # Drop the remote prefix, e.g. origin/v0.7.x -> v0.7.x
+        if "/" in name:
+            name = name.split("/", 1)[1]
+        branches.append(name)
+    return branches
+
+
+def find_parent_release_branch(cwd: str = None) -> str:
+    """
+    Returns the release branch the current ``HEAD`` was most likely branched
+    off from: out of all the release branches sharing a common ancestor with
+    ``HEAD``, the one with the highest ``major.minor``.
+
+    :raises VersioningError: when no such branch exists
+    """
+    candidates = []
+    for branch in set(_list_branches(cwd=cwd)):
+        major_minor = match_release_branch(branch)
+        if major_minor is None:
+            continue
+        _, _, ret = run_cmd(cmd=f"git merge-base {branch} HEAD",
+                            return_code=True, cwd=cwd)
+        if ret == 0:
+            candidates.append((major_minor, branch))
+    if len(candidates) == 0:
+        raise VersioningError(
+            "Could not determine the version number: the current HEAD has no "
+            "parent release branch (expected a branch named e.g. 'v0.7.x'). "
+            "Make sure the release branches are fetched "
+            "(e.g. 'git fetch --unshallow' in a CI checkout).")
+    candidates = sorted(candidates)
+    return candidates[-1][1]
+
+
+def get_version(cwd: str = None, today: str = None) -> str:
+    """
+    Determines the package version from the state of the git repository.
+
+    :param cwd: repository directory, the current working directory by default
+    :param today: date stamp to use, ``YYYYMMDD``; the current date by default
+    :return: PEP 440 version string, e.g. ``0.7.1.dev20260823``
+    :raises VersioningError: when the version number cannot be determined
+    """
+    today = today if today is not None else get_today()
+    current_branch = run_cmd(cmd="git rev-parse --abbrev-ref HEAD", cwd=cwd)
+    current_tags = run_cmd(cmd="git tag --points-at HEAD", cwd=cwd)
+
+    # 1. A tagged commit is a stable release.
+    for tag in current_tags.split("\n"):
+        if match_release_tag(tag) is not None:
+            return _strip_v(tag.strip())
+
+    # 2. A release branch: the development version of the next patch release.
+    if match_release_branch(current_branch) is not None:
+        return _strip_v(get_version_for_release_branch(
+            current_branch, cwd=cwd, today=today))
+
+    # 3. A feature branch: the parent release branch version + local label.
+    parent = find_parent_release_branch(cwd=cwd)
+    version = get_version_for_release_branch(parent, cwd=cwd, today=today)
+    return _strip_v(f"{version}+{normalize_local_label(current_branch)}")

setuptools_us4us-0.1.0.dist-info/METADATA

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: setuptools_us4us
+Version: 0.1.0
+Summary: Shared build-time (setuptools) helpers for the us4us Python packages.
+Home-page: https://us4us.eu
+Author: us4us Ltd.
+Author-email: support@us4us.eu
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-python
+Dynamic: summary
+
+# setuptools-us4us
+
+Common setuptools extensions used by the us4us Python packages, e.g.
+determining the package version from the state of the git repository
+(release tags and branches).
+
+## Installation
+
+```
+pip install setuptools_us4us
+```
+
+Usually it is needed only at build time, e.g. in the project's `pyproject.toml`:
+
+```toml
+[build-system]
+requires = ["setuptools>=61", "wheel", "setuptools_us4us"]
+build-backend = "setuptools.build_meta"
+```
+
+and `setup.py`:
+
+```python
+import setuptools
+from setuptools_us4us import setup_version
+
+setuptools.setup(
+    name="my_package",
+    version=setup_version("my_package"),  # also writes my_package/version.py
+    ...
+)
+```
+
+## Repository structure
+
+- `setuptools_us4us/versioning.py`: git-based version numbers
+  (`get_version`, `get_version_for_release_branch`,
+  `find_parent_release_branch`):
+  - tagged commit `va.b.c` -> `a.b.c`,
+  - release branch `va.b.x` -> `a.b.(c+1).devYYYYMMDD`,
+  - feature branch -> parent release branch version + branch name as local
+    label, e.g. `0.7.0.dev20260823+ref.mvandv.194`.
+- `setuptools_us4us/setup_helpers.py`: helpers for `setup.py`
+  (`setup_version`, `write_version_file`, `read_version_file`,
+  `is_dev_version`).
+- `setuptools_us4us/cmd.py`: running shell commands (`run_cmd`).

setuptools_us4us-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+setuptools_us4us/__init__.py,sha256=NWOIXdYO2V4epz8yHjBGLZOSpvLv496mUC2c_h3Uwek,657
+setuptools_us4us/cmd.py,sha256=40OpqVJyfYAPrNnD6DDoABGzQKZVFM4r4tRhZzcsTlY,1299
+setuptools_us4us/setup_helpers.py,sha256=yZSmz51zt21goozx4F1M_UdpQ3ke1XkINuuaEH0u_qU,3305
+setuptools_us4us/version.py,sha256=xPY9lfp6N_vdi4fTqGroHseX11_-TIsbW0_QlWD6HR8,338
+setuptools_us4us/versioning.py,sha256=VzQeV3KyGGWCYHHy-T4WOgfvQf6JuBNUP_hC-FNhu2Y,6934
+setuptools_us4us-0.1.0.dist-info/METADATA,sha256=TBdqp9DJuYZwdTh0ebEV0cBnbaqnUyxDUHrBpgpH_Kw,1974
+setuptools_us4us-0.1.0.dist-info/WHEEL,sha256=a-udL2m4V_6Yn8b-uKzWb12RjRxwwMo6ohYFM24tpaY,91
+setuptools_us4us-0.1.0.dist-info/top_level.txt,sha256=NrGCQnrB2gB687Wy8oH5TqCpucfu8rIDkQj4Jth0WGw,17
+setuptools_us4us-0.1.0.dist-info/RECORD,,

setuptools_us4us-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

setuptools_us4us-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+setuptools_us4us