initial commit

.config/dictionary.txt

@@ -0,0 +1,16 @@
+PYSCAFFOLD
+REQPASS
+Sbarnea
+Sorin
+TOXENV
+autofix
+autoupdate
+capsys
+codespell
+commitlint
+coveragerc
+dists
+notest
+pycontribs
+pypa
+setuptools

.config/requirements.txt

@@ -0,0 +1 @@
+rich

.config/test-requirements.txt

@@ -0,0 +1 @@
+pytest

.coveragerc

@@ -0,0 +1,28 @@
+# .coveragerc to control coverage.py
+[run]
+branch = True
+source = gh_pre
+# omit = bad_file.py
+
+[paths]
+source =
+    src/
+    */site-packages/
+
+[report]
+# Regexes for lines to exclude from consideration
+exclude_lines =
+    # Have to re-enable the standard pragma
+    pragma: no cover
+
+    # Don't complain about missing debug-only code:
+    def __repr__
+    if self\.debug
+
+    # Don't complain if tests don't hit defensive assertion code:
+    raise AssertionError
+    raise NotImplementedError
+
+    # Don't complain if non-runnable code isn't run:
+    if 0:
+    if __name__ == .__main__.:

.github/dependabot.yml

@@ -0,0 +1,22 @@
+---
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /.config/
+    schedule:
+      day: sunday
+      interval: monthly
+    labels:
+      - dependabot-deps-updates
+      - skip-changelog
+    groups:
+      dependencies:
+        patterns:
+          - "*"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: monthly
+    labels:
+      - "dependencies"
+      - "skip-changelog"

.github/release-drafter.yml

@@ -0,0 +1,3 @@
+---
+# see https://github.com/ansible/team-devtools
+_extends: ansible/team-devtools

.github/workflows/ack.yml

@@ -0,0 +1,10 @@
+---
+# See https://github.com/ansible/devtools/blob/main/.github/workflows/ack.yml
+name: ack
+"on":
+  pull_request_target:
+    types: [opened, labeled, unlabeled, synchronize]
+
+jobs:
+  ack:
+    uses: ansible/team-devtools/.github/workflows/ack.yml@main

.github/workflows/push.yml

@@ -0,0 +1,13 @@
+---
+# See https://github.com/ansible/devtools/blob/main/.github/workflows/push.yml
+name: push
+"on":
+  push:
+    branches:
+      - main
+      - "releases/**"
+      - "stable/**"
+
+jobs:
+  ack:
+    uses: ansible/team-devtools/.github/workflows/push.yml@main

.github/workflows/release.yml

@@ -0,0 +1,57 @@
+---
+name: release
+
+"on":
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  # https://github.com/marketplace/actions/actions-tagger
+  actions-tagger:
+    needs: pypi # do not move the mobile tag until we publish
+    runs-on: windows-latest
+    permissions:
+      # Give the default GITHUB_TOKEN write permission.
+      # https://github.blog/changelog/2023-02-02-github-actions-updating-the-default-github_token-permissions-to-read-only/
+      contents: write
+    steps:
+      - uses: Actions-R-Us/actions-tagger@latest
+        with:
+          token: "${{ github.token }}"
+          # Do not activate latest tag because it seems to affect RTD builds
+          # publish_latest_tag: true
+  pypi:
+    name: Publish to PyPI registry
+    environment: release
+    runs-on: ubuntu-22.04
+    permissions:
+      id-token: write
+
+    env:
+      FORCE_COLOR: 1
+      PY_COLORS: 1
+      TOXENV: pkg
+
+    steps:
+      - name: Switch to using Python 3.10 by default
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install tox
+        run: python3 -m pip install --user "tox>=4.0.0"
+
+      - name: Check out src from Git
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # needed by setuptools-scm
+          submodules: true
+
+      - name: Build dists
+        run: python -m tox
+
+      - name: Publish to pypi.org
+        if: >- # "create" workflows run separately from "push" & "pull_request"
+          github.event_name == 'release'
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/tox.yml

