nilan-connect 0.2.0rc1__tar.gz

nilan_connect-0.2.0rc1/.gitattributes

@@ -0,0 +1,2 @@
+# GitHub's source downloads carry the version setuptools-scm needs, from this file.
+.git_archival.txt  export-subst

nilan_connect-0.2.0rc1/.github/dependabot.yml

@@ -0,0 +1,17 @@
+# Proposes updates to the pinned actions and test tools as pull requests, which the tests then
+# check before anything is merged.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    labels:
+      - dependencies
+
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    labels:
+      - dependencies

nilan_connect-0.2.0rc1/.github/release-drafter.yml

@@ -0,0 +1,63 @@
+name-template: 'v$RESOLVED_VERSION'
+tag-template: 'v$RESOLVED_VERSION'
+change-template: '- #$NUMBER $TITLE @$AUTHOR'
+sort-direction: ascending
+categories:
+  - type: 'pre-exclude'
+    when:
+      label: 'skip-changelog'
+
+  # Each pull request is listed once, under the first of these its labels match.
+  - title: '🛠 Breaking Changes'
+    exclusive: true
+    when:
+      label: 'breaking-change'
+
+  - title: '🚀 Features'
+    exclusive: true
+    when:
+      labels:
+        - 'feature request'
+        - 'enhancement'
+
+  - title: '🐛 Bug Fixes'
+    exclusive: true
+    when:
+      labels:
+        - 'fix'
+        - 'bugfix'
+        - 'bug'
+
+  - title: '🧰 Maintenance'
+    exclusive: true
+    when:
+      label: 'chore'
+
+  - title: '📦 Dependencies'
+    exclusive: true
+    when:
+      label: 'dependencies'
+
+  # The next version: a minor bump for a breaking change or by label, a patch otherwise. A major
+  # is never taken from a label, as one placed wrongly must not release a new major version.
+  - type: 'version-resolver'
+    semver-increment: 'minor'
+    when:
+      labels:
+        - 'breaking-change'
+        - 'minor'
+  - type: 'version-resolver'
+    semver-increment: 'patch'
+template: |
+  ## Changes
+  $CHANGES
+autolabeler:
+  - label: 'bug'
+    branch:
+      - '/fix\/.+/'
+  - label: 'feature request'
+    branch:
+      - '/feature\/.+/'
+  - label: 'chore'
+    branch:
+      - '/chore\/.+/'

nilan_connect-0.2.0rc1/.github/release.yml

@@ -0,0 +1,27 @@
+# How GitHub groups a release's notes: each pull request by its labels.
+changelog:
+  exclude:
+    labels:
+      - skip-changelog
+  categories:
+    - title: 🛠 Breaking Changes
+      labels:
+        - breaking-change
+    - title: 🚀 Features
+      labels:
+        - feature request
+        - enhancement
+    - title: 🐛 Bug Fixes
+      labels:
+        - bug
+        - fix
+        - bugfix
+    - title: 🧰 Maintenance
+      labels:
+        - chore
+    - title: 📦 Dependencies
+      labels:
+        - dependencies
+    - title: Other Changes
+      labels:
+        - "*"

nilan_connect-0.2.0rc1/.github/scripts/pyrightconfig.json

@@ -0,0 +1,5 @@
+{
+  // A project of its own, as pyright skips directories whose names begin with a dot.
+  "typeCheckingMode": "strict",
+  "reportMissingTypeStubs": "none"
+}

nilan_connect-0.2.0rc1/.github/scripts/release_version.py

