Set up CI/CD with auto semantic versioning and PyPI publish

Author: akshatnerella

.github/scripts/bump_version.py

@@ -0,0 +1,99 @@
+import os
+import re
+import subprocess
+from pathlib import Path
+
+
+def run(*args: str) -> str:
+    return subprocess.check_output(args, text=True).strip()
+
+
+def write_output(key: str, value: str) -> None:
+    output_path = os.getenv("GITHUB_OUTPUT")
+    if not output_path:
+        return
+    with open(output_path, "a", encoding="utf-8") as fh:
+        fh.write(f"{key}={value}\n")
+
+
+def latest_version_tag() -> str | None:
+    tags = run("git", "tag", "--list", "v*", "--sort=-v:refname").splitlines()
+    for tag in tags:
+        if re.fullmatch(r"v\d+\.\d+\.\d+", tag):
+            return tag
+    return None
+
+
+def read_setup_version() -> str:
+    setup_text = Path("setup.py").read_text(encoding="utf-8")
+    match = re.search(r"version\s*=\s*['\"](\d+\.\d+\.\d+)['\"]", setup_text)
+    if not match:
+        raise RuntimeError("Could not parse current version from setup.py")
+    return match.group(1)
+
+
+def commit_log_since(tag: str | None) -> str:
+    if tag:
+        return run("git", "log", "--format=%s%n%b", f"{tag}..HEAD")
+    return run("git", "log", "--format=%s%n%b")
+
+
+def commits_since(tag: str | None) -> int:
+    if tag:
+        return int(run("git", "rev-list", "--count", f"{tag}..HEAD"))
+    return int(run("git", "rev-list", "--count", "HEAD"))
+
+
+def determine_bump(log_text: str) -> str:
+    if re.search(r"BREAKING CHANGE|!:", log_text, re.IGNORECASE):
+        return "major"
+    if re.search(r"(?mi)^feat(\(.+\))?:", log_text):
+        return "minor"
+    return "patch"
+
+
+def bump_version(current: str, bump: str) -> str:
+    major, minor, patch = [int(part) for part in current.split(".")]
+    if bump == "major":
+        return f"{major + 1}.0.0"
+    if bump == "minor":
+        return f"{major}.{minor + 1}.0"
+    return f"{major}.{minor}.{patch + 1}"
+
+
+def update_setup_py(new_version: str) -> bool:
+    setup_path = Path("setup.py")
+    setup_text = setup_path.read_text(encoding="utf-8")
+    new_text, replacements = re.subn(
+        r"version\s*=\s*['\"]\d+\.\d+\.\d+['\"]",
+        f"version='{new_version}'",
+        setup_text,
+        count=1,
+    )
+    if replacements == 0:
+        raise RuntimeError("Could not find version assignment in setup.py")
+    if new_text == setup_text:
+        return False
+    setup_path.write_text(new_text, encoding="utf-8")
+    return True
+
+
+def main() -> None:
+    tag = latest_version_tag()
+    current_version = tag[1:] if tag else read_setup_version()
+
+    if commits_since(tag) == 0:
+        write_output("released", "false")
+        return
+
+    bump_kind = determine_bump(commit_log_since(tag)) if tag else "patch"
+    next_version = bump_version(current_version, bump_kind)
+    changed = update_setup_py(next_version)
+
+    write_output("version", next_version)
+    write_output("released", "true" if changed else "false")
+    print(f"Bumped {current_version} -> {next_version} ({bump_kind})")
+
+
+if __name__ == "__main__":
+    main()

.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .
+          python -m pip install pytest
+
+      - name: Run tests
+        run: pytest -q tests

.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+
+jobs:
+  publish:
+    if: github.event_name == 'workflow_dispatch' || startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .
+          python -m pip install build twine pytest
+
+      - name: Run tests
+        run: pytest -q tests
+
+      - name: Build distribution
+        run: python -m build
+
+      - name: Check PyPI token
+        if: ${{ secrets.PYPI_API_TOKEN == '' }}
+        run: |
+          echo "Missing required secret: PYPI_API_TOKEN"
+          exit 1
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: python -m twine upload --skip-existing dist/*

.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Auto Version Release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    if: github.actor != 'github-actions[bot]' && !contains(github.event.head_commit.message, 'chore(release):')
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .
+          python -m pip install pytest
+
+      - name: Run tests
+        run: pytest -q tests
+
+      - name: Bump version
+        id: bump
+        run: python .github/scripts/bump_version.py
+
+      - name: Commit version and create tag
+        if: steps.bump.outputs.released == 'true'
+        env:
+          NEW_VERSION: ${{ steps.bump.outputs.version }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add setup.py
+          git commit -m "chore(release): v${NEW_VERSION} [skip ci]"
+          git tag "v${NEW_VERSION}"
+          git push origin HEAD:main --follow-tags

.gitignore

@@ -1,3 +1,8 @@
 .venv
 venv/
 __pycache__
+.pytest_cache/
+build/
+dist/
+*.egg-info/
+pytest-cache-files-*/

README.md

@@ -102,6 +102,23 @@ ladder.run(visualize=True)
 
 We welcome contributions to add new features, fix bugs, and improve documentation. To contribute, fork the repository, make your changes, and open a pull request.
 
+## CI/CD (Auto Publish to PyPI)
+
+This repository is configured with GitHub Actions:
+- `CI`: runs tests on pull requests and pushes to `main`.
+- `Auto Version Release`: on each merge/push to `main`, it auto-bumps version in `setup.py`, creates a git tag (for example `v0.1.1`), and pushes it.
+- `Publish to PyPI`: builds and uploads the package when a release tag is pushed.
+
+One-time setup required:
+1. Create a PyPI API token (`__token__`) for your PyPI project.
+2. In GitHub: `Settings -> Secrets and variables -> Actions`, add a repository secret named `PYPI_API_TOKEN`.
+3. Use conventional commit messages in merged commits/PR titles for semantic bumps:
+   - `feat:` -> minor bump
+   - `fix:` (or anything else) -> patch bump
+   - `BREAKING CHANGE` or `feat!:` / `fix!:` -> major bump
+
+If the version already exists on PyPI, publish is skipped safely.
+
 ## License
 
 This project is licensed under the MIT License.

pyladdersim/components.py

@@ -62,11 +62,20 @@ def __init__(self, name, delay):
         self.ET = 0  # Elapsed Time in seconds
         self.Q = False  # Q (done output)
 
+    @property
+    def state(self):
+        """Compatibility alias used by existing examples/tests."""
+        return self.Q
+
     def reset(self):
         """Resets the timer's internal state."""
         self.ET = 0
         self.Q = False
 
+    def update(self, IN):
+        """Compatibility alias that mirrors evaluate(IN)."""
+        return self.evaluate(IN)
+
     def evaluate(self, IN):
         """This method should be overridden in subclasses."""
         pass