Modern setup: doctests, mypy, cached poetry

.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 }}

.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
 

CHANGES

@@ -11,10 +11,23 @@
 
 ### Development
 
+Infrastructure updates for static type checking and doctest examples.
+
 - Update poetry to 1.1
   - CI: Use poetry 1.1.12 and `install-poetry.py` installer (#296 + #317)
   - Relock poetry.lock at 1.1 (w/ 1.1.7's fix)
-- Add `.pre-commit-config.yaml` (#317)
+- Initial [doctests] support added, via #323 
+
+  [doctests]: https://docs.python.org/3/library/doctest.html
+
+- Initial [mypy] validation, via #323
+
+  [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 #323
+
+- CI (docs): Skip if no `PUBLISH` condition triggered, via #323
 
 ## cihai 0.12.0 (2021-06-16)
 

cihai/conversion.py

@@ -142,7 +142,7 @@ def ucn_to_unicode(ucn):
 
 
 def euc_to_unicode(hexstr):
-    """
+    r"""
     Return EUC-CN (GB2312) hex to a Python unicode.
 
     Parameters
@@ -158,16 +158,16 @@ def euc_to_unicode(hexstr):
     --------
 
     >>> u'\u4e00'.encode('gb2312').decode('utf-8')
-    u'\u04bb'
+    '\u04bb'
 
-    >>> (b'\\x' + b'd2' + b'\\x' + b'bb').replace('\\x', '') \\
+    >>> (b'\\x' + b'd2' + b'\\x' + b'bb').replace('\\x', '') \  # doctest: +SKIP
     ... .decode('hex').decode('utf-8')
     u'\u04bb'
 
     Note: bytes don't have a ``.replace``:
 
-    >>> gb_enc = gb_enc.replace('\\x', '').decode('hex')
-    >>> gb_enc.decode('string_escape')  # Won't work with Python 3.x.
+    >>> gb_enc = gb_enc.replace('\\x', '').decode('hex')  # doctest: +SKIP
+    >>> gb_enc.decode('string_escape')  # Won't work with Python 3.x.  # doctest: +SKIP
     """
     hi = hexstr[0:2]
     lo = hexstr[2:4]

docs/conf.py

@@ -2,21 +2,22 @@
 import inspect
 import os
 import sys
+import typing as t
 from os.path import dirname, relpath
 from pathlib import Path
 
 import cihai
 
 # 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("../cihai/__about__.py") as fp:
+about: t.Dict[str, str] = {}
+with open(project_root / "cihai" / "__about__.py") as fp:
     exec(fp.read(), about)
 
 extensions = [
@@ -58,7 +59,8 @@
 html_css_files = ["css/custom.css"]
 html_favicon = "_static/favicon.ico"
 html_theme = "furo"
-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": [
@@ -74,7 +76,6 @@
         },
     ],
 }
-html_theme_path = []
 html_sidebars = {
     "**": [
         "sidebar/scroll-start.html",

pyproject.toml

@@ -90,6 +90,9 @@ isort = "*"
 ### Lint ###
 flake8 = "*"
 mypy = "*"
+sqlalchemy-stubs = "^0.4"
+types-appdirs = "^1.4.3"
+types-colorama = "^0.4.15"
 
 [tool.poetry.extras]
 "cli" = ["cihai-cli"]
@@ -110,7 +113,19 @@ 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", "types-colorama"]
+
+[tool.mypy]
+plugins = [
+  "sqlmypy"
+]
+
+[[tool.mypy.overrides]]
+module = [
+  "unihan_etl.*",
+  "kaptan"
+]
+ignore_missing_imports = true
 
 [build-system]
 requires = ["poetry_core>=1.0.0"]

setup.cfg

@@ -18,3 +18,11 @@ known_pytest = pytest,py
 known_first_party = cihai,unihan_etl
 sections = FUTURE,STDLIB,PYTEST,THIRDPARTY,FIRSTPARTY,LOCALFOLDER
 line_length = 88
+
+[tool:pytest]
+addopts = --tb=short --no-header --showlocals --doctest-modules
+doctest_optionflags = ELLIPSIS NORMALIZE_WHITESPACE
+testpaths =
+	cihai
+	tests
+	docs