@@ -0,0 +1,164 @@
+"""The release version: work it out, and write it into the package.
+
+    release_version.py next KIND DRAFT OVERRIDE TAGS [PUBLISHED]
+                                            prints version=, tag=, prerelease= and previous_tag=
+                                            lines for the next KIND ("release candidate" or
+                                            "final release"); DRAFT is the draft release's
+                                            version, OVERRIDE a version to take instead, either
+                                            may be empty; TAGS is a file of every tag, PUBLISHED
+                                            one of every version published, one per line
+    release_version.py changes SINCE MERGED refuses a release when MERGED, a file of the pull
+                                            requests merged since the release SINCE, is empty
+    release_version.py write VERSION FILE   sets the one `__version__ = "..."` line in FILE
+"""
+import re
+import sys
+from pathlib import Path
+
+from packaging.version import InvalidVersion, Version
+
+_LINE = re.compile(r'^__version__ = "[^"\n]*"$', re.MULTILINE)
+
+RELEASE_CANDIDATE = "release candidate"
+FINAL_RELEASE = "final release"
+
+
+def _canonical(text: str) -> Version:
+    """The version `text` names, refused unless `text` is already its canonical form."""
+    try:
+        version = Version(text)
+    except InvalidVersion:
+        sys.exit(f"::error::{text!r} is not a PEP 440 version, such as 1.2.3 or 1.2.3rc1")
+    if str(version) != text:
+        # A build writes the canonical form into the file names, so any other spelling would
+        # tag one version and publish another.
+        sys.exit(f"::error::write {text!r} as {str(version)!r}, its canonical PEP 440 form")
+    if len(version.release) != 3 or version.epoch or version.local:
+        # 1.2 and 1.2.0 are one version to PEP 440 but two tags; PyPI refuses a local version.
+        sys.exit(f"::error::{text!r} must be MAJOR.MINOR.PATCH, optionally with a pre-release, "
+                 f"such as 1.2.3 or 1.2.3rc1")
+    return version
+
+
+def known_versions(lines: list[str]) -> list[Version]:
+    """The versions `lines` name, skipping tags that name none."""
+    versions: list[Version] = []
+    for line in lines:
+        try:
+            versions.append(Version(line.strip().removeprefix("v")))
+        except InvalidVersion:
+            continue
+    return versions
+
+
+def next_version(kind: str, draft: str, override: str, known: list[Version]) -> tuple[Version, str]:
+    """The version to release as `kind`, and how it was found.
+
+    Without an override, an open release-candidate series - the highest known version being a
+    pre-release - is continued, or ended by a final release, unless the draft names a higher
+    version; that starts a new series. A new major version is taken only as an override, so that
+    a label placed wrongly cannot release one. The result must be higher than every known version,
+    as pip installs the highest and PyPI never takes a version twice.
+    """
+    if kind not in (RELEASE_CANDIDATE, FINAL_RELEASE):
+        sys.exit(f"::error::{kind!r} is neither {RELEASE_CANDIDATE!r} nor {FINAL_RELEASE!r}")
+    top = max(known, default=None)
+    if override:
+        version = _canonical(override)
+        if version.is_prerelease != (kind == RELEASE_CANDIDATE):
+            sys.exit(f"::error::{version} is {'a pre-release' if version.is_prerelease else 'a final release'}, "
+                     f"not a {kind}")
+        how = "given as the override"
+    else:
+        series = Version(top.base_version) if top is not None and top.is_prerelease else None
+        base = series
+        if draft:
+            proposed = _canonical(draft.removeprefix("v"))
+            if proposed.is_prerelease:
+                sys.exit(f"::error::the draft release names {proposed}, a pre-release, not the next version")
+            if base is None or proposed > base:
+                base = proposed
+        if base is None:
+            sys.exit("::error::no draft release names the next version, and no release-candidate "
+                     "series is open; give the version as the override")
+        if kind == FINAL_RELEASE:
+            version = base
+            how = "ends the release-candidate series" if base == series else "the draft release's version"
+        elif base == series and top is not None and top.pre is not None and top.pre[0] == "rc":
+            version = Version(f"{base}rc{top.pre[1] + 1}")
+            how = f"the release candidate after {top}"
+        else:
+            version = Version(f"{base}rc1")
+            how = f"the first release candidate of {base}"
+        if top is not None and version.major > top.major:
+            sys.exit(f"::error::{version} is a new major version; type it as the override")
+    if top is not None and version <= top:
+        sys.exit(f"::error::{version} is not higher than {top}, the highest version already tagged "
+                 f"or published")
+    return version, how
+
+
+def previous_tag(version: Version, tags: list[str]) -> str | None:
+    """The tag the notes of `version` start from, None to start from the beginning.
+
+    That is the release candidate or final release before it; before a final release, the final
+    release before it, so that its notes hold every change its release candidates had. Other
+    pre-releases, such as test builds, are skipped.
+    """
+    found: list[tuple[Version, str]] = []
+    for tag in tags:
+        try:
+            earlier = Version(tag.strip().removeprefix("v"))
+        except InvalidVersion:
+            continue
+        if earlier >= version or earlier.dev is not None:
+            continue
+        if earlier.pre is not None and (earlier.pre[0] != "rc" or not version.is_prerelease):
+            continue
+        found.append((earlier, tag.strip()))
+    return max(found)[1] if found else None
+
+
+def require_changes(since: str, pull_requests: list[str]) -> None:
+    """Refuse a release when no pull request has been merged since the release `since`.
+
+    What users get comes through pull requests; a change pushed straight to main - CI, tests,
+    the release itself - gives them nothing to release.
+    """
+    if not any(line.strip() for line in pull_requests):
+        sys.exit(f"::error::no pull request has been merged since {since}; there is nothing to release")
+
+
+def _lines(path: str) -> list[str]:
+    return Path(path).read_text(encoding="utf-8").splitlines()
+
+
+def _print(version: Version) -> None:
+    print(f"version={version}")
+    print(f"tag=v{version}")
+    print(f"prerelease={'true' if version.is_prerelease else 'false'}")
+
+
+def write(text: str, path: Path) -> None:
+    version = _canonical(text)
+    source = path.read_text(encoding="utf-8")
+    found = _LINE.findall(source)
+    if len(found) != 1:
+        sys.exit(f"::error::{path} must hold exactly one `__version__ = \"...\"` line, found {len(found)}")
+    path.write_text(_LINE.sub(f'__version__ = "{version}"', source), encoding="utf-8")
+
+
+if __name__ == "__main__":
+    match sys.argv[1:]:
+        case ["next", kind, draft, override, tags, *published] if len(published) <= 1:
+            found, how = next_version(kind, draft, override,
+                                      known_versions(_lines(tags) + [v for f in published for v in _lines(f)]))
+            print(f"{found}: {how}", file=sys.stderr)
+            _print(found)
+            print(f"previous_tag={previous_tag(found, _lines(tags)) or ''}")
+        case ["changes", since, merged]:
+            require_changes(since, _lines(merged))
+        case ["write", text, path]:
+            write(text, Path(path))
+        case _:
+            sys.exit(__doc__)

