lint python scripts in dev-tools

.github/actions/prepare-for-build/action.yml

@@ -2,11 +2,12 @@
 # for java, gradle, caches, etc.
 
 name: Prepare Lucene build
+description: Creates a shared setup for other workflows
 
 inputs:
    java-version:
      required: false
-     default: 23
+     default: "23"
      description: "The default JDK version to set up."
 
    java-distribution:

.github/workflows/run-checks-python.yml

@@ -0,0 +1,36 @@
+name: "Run checks: dev-tools/scripts (python)"
+
+on:
+  workflow_dispatch:
+
+  pull_request:
+    branches:
+      - 'main'
+      - 'branch_10x'
+    paths:
+      - '.github/workflows/run-checks-python.yml'
+      - 'dev-tools/scripts/**'
+
+  push:
+    branches:
+      - 'main'
+      - 'branch_10x'
+    paths:
+      - '.github/workflows/run-checks-python.yml'
+      - 'dev-tools/scripts/**'
+
+jobs:
+  lint:
+    timeout-minutes: 15
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12.6"
+
+      - name: Lint Python
+        run: "cd dev-tools/scripts && make"

dev-tools/scripts/Makefile

@@ -0,0 +1,68 @@
+# basic make safety: if error happens, delete output
+.DELETE_ON_ERROR:
+
+# explicitly declare shell used
+SHELL := /bin/bash
+
+# enforce that shell is picky
+.SHELLFLAGS := -norc -euo pipefail -c
+
+# don't litter up repo with bytecode
+export PYTHONDONTWRITEBYTECODE=true
+
+# don't self-check, don't ask questions
+PIP_INSTALL_ARGS=--disable-pip-version-check --no-input --upgrade
+
+# venv with dependencies in the standard location
+VENV=${PWD}/.venv
+
+# don't behave strangely if these files exist
+.PHONY: lint format reformat ruff pyright env clean
+
+# list of directories we check
+SOURCES=$(wildcard *.py)
+
+# check formatting, linting, and types
+# TODO: enable this when we're ready to reformat all code
+# lint: format ruff pyright
+lint: ruff pyright
+
+# check all formatting
+format: env
+	# validate imports: if this fails, please run "make reformat" and commit changes.
+	$(VENV)/bin/ruff check --select I $(SOURCES)
+	# validate formatting: if this fails, please run "make reformat" and commit changes.
+	$(VENV)/bin/ruff format --diff $(SOURCES)
+
+# reformat code to conventions
+reformat: env
+	# organize imports
+	$(VENV)/bin/ruff check --select I --fix $(SOURCES)
+	# reformat sources
+	$(VENV)/bin/ruff format $(SOURCES)
+
+# lints sources
+ruff: env
+	# validate sources with ruff linter
+	$(VENV)/bin/ruff check $(SOURCES)
+
+# checks types
+pyright: env
+	# type-check sources with basedpyright
+	$(VENV)/bin/basedpyright $(SOURCES)
+
+# rebuild venv if dependencies change
+env: $(VENV)/bin/activate
+$(VENV)/bin/activate: requirements.txt
+	# remove any existing venv
+	rm -rf $(VENV)
+	# create new venv
+	python3 -m venv $(VENV)
+	# install dependencies into venv
+	$(VENV)/bin/pip install $(PIP_INSTALL_ARGS) -r requirements.txt
+	# adjust timestamp for safety
+	touch $(VENV)/bin/activate
+
+# nuke venv
+clean:
+	rm -rf $(VENV)

dev-tools/scripts/pyproject.toml

@@ -0,0 +1,48 @@
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+# TODO: improve!
+# typeCheckingMode = "strict"
+typeCheckingMode = "basic"
+# TODO: we should fix these
+reportArgumentType = "none"
+reportAttributeAccessIssue = "none"
+reportCallIssue = "none"
+reportInvalidStringEscapeSequence = "none"
+reportOperatorIssue = "none"
+reportOptionalIterable = "none"
+reportOptionalMemberAccess = "none"
+reportOptionalSubscript = "none"
+reportUndefinedVariable = "none"
+
+[tool.ruff]
+line-length = 200
+indent-width = 2
+
+[tool.ruff.lint]
+# TODO: improve!
+# select = ["ALL"]
+
+# disabling/enabling of rules
+ignore = [
+  # we should fix these
+  "E401",  # multiple imports on one line
+  "E701",  # multiple statements on one line
+  "E711",  # comparison should be "is not None"
+  "E703",  # unnecessary semicolon
+  "E713",  # test for membership should be "not in"
+  "E714",  # test for object identity should be "is not"
+  "E722",  # do not use bare except
+  "E741",  # ambiguous variable name
+  "F401",  # unused import
+  "F403",  # unable to detect undefined names due to star imports
+  "F405",  # undefined name or defined from star imports
+  "F811",  # redefinition of unused
+  "F821",  # undefined name
+  "F841",  # local variable assigned but never used
+
+  # These rules are always disabled: conflict with the formatter
+  # don't enable! https://docs.astral.sh/ruff/formatter/#conflicting-lint-rules
+  "W191", "E111", "E114", "E117", "D206", "D300", "Q000", "Q001",
+  "Q002", "Q003", "COM812", "COM819", "ISC001", "ISC002", "E501",
+]

dev-tools/scripts/requirements.txt

@@ -5,4 +5,6 @@ holidays~=0.16
 ics~=0.7.2
 console-menu~=0.7.1
 PyGithub~=1.56
-jira~=3.4.1
+jira~=3.4.1
+basedpyright~=1.28.1
+ruff~=0.9.9