Add/update dev scripts and Github workflow

.github/workflows/ci.yaml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+    tags: ['v*.*.*']
+
+jobs:
+  test:
+    name: Test
+    uses: daniil-berg/reusable-workflows/.github/workflows/python-test.yaml@v0.2.1
+    with:
+      versions: '["3.9", "3.10", "3.11"]'
+      unittest-command: 'scripts/test.sh'
+      coverage-command: 'scripts/cov.sh'
+      unittest-requirements: "-e '.[dev]'"
+      typecheck-command: 'scripts/typecheck.sh'
+      typecheck-requirements: '-Ur requirements/dev.txt'
+      typecheck-all-versions: true
+      lint-command: 'scripts/lint.sh'
+      lint-requirements: '-Ur requirements/dev.txt'
+
+  release:
+    name: Release
+    if: ${{ github.ref_type == 'tag' }}
+    needs: test
+    uses: daniil-berg/reusable-workflows/.github/workflows/python-release.yaml@v0.2.1
+    with:
+      git-ref: ${{ github.ref_name }}
+    secrets:
+      release-token: ${{ secrets.TOKEN_GITHUB_CREATE_RELEASE }}
+      publish-token: ${{ secrets.TOKEN_PYPI_PROJECT }}
+    permissions:
+      contents: write

mkdocs.yaml

@@ -26,13 +26,23 @@ extra_css:
 
 plugins:
   - search
-  - mkdocstrings
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            line_length: 80
+            show_source: false
+            show_root_toc_entry: false
+            separate_signature: true
+            show_signature_annotations: true
 
 markdown_extensions:
   - admonition
   - codehilite
   - extra
   - pymdownx.superfences
+  - toc:
+      permalink: true
 
 nav:
   - Home: index.md

pyproject.toml