nilan_connect-0.2.0rc1/.github/scripts/test_release_version.py

@@ -0,0 +1,125 @@
+"""Tests of how the release works out its version."""
+import pytest
+from packaging.version import Version
+
+from release_version import FINAL_RELEASE, RELEASE_CANDIDATE, known_versions, next_version, previous_tag, require_changes
+
+
+def _next(kind: str, draft: str, known: list[str], override: str = "") -> str:
+    return str(next_version(kind, draft, override, known_versions(known))[0])
+
+
+def test_a_release_candidate_continues_the_open_series_below_the_draft() -> None:
+    assert _next(RELEASE_CANDIDATE, "v0.1.10", ["v0.1.8", "0.1.9", "v0.2.0rc1", "0.2.0rc1"]) == "0.2.0rc2"
+
+
+def test_a_final_release_ends_the_open_series() -> None:
+    assert _next(FINAL_RELEASE, "v0.1.10", ["v0.1.8", "v0.2.0rc1", "v0.2.0rc2"]) == "0.2.0"
+
+
+def test_a_draft_above_the_open_series_starts_a_new_one() -> None:
+    assert _next(RELEASE_CANDIDATE, "v0.3.0", ["v0.2.0rc2"]) == "0.3.0rc1"
+    assert _next(FINAL_RELEASE, "v0.3.0", ["v0.2.0rc2"]) == "0.3.0"
+
+
+@pytest.mark.parametrize("kind", [RELEASE_CANDIDATE, FINAL_RELEASE])
+def test_a_new_major_version_is_never_worked_out(kind: str) -> None:
+    with pytest.raises(SystemExit, match="1.0.0(rc1)? is a new major version"):
+        _next(kind, "v1.0.0", ["v0.2.0rc2"])
+
+
+def test_a_new_major_version_is_taken_as_an_override() -> None:
+    assert _next(RELEASE_CANDIDATE, "v0.2.1", ["v0.2.0"], override="1.0.0rc1") == "1.0.0rc1"
+
+
+def test_without_an_open_series_the_draft_names_the_version() -> None:
+    assert _next(RELEASE_CANDIDATE, "v0.3.0", ["v0.2.0rc1", "v0.2.0"]) == "0.3.0rc1"
+    assert _next(FINAL_RELEASE, "v0.3.0", ["v0.2.0"]) == "0.3.0"
+
+
+def test_the_first_release_needs_nothing_known() -> None:
+    assert _next(FINAL_RELEASE, "v0.1.0", []) == "0.1.0"
+
+
+def test_a_series_of_betas_continues_with_its_first_release_candidate() -> None:
+    assert _next(RELEASE_CANDIDATE, "v0.2.0", ["v0.1.0", "v0.2.0b3"]) == "0.2.0rc1"
+
+
+def test_an_open_series_needs_no_draft() -> None:
+    assert _next(RELEASE_CANDIDATE, "", ["v0.2.0rc1"]) == "0.2.0rc2"
+    assert _next(FINAL_RELEASE, "", ["v0.2.0rc1"]) == "0.2.0"
+
+
+def test_without_a_draft_or_an_open_series_the_version_must_be_given() -> None:
+    with pytest.raises(SystemExit, match="give the version as the override"):
+        _next(FINAL_RELEASE, "", ["v0.2.0"])
+
+
+def test_a_draft_below_what_is_published_is_refused() -> None:
+    with pytest.raises(SystemExit, match="0.1.10 is not higher than 0.2.0"):
+        _next(FINAL_RELEASE, "v0.1.10", ["v0.2.0"])
+
+
+def test_a_version_withdrawn_from_the_tags_still_counts_from_pypi() -> None:
+    with pytest.raises(SystemExit, match="0.1.9 is not higher than 0.1.9"):
+        _next(FINAL_RELEASE, "v0.1.9", ["v0.1.8", "0.1.9"])
+
+
+def test_the_override_replaces_the_version_worked_out() -> None:
+    assert _next(RELEASE_CANDIDATE, "v0.1.10", ["v0.2.0rc1"], override="0.3.0rc1") == "0.3.0rc1"
+
+
+def test_the_override_must_still_be_higher_than_every_known_version() -> None:
+    with pytest.raises(SystemExit, match="0.2.0rc1 is not higher than 0.2.0rc1"):
+        _next(RELEASE_CANDIDATE, "", ["v0.2.0rc1"], override="0.2.0rc1")
+
+
+@pytest.mark.parametrize(("kind", "override"), [(FINAL_RELEASE, "0.2.0rc2"), (RELEASE_CANDIDATE, "0.2.0")])
+def test_the_override_must_be_the_kind_chosen(kind: str, override: str) -> None:
+    with pytest.raises(SystemExit, match=f"not a {kind}"):
+        _next(kind, "", ["v0.2.0rc1"], override=override)
+
+
+@pytest.mark.parametrize("override", ["v0.3.0", "0.3", "0.3.0-rc1", "0.3.0+local"])
+def test_the_override_must_be_canonical_major_minor_patch(override: str) -> None:
+    with pytest.raises(SystemExit, match="::error::"):
+        _next(FINAL_RELEASE, "", [], override=override)
+
+
+def test_an_unknown_kind_is_refused() -> None:
+    with pytest.raises(SystemExit, match="neither"):
+        _next("final", "v0.1.0", [])
+
+
+def test_tags_that_name_no_version_are_skipped() -> None:
+    assert known_versions(["v0.1.0", "latest", "", "0.2.0rc1"]) == [Version("0.1.0"), Version("0.2.0rc1")]
+
+
+def test_the_notes_of_a_release_candidate_start_at_the_one_before() -> None:
+    assert previous_tag(Version("0.2.0rc2"), ["v0.1.9", "v0.2.0rc1", "v0.2.0rc2"]) == "v0.2.0rc1"
+
+
+def test_the_notes_of_a_final_release_start_at_the_final_release_before() -> None:
+    assert previous_tag(Version("0.2.0"), ["v0.1.9", "v0.2.0rc1", "v0.2.0rc2"]) == "v0.1.9"
+
+
+def test_the_notes_of_a_new_series_start_at_the_final_release_before() -> None:
+    assert previous_tag(Version("0.3.0rc1"), ["v0.2.0rc2", "v0.2.0", "latest"]) == "v0.2.0"
+
+
+def test_the_notes_skip_test_builds() -> None:
+    assert previous_tag(Version("0.2.0rc1"), ["v0.1.0", "v0.2.0b3"]) == "v0.1.0"
+
+
+def test_the_first_release_notes_start_from_the_beginning() -> None:
+    assert previous_tag(Version("0.1.0"), []) is None
+    assert previous_tag(Version("0.2.0"), ["v0.2.0rc1", "v0.2.0rc2"]) is None
+
+
+def test_a_release_without_a_merged_pull_request_is_refused() -> None:
+    with pytest.raises(SystemExit, match="no pull request has been merged since v0.3.0"):
+        require_changes("v0.3.0", ["", "  "])
+
+
+def test_a_release_with_a_merged_pull_request_goes_ahead() -> None:
+    require_changes("v0.3.0", ["10"])