@@ -0,0 +1,142 @@
+---
+name: tox
+
+on:
+  push: # only publishes pushes to the main branch to TestPyPI
+    branches: # any integration branch but not tag
+      - "main"
+  pull_request:
+    branches:
+      - "main"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+env:
+  FORCE_COLOR: 1 # tox, pytest, ansible-lint
+  PY_COLORS: 1
+
+jobs:
+  prepare:
+    name: prepare
+    runs-on: ubuntu-22.04
+    outputs:
+      matrix: ${{ steps.generate_matrix.outputs.matrix }}
+    steps:
+      - name: Determine matrix
+        id: generate_matrix
+        uses: coactions/dynamic-matrix@v1
+        with:
+          min_python: "3.10"
+          max_python: "3.12"
+          other_names: |
+            lint
+            pkg
+          platforms: linux,macos
+  build:
+    name: ${{ matrix.name }}
+    runs-on: ${{ matrix.os || 'ubuntu-22.04' }}
+    needs:
+      - prepare
+    defaults:
+      run:
+        shell: ${{ matrix.shell || 'bash'}}
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.prepare.outputs.matrix) }}
+      # max-parallel: 5
+      # The matrix testing goal is to cover the *most likely* environments
+      # which are expected to be used by users in production. Avoid adding a
+      # combination unless there are good reasons to test it, like having
+      # proof that we failed to catch a bug by not running it. Using
+      # distribution should be preferred instead of custom builds.
+    env:
+      # Number of expected test passes, safety measure for accidental skip of
+      # tests. Update value if you add/remove tests.
+      PYTEST_REQPASS: 850
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # needed by setuptools-scm
+          submodules: true
+
+      - name: Set pre-commit cache
+        uses: actions/cache@v3
+        if: ${{ matrix.passed_name == 'lint' }}
+        with:
+          path: |
+            ~/.cache/pre-commit
+          key: pre-commit-${{ matrix.name || matrix.passed_name }}-${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: Set up Python ${{ matrix.python_version || '3.10' }}
+        if: "!contains(matrix.shell, 'wsl')"
+        uses: actions/setup-python@v5
+        with:
+          cache: pip
+          python-version: ${{ matrix.python_version || '3.10' }}
+
+      # - name: Run ./tools/test-setup.sh
+      #   run: ./tools/test-setup.sh
+
+      - name: Install tox
+        run: |
+          python3 -m pip install --upgrade pip
+          python3 -m pip install --upgrade "tox>=4.0.0"
+
+      - name: Log installed dists
+        run: python3 -m pip freeze --all
+
+      - name: Initialize tox envs ${{ matrix.passed_name }}
+        run: python3 -m tox --notest --skip-missing-interpreters false -vv -e ${{ matrix.passed_name }}
+        timeout-minutes: 5 # average is under 1, but macos can be over 3
+
+      # sequential run improves browsing experience (almost no speed impact)
+      - name: tox -e ${{ matrix.passed_name }}
+        run: python3 -m tox -e ${{ matrix.passed_name }}
+
+      - name: Combine coverage data
+        if: ${{ startsWith(matrix.passed_name, 'py') }}
+        # produce a single .coverage file at repo root
+        run: tox -e coverage
+
+      - name: Upload coverage data
+        if: ${{ startsWith(matrix.passed_name, 'py') }}
+        uses: codecov/codecov-action@v3
+        with:
+          name: ${{ matrix.passed_name }}
+          token: ${{ secrets.CODECOV_TOKEN }}
+          verbose: true # optional (default = false)
+
+      - name: Archive logs
+        uses: actions/upload-artifact@v3
+        with:
+          name: logs.zip
+          path: .tox/**/log/
+
+      - name: Report failure if git reports dirty status
+        run: |
+          if [[ -n $(git status -s) ]]; then
+            # shellcheck disable=SC2016
+            echo -n '::error file=git-status::'
+            printf '### Failed as git reported modified and/or untracked files\n```\n%s\n```\n' "$(git status -s)" | tee -a "$GITHUB_STEP_SUMMARY"
+            exit 99
+          fi
+        # https://github.com/actions/toolkit/issues/193
+  check: # This job does nothing and is only used for the branch protection
+    if: always()
+    permissions:
+      pull-requests: write
+    needs:
+      - build
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Decide whether the needed jobs succeeded or failed
+        uses: re-actors/alls-green@release/v1
+        with:
+          jobs: ${{ toJSON(needs) }}
+
+      - name: Check out src from Git
+        uses: actions/checkout@v4

.gitignore

@@ -0,0 +1,54 @@
+# Temporary and binary files
+*~
+*.py[cod]
+*.so
+*.cfg
+!.isort.cfg
+!setup.cfg
+*.orig
+*.log
+*.pot
+__pycache__/*
+.cache/*
+.*.swp
+*/.ipynb_checkpoints/*
+.DS_Store
+
+# Project files
+.ropeproject
+.project
+.pydevproject
+.settings
+.idea
+.vscode
+tags
+
+# Package files
+*.egg
+*.eggs/
+.installed.cfg
+*.egg-info
+
+# Unittest and coverage
+htmlcov/*
+.coverage
+.coverage.*
+.tox
+junit*.xml
+coverage.xml
+.pytest_cache/
+
+# Build and docs folder/files
+build/*
+dist/*
+sdist/*
+docs/api/*
+docs/_rst/*
+docs/_build/*
+cover/*
+MANIFEST
+
+# Per-project virtualenvs
+.venv*/
+.conda*/
+.python-version