Initial commit

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[{*.yaml,*.yml}]
+indent_size = 2

.github/workflows/readme_example.yaml

@@ -0,0 +1,54 @@
+# This workflow exists for several purposes:
+#
+# * Ensure that the example in the README is functional.
+# * Ensure that the desired YAML formatting is enforced.
+# * Ensure that the example action versions are maintained.
+#
+# Update PRs submitted by Dependabot should trigger pre-commit.ci,
+# which will synchronize changes to this file into the README.
+#
+
+name: "📘 README example"
+
+on:
+  pull_request:
+  push:
+    branches:
+      - "main"
+      - "releases"
+  schedule:
+    - "27 19 * * *"
+
+jobs:
+  readme_example:
+    runs-on: ubuntu-latest
+    steps:
+      # START_README_EXAMPLE_BLOCK
+      - uses: "actions/setup-python@v4"
+        with:
+          python-versions: |
+            3.8
+            3.9
+            3.10
+            3.11
+            3.12
+
+      - uses: "kurtmckee/detect-pythons@main"
+
+      - uses: "actions/cache@v3"
+        id: "restore-cache"
+        with:
+          path: |
+            .tox/
+            .venv/
+          key: "${{ hashFiles('.python-identifiers') }}"
+
+      - name: "Create a virtual environment"
+        if: "steps.restore-cache.outputs.cache-hit == false"
+        run: |
+          python -m venv .venv
+          .venv/bin/python -m pip install tox
+
+      - name: "Run the test suite against all installed Pythons"
+        run: ".venv/bin/tox"
+      # END_README_EXAMPLE_BLOCK

.github/workflows/test.yaml

@@ -0,0 +1,34 @@
+name: "Test"
+
+on:
+  push:
+    branches:
+      - "main"
+
+jobs:
+  test-linux:
+    name: "Test on ${{ matrix.config.os-name }}"
+    runs-on: "${{ matrix.config.runner }}"
+    strategy:
+      matrix:
+        config:
+          - os-name: "Linux"
+            runner: "ubuntu-latest"
+            test-label: "ci-test-linux"
+          - os-name: "macOS"
+            runner: "macos-latest"
+            test-label: "ci-test-macos"
+          - os-name: "Windows"
+            runner: "windows-latest"
+            test-label: "ci-test-windows"
+      fail-fast: false
+
+    steps:
+      - name: "Use it!"
+        id: "detector"
+        uses: "kurtmckee/detect-pythons@main"
+
+      - name: "Print it!"
+        shell: "bash"
+        run: |
+          echo '${{ steps.detector.outputs.python-identifiers }}'

.gitignore

@@ -0,0 +1 @@
+__pycache__

.pre-commit-config.yaml

@@ -0,0 +1,71 @@
+ci:
+  autoupdate_schedule: "monthly"
+
+repos:
+  - repo: "https://github.com/pre-commit/pre-commit-hooks"
+    rev: "v4.5.0"
+    hooks:
+      - id: "trailing-whitespace"
+      - id: "end-of-file-fixer"
+      - id: "check-yaml"
+      - id: "check-added-large-files"
+
+  - repo: "https://github.com/psf/black-pre-commit-mirror"
+    rev: "23.9.1"
+    hooks:
+      - id: "black"
+        language_version: "python3.8"
+
+  - repo: "https://github.com/pycqa/isort"
+    rev: "5.12.0"
+    hooks:
+      - id: "isort"
+
+  - repo: "https://github.com/pycqa/flake8"
+    rev: "6.1.0"
+    hooks:
+      - id: "flake8"
+
+  - repo: "https://github.com/editorconfig-checker/editorconfig-checker.python"
+    rev: "2.7.3"
+    hooks:
+      - id: "editorconfig-checker"
+        # The README contains YAML syntax that is indented with 2 spaces.
+        # The .editorconfig file will continue to require 4 spaces,
+        # and this pre-commit hook will ignore the README.
+        exclude: "README.rst"
+
+  - repo: "local"
+    hooks:
+      - id: "sync-identify-code"
+        name: "Synchronize identify.py source code into 'detector.sh'"
+        language: "python"
+        entry: "python src/detect_pythons/sync_identify_code.py"
+        files: "^src/detect_pythons/identify.py$"
+
+  - repo: "https://github.com/shellcheck-py/shellcheck-py"
+    rev: "v0.9.0.6"
+    hooks:
+      - id: "shellcheck"
+        args:
+          - "--shell=bash"
+
+  - repo: "local"
+    hooks:
+      - id: "sync-detector-code"
+        name: "Synchronize detector source code into 'action.yml'"
+        language: "python"
+        entry: "python src/detect_pythons/sync_detector_code.py"
+        files: "^src/detect_pythons/detector.*$"
+      - id: "sync-readme-example"
+        name: "Synchronize a functional example into the README"
+        language: "python"
+        entry: "python src/detect_pythons/sync_readme_example.py"
+        always_run: true
+        pass_filenames: false
+
+  - repo: "https://github.com/python-jsonschema/check-jsonschema"
+    rev: "0.27.0"
+    hooks:
+      - id: "check-github-workflows"
+      - id: "check-dependabot"

LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2023 Kurt McKee <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.rst

@@ -0,0 +1,59 @@
+Detect Python interpreters
+##########################
+
+*Robust cache-busting based on Python implementations, versions, and architectures.*
+
+----
+
+Purpose
+=======
+
+If you're caching Python virtual environments, or tox environments,
+or even build artifacts that depend on a particular Python version,
+you need robust cache busting to ensure that your caches are invalidated
+when a new Python version is released.
+
+``detect-pythons`` provides that much-needed cache busting.
+
+
+Usage
+=====
+
+The following example demonstrates how ``detect-pythons`` can be used
+when caching a Python virtual environment stored in ``.venv/``
+and tox test environments stored in ``.tox/``.
+
+
+..  START_EXAMPLE_YAML_BLOCK
+..  code-block::
+
+    - uses: "actions/setup-python@v4"
+      with:
+        python-versions: |
+          3.8
+          3.9
+          3.10
+          3.11
+          3.12
+
+    - uses: "kurtmckee/detect-pythons@main"
+
+    - uses: "actions/cache@v3"
+      id: "restore-cache"
+      with:
+        path: |
+          .tox/
+          .venv/
+        key: "${{ hashFiles('.python-identifiers') }}"
+
+    - name: "Create a virtual environment"
+      if: "steps.restore-cache.outputs.cache-hit == false"
+      run: |
+        python -m venv .venv
+        .venv/bin/python -m pip install tox
+
+    - name: "Run the test suite against all installed Pythons"
+      run: ".venv/bin/tox"
+..  END_EXAMPLE_YAML_BLOCK
+
+other stuff goes here

TODO.rst

@@ -0,0 +1,5 @@
+*   Expand README
+*   Create ``releases`` branch for tagging and such
+*   Add pre-commit hook to check README against latest tagged SHA
+*   Add test suite that can run locally
+*   Add test suite that verifies expected outputs in CI