nilan_connect-0.2.0rc1/.github/scripts/test_workflows.py

@@ -0,0 +1,25 @@
+"""The repository's workflows."""
+
+from pathlib import Path
+
+import pytest
+
+WORKFLOWS = sorted((Path(__file__).parents[1] / "workflows").glob("*.yml"))
+
+BASH = "defaults:\n  run:\n    shell: bash\n"
+
+
+def test_the_workflows_are_found() -> None:
+    assert WORKFLOWS
+
+
+@pytest.mark.parametrize("workflow", WORKFLOWS, ids=[path.name for path in WORKFLOWS])
+def test_a_step_fails_when_a_command_piped_into_another_fails(workflow: Path) -> None:
+    """GitHub runs a step as `bash -eo pipefail` only when the shell is given; without one it
+    runs `bash -e`, where a failing command piped into another fails nothing."""
+    assert BASH in workflow.read_text(encoding="utf-8")
+
+@pytest.mark.parametrize("workflow", WORKFLOWS, ids=[path.name for path in WORKFLOWS])
+def test_no_step_pipes_into_a_command_that_stops_reading(workflow: Path) -> None:
+    """With pipefail, the command before `head` fails when head stops reading its output."""
+    assert "| head" not in workflow.read_text(encoding="utf-8")

nilan_connect-0.2.0rc1/.github/workflows/close-inactive-issues.yml

