CI(infra): Modern setup: doctests, mypy, cached poetry (#297)

- CI: Fix publishing docs only when changes detected - CI: Improve poetry dependency caching / CI speed - CI: Phase out .pre-commit-config.yaml - Testing: Add basic pytest configuration - Testing: Basic doctest support - Linting: Basic mypy static type checking
cihai · Aug 16, 2022 · 91aeb70 · 91aeb70
2 parents abb8580 + a8100d5
commit 91aeb70
Show file tree

Hide file tree

Showing 8 changed files with 102 additions and 103 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -34,58 +34,34 @@ jobs:
         if: steps.changes.outputs.docs == 'true' || steps.changes.outputs.root_docs == 'true' || steps.changes.outputs.python_files == 'true'
         run: echo "PUBLISH=$(echo true)" >> $GITHUB_ENV
 
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v3
-        with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: Get full Python version
-        id: full-python-version
-        shell: bash
-        run: echo ::set-output name=version::$(python -c "import sys; print('-'.join(str(v) for v in sys.version_info))")
-
       - name: Install poetry
-        run: |
-          curl -O -sSL https://install.python-poetry.org/install-poetry.py
-          python install-poetry.py -y --version 1.1.14
-          echo "PATH=${HOME}/.poetry/bin:${PATH}" >> $GITHUB_ENV
-          rm install-poetry.py
+        if: env.PUBLISH == 'true'
+        run: pipx install "poetry==1.1.14"
 
-      - name: Add ~/.local/bin to PATH
-        run: echo "$HOME/.local/bin" >> $GITHUB_PATH
-
-      - name: Get poetry cache paths from config
-        run: |
-          echo "poetry_virtualenvs_path=$(poetry config --list | sed -n 's/.*virtualenvs.path = .* # //p' | sed -e 's/^\"//' -e 's/\"$//')" >> $GITHUB_ENV
-          echo "poetry_virtualenvs_path=$(poetry config --list | sed -n 's/.*virtualenvs.path = .* # //p' | sed -e 's/^\"//' -e 's/\"$//')" >> $GITHUB_ENV
-
-      - name: Configure poetry
-        shell: bash
-        run: poetry config virtualenvs.in-project true
-
-      - name: Set up cache
-        uses: actions/cache@v3
-        id: cache
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        if: env.PUBLISH == 'true'
         with:
-          path: |
-            .venv
-            ${{ env.poetry_cache_dir }}
-            ${{ env.poetry_virtualenvs_path }}
-          key: venv-${{ runner.os }}-${{ steps.full-python-version.outputs.version }}-${{ hashFiles('**/poetry.lock') }}
-
-      - name: Ensure cache is healthy
-        if: steps.cache.outputs.cache-hit == 'true'
-        shell: bash
-        run: poetry run pip --version >/dev/null 2>&1 || rm -rf .venv
+          python-version: ${{ matrix.python-version }}
+          cache: 'poetry'
 
       - name: Install dependencies [w/ docs]
+        if: env.PUBLISH == 'true'
         run: poetry install --extras "docs lint"
 
+      - name: Print python versions
+        if: env.PUBLISH == 'true'
+        run: |
+          python -V
+          poetry run python -V
+
       - name: Build documentation
+        if: env.PUBLISH == 'true'
         run: |
           pushd docs; make SPHINXBUILD='poetry run sphinx-build' html; popd
 
       - name: Push documentation to S3
+        if: env.PUBLISH == 'true'
         uses: jakejarvis/s3-sync-action@v0.5.1
         with:
           args: --acl public-read --follow-symlinks --delete
@@ -97,6 +73,7 @@ jobs:
           SOURCE_DIR: "docs/_build/html" # optional: defaults to entire repository
 
       - name: Purge cache on Cloudflare
+        if: env.PUBLISH == 'true'
         uses: jakejarvis/cloudflare-purge-action@v0.3.0
         env:
           CLOUDFLARE_TOKEN: ${{ secrets.CLOUDFLARE_TOKEN }}

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -13,56 +13,29 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v3
-        with:
-          python-version: ${{ matrix.python-version }}
-
-      - name: Get full Python version
-        id: full-python-version
-        shell: bash
-        run: echo ::set-output name=version::$(python -c "import sys; print('-'.join(str(v) for v in sys.version_info))")
-
       - name: Install poetry
-        run: |
-          curl -O -sSL https://install.python-poetry.org/install-poetry.py
-          python install-poetry.py -y --version 1.1.14
-          echo "PATH=${HOME}/.poetry/bin:${PATH}" >> $GITHUB_ENV
-          rm install-poetry.py
-
-      - name: Add ~/.local/bin to PATH
-        run: echo "$HOME/.local/bin" >> $GITHUB_PATH
-
-      - name: Get poetry cache paths from config
-        run: |
-          echo "poetry_virtualenvs_path=$(poetry config --list | sed -n 's/.*virtualenvs.path = .* # //p' | sed -e 's/^\"//' -e 's/\"$//')" >> $GITHUB_ENV
-          echo "poetry_virtualenvs_path=$(poetry config --list | sed -n 's/.*virtualenvs.path = .* # //p' | sed -e 's/^\"//' -e 's/\"$//')" >> $GITHUB_ENV
-
-      - name: Configure poetry
-        shell: bash
-        run: poetry config virtualenvs.in-project true
+        run: pipx install "poetry==1.1.14"
 
-      - name: Set up cache
-        uses: actions/cache@v3
-        id: cache
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
         with:
-          path: |
-            .venv
-            ${{ env.poetry_cache_dir }}
-            ${{ env.poetry_virtualenvs_path }}
-          key: venv-${{ runner.os }}-${{ steps.full-python-version.outputs.version }}-${{ hashFiles('**/poetry.lock') }}
-
-      - name: Ensure cache is healthy
-        if: steps.cache.outputs.cache-hit == 'true'
-        shell: bash
-        run: poetry run pip --version >/dev/null 2>&1 || rm -rf .venv
+          python-version: ${{ matrix.python-version }}
+          cache: 'poetry'
 
       - name: Install dependencies
         run: poetry install -E "docs test coverage lint format"
 
+      - name: Print python versions
+        run: |
+          python -V
+          poetry run python -V
+
       - name: Lint with flake8
         run: poetry run flake8
 
+      - name: Lint with mypy
+        run: poetry run mypy .
+
       - name: Test with pytest
         run: poetry run py.test --cov=./ --cov-report=xml
 

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
diff --git a/CHANGES b/CHANGES
@@ -20,12 +20,25 @@ $ pip install --user --upgrade --pre unihan-db
 
 ### Development
 
+Infrastructure updates for static type checking and doctest examples.
+
 - Update poetry to 1.1
   - CI: Use poetry 1.1.7 and `install-poetry.py` installer (#274, #292)
   - Relock poetry.lock at 1.1 (w/ 1.1.7's fix)
-- Add `.pre-commit-config.yaml` for CI (#292)
 - Tests: `tmpdir` -> `tmp_path`
 - Run pyupgrade @ python 3.7
+- Initial [doctests] support added, via #297 
+
+  [doctests]: https://docs.python.org/3/library/doctest.html
+
+- Initial [mypy] validation, via #297
+
+  [mypy]: https://github.com/python/mypy
+
+- CI (tests, docs): Improve caching of python dependencies via
+  `action/setup-python`'s v3/4's new poetry caching, via #297
+
+- CI (docs): Skip if no `PUBLISH` condition triggered, via #297
 
 ### Documentation
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -2,23 +2,25 @@
 import inspect
 import os
 import sys
+import typing as t
 from pathlib import Path
 from posixpath import dirname, relpath
 
 import unihan_db
 
 # Get the project root dir, which is the parent dir of this
-cwd = Path.cwd()
+cwd = Path(__file__).parent
 project_root = cwd.parent
 
 sys.path.insert(0, str(project_root))
 sys.path.insert(0, str(cwd / "_ext"))
 
 # package data
-about = {}
-with open("../unihan_db/__about__.py") as fp:
+about: t.Dict[str, str] = {}
+with open(project_root / "unihan_db" / "__about__.py") as fp:
     exec(fp.read(), about)
 
+
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx_autodoc_typehints",
@@ -57,8 +59,8 @@
 html_css_files = ["css/custom.css"]
 html_favicon = "_static/favicon.ico"
 html_theme = "furo"
-html_theme_path = []
-html_theme_options = {
+html_theme_path: t.List[str] = []
+html_theme_options: t.Dict[str, t.Union[str, t.List[t.Dict[str, str]]]] = {
     "light_logo": "img/cihai.svg",
     "dark_logo": "img/cihai.svg",
     "footer_icons": [

diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -84,6 +84,8 @@ isort = "*"
 ### Lint ###
 flake8 = "*"
 mypy = "*"
+sqlalchemy-stubs = "^0.4"
+types-appdirs = "^1.4.3"
 
 [tool.poetry.extras]
 docs = [
@@ -102,7 +104,18 @@ docs = [
 test = ["pytest", "pytest-rerunfailures", "pytest-watcher"]
 coverage = ["codecov", "coverage", "pytest-cov"]
 format = ["black", "isort"]
-lint = ["flake8", "mypy"]
+lint = ["flake8", "mypy", "sqlalchemy-stubs", "types-appdirs"]
+
+[tool.mypy]
+plugins = [
+  "sqlmypy"
+]
+
+[[tool.mypy.overrides]]
+module = [
+  "unihan_etl"
+]
+ignore_missing_imports = true
 
 [build-system]
 requires = ["poetry_core>=1.0.0"]

diff --git a/setup.cfg b/setup.cfg
@@ -18,3 +18,11 @@ known_pytest = pytest,py
 known_first_party = unihan_db,cihai,cihai_cli,unihan_etl
 sections = FUTURE,STDLIB,PYTEST,THIRDPARTY,FIRSTPARTY,LOCALFOLDER
 line_length = 88
+
+[tool:pytest]
+addopts = --reruns=0 --tb=short --no-header --showlocals --doctest-modules
+doctest_optionflags = ELLIPSIS NORMALIZE_WHITESPACE
+testpaths =
+    unihan_db
+    tests
+    docs