@@ -9,14 +9,14 @@ build-backend = "setuptools.build_meta"
 name = "${REPO_NAME}"
 description = "${REPO_DESCRIPTION}"
 authors = [
-    { name = "${REPO_OWNER_TITLE}", email = "mail@PLACEHOLDER.to" },
+    { name = "${REPO_OWNER_TITLE}", email = ... },
 ]
 maintainers = [
-    { name = "${REPO_OWNER_TITLE}", email = "mail@PLACEHOLDER.to" },
+    { name = "${REPO_OWNER_TITLE}", email = ... },
 ]
 requires-python = ">=3.9, <4.0"
 keywords = [
-
+    ...
 ]
 license = { text = "Apache Software License Version 2.0" }
 classifiers = [
@@ -30,6 +30,7 @@ classifiers = [
 #    "Intended Audience :: Developers",
 #    "Framework :: AsyncIO",
 #    "Topic :: Internet",
+    ...
 ]
 dynamic = [
     "dependencies",
@@ -39,32 +40,34 @@ dynamic = [
 
 [project.optional-dependencies]
 full = [
-
+    ...
 ]
 dev = [
-    "black",
+    "black==23.3.0",
-    "build",
+    "build==0.10.0",
-    "coverage[toml]",
+    "coverage[toml]==7.2.7",
-    "flake8",
+    "isort==5.12.0",
-    "mkdocs-material",
+    "mkdocs-material==9.1.17",
-    "mkdocstrings[python]",
+    "mkdocstrings[python]==0.22.0",
-    "mypy",
+    "mypy==1.4.0",
+    "ruff==0.0.275",
 ]
 
 [project.urls]
-repository = "https://github.com/${REPO_OWNER_LOWER}/${REPO_NAME_LOWER}"
+"Repository" = "https://github.com/${REPO_OWNER_LOWER}/${REPO_NAME_LOWER}"
-bug_tracker = "https://github.com/${REPO_OWNER_LOWER}/${REPO_NAME_LOWER}/issues"
+"Issue Tracker" = "https://github.com/${REPO_OWNER_LOWER}/${REPO_NAME_LOWER}/issues"
-documentation = "http://${REPO_OWNER_LOWER}.github.io/${REPO_NAME_LOWER}"
+"Documentation" = "http://${REPO_OWNER_LOWER}.github.io/${REPO_NAME_LOWER}"
 
 [tool.setuptools.dynamic]
 dependencies = { file = "requirements/common.txt" }
-readme = { file = ["README.md"] }
+readme = { file = ["README.md"], content-type = "text/markdown" }
-version = {attr = "PACKAGE_NAME_PLACEHOLDER.__version__"}
+version = {attr = ..."${REPO_NAME}.__version__"}
 
-#########
+#########################
-# Mypy: #
+# Static type checking: #
 
 [tool.mypy]
+cache_dir = ".cache/mypy"
 files = [
     "src/",
     "tests/",
@@ -73,13 +76,14 @@ warn_unused_configs = true
 strict = true
 show_error_codes = true
 plugins = [
-
+...
 ]
 
-#############
+#######################
-# Coverage: #
+# Unit test coverage: #
 
 [tool.coverage.run]
+data_file = ".cache/coverage"
 source = [
     "src/",
 ]
@@ -100,3 +104,45 @@ exclude_lines = [
 omit = [
     "tests/*",
 ]
+
+###############################
+# Linting and style checking: #
+
+[tool.ruff]
+cache-dir = ".cache/ruff"
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "D",    # pydocstyle
+    "C",    # flake8-comprehensions
+    "B",    # flake8-bugbear
+    "PL",   # pylint
+    "RUF",  # ruff-specific
+]
+ignore = [
+    "E501",  # Line too long -> handled by black
+    "D203",  # 1 blank line required before class docstring -> D211 is better
+    "D212",  # Multi-line docstring summary should start at the first line -> ugly, D212 is better
+    "D401",  # First line of docstring should be in imperative mood -> no, it shouldn't
+    "D407",  # Missing dashed underline after section -> different docstring style
+]
+
+[tool.ruff.per-file-ignores]
+"src/**/__init__.py" = [
+    "D104",  # Missing docstring in public package
+    "F401",  # {...} imported but unused
+]
+"tests/*.py" = [
+    "D100",  # Missing docstring in public module
+    "D101",  # Missing docstring in public class
+    "D102",  # Missing docstring in public method
+    "D104",  # Missing docstring in public package
+]
+
+###################
+# Import sorting: #
+
+[tool.isort]
+profile = "black"
+extra_standard_library = ["typing_extensions"]

requirements/dev.txt

@@ -1,8 +1,9 @@
 -r common.txt
-black
+black==23.3.0
-build
+build==0.10.0
-coverage[toml]
+coverage[toml]==7.2.7
-flake8
+isort==5.12.0
-mkdocs-material
+mkdocs-material==9.1.17
-mkdocstrings[python]
+mkdocstrings[python]==0.22.0
-mypy
+mypy==1.4.0
+ruff==0.0.275

scripts/ci.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Runs full CI pipeline (test, typecheck, lint).
+
+typeset scripts_dir="$(dirname $(realpath $0))"
+
+source "${scripts_dir}/util.sh"
+
+"${scripts_dir}/test.sh"
+"${scripts_dir}/typecheck.sh"
+"${scripts_dir}/lint.sh"
+
+echo -e "${background_black}${bold_green}✅ 🎉 All checks passed!${color_reset}"

scripts/cov.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Runs unit tests.
+# If successful, prints only the coverage percentage.
+# If an error occurs, prints the entire unit tests progress output.
+
+source "$(dirname $(realpath $0))/util.sh"
+
+coverage erase
+run_and_capture coverage run
+coverage report | awk '$1 == "TOTAL" {print $NF; exit}'

scripts/lint.sh

@@ -1,16 +1,17 @@
 #!/usr/bin/env bash
-# Runs type checker and linters.
+# Runs various linters.
 
-# Ensure that we return to the current working directory
+source "$(dirname $(realpath $0))/util.sh"
-# and exit the script immediately in case of an error:
-trap "cd $(realpath ${PWD}); exit 1" ERR
-# Change into project root directory:
-cd "$(dirname $(dirname $(realpath $0)))"
-
-echo 'Performing type checks...'
-mypy
-echo
 
 echo 'Linting source and test files...'
-flake8 src/ tests/
+
-echo -e 'No issues found.'
+echo '  isort - consistent imports'
+isort src/ tests/ --check-only
+
+echo '  ruff - extensive linting'
+ruff src/ tests/
+
+echo '  black - consistent style'
+run_and_capture black src/ tests/ --check
+
+echo -e "${bold_green}No issues found${color_reset}\n"

scripts/test.sh

@@ -1,17 +1,12 @@
 #!/usr/bin/env bash
-# Runs unit tests and prints only coverage percentage, if successful.
+# Runs unit tests and reports coverage percentage.
-# If an error occurs, prints the entire unit tests progress output.
 
-# Ensure that we return to the current working directory in case of an error:
+source "$(dirname $(realpath $0))/util.sh"
-trap "cd $(realpath ${PWD})" ERR
-# Change into project root directory:
-cd "$(dirname $(dirname $(realpath $0)))"
 
-coverage erase
+echo 'Running unit tests...'
-# Capture the test progression in a variable:
+coverage run
-typeset progress
+typeset percentage
-progress=$(coverage run 2>&1)
+typeset color
-# If tests failed or produced errors, write progress/messages to stderr and exit:
+percentage="$(coverage report | awk '$1 == "TOTAL" {print $NF; exit}')"
-[[ $? -eq 0 ]] || { >&2 echo "${progress}"; exit 1; }
+[[ $percentage == "100%" ]] && color="${bold_green}" || color="${yellow}"
-# Otherwise extract the total coverage percentage from the produced report and write it to stdout:
+echo -e "${color}${percentage} coverage${color_reset}\n"
-coverage report | awk '$1 == "TOTAL" {print $NF; exit}'

scripts/typecheck.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# Runs type checker.
+
+source "$(dirname $(realpath $0))/util.sh"
+
+echo 'Performing type checks...'
+mypy
+echo

scripts/util.sh

@@ -0,0 +1,20 @@
+run_and_capture() {
+  # Captures stderr of any command passed to it
+  # and releases it only if the command exits with a non-zero code.
+  typeset output
+  output=$($@ 2>&1)
+  typeset exit_status=$?
+  [[ $exit_status == 0 ]] || >&2 echo "${output}"
+  return $exit_status
+}
+
+# Ensure that we return to the current working directory
+# and exit the script immediately in case of an error:
+trap "cd $(realpath ${PWD}); exit 1" ERR
+# Change into project root directory:
+cd "$(dirname $(dirname $(realpath $0)))"
+
+typeset background_black='\033[40m'
+typeset bold_green='\033[1;92m'
+typeset yellow='\033[0;33m'
+typeset color_reset='\033[0m'