@@ -0,0 +1,30 @@
+name: Close inactive issues
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "30 1 * * *"
+
+permissions: {}
+
+# The shell given explicitly, so GitHub runs every step with pipefail.
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  close-issues:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/stale@v11
+        with:
+          days-before-issue-stale: 30
+          days-before-issue-close: 14
+          stale-issue-label: "stale"
+          stale-issue-message: "This issue is stale because it has been open for 30 days with no activity."
+          close-issue-message: "This issue was closed because it has been inactive for 14 days since being marked as stale."
+          days-before-pr-stale: -1
+          days-before-pr-close: -1

nilan_connect-0.2.0rc1/.github/workflows/release-drafter.yml

@@ -0,0 +1,44 @@
+name: Release Drafter
+
+# Keeps a draft release proposing the next version, from the labels of the pull requests merged
+# since the last final release. The draft is never published by hand.
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    types: [opened, reopened, synchronize]
+
+permissions: {}
+
+# The shell given explicitly, so GitHub runs every step with pipefail.
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  update_release_draft:
+    name: Update the release draft
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: read
+    steps:
+      - name: Draft the release
+        uses: release-drafter/release-drafter@v7
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+
+  autolabel_pr:
+    name: Label the pull request
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Apply labels
+        uses: release-drafter/release-drafter/autolabeler@v7
+        env:
+          GITHUB_TOKEN: ${{ github.token }}