Merge pull request #57 from DiamondLightSource/dev

Update to latest python3-pip-skeleton

Author: gilesknap

.devcontainer/devcontainer.json

@@ -1,4 +1,4 @@
-// For format details, see https://aka.ms/devcontainer.json
+// For format details, see https://containers.dev/implementors/json_reference/
 {
     "name": "Python 3 Developer Container",
     "build": {
@@ -12,24 +12,37 @@
     "remoteEnv": {
         "DISPLAY": "${localEnv:DISPLAY}"
     },
+    // Add the URLs of features you want added when the container is built.
+    "features": {
+        "ghcr.io/devcontainers/features/common-utils:1": {
+            "username": "none",
+            "upgradePackages": false
+        }
+    },
     // Set *default* container specific settings.json values on container create.
     "settings": {
         "python.defaultInterpreterPath": "/venv/bin/python"
     },
-    // Add the IDs of extensions you want installed when the container is created.
-    "extensions": [
-        "ms-python.python",
-        "ms-python.vscode-pylance"
-    ],
+    "customizations": {
+        "vscode": {
+            // Add the IDs of extensions you want installed when the container is created.
+            "extensions": [
+                "ms-python.python",
+                "tamasfe.even-better-toml",
+                "redhat.vscode-yaml",
+                "ryanluker.vscode-coverage-gutters"
+            ]
+        }
+    },
     // Make sure the files we are mapping into the container exist on the host
     "initializeCommand": "bash -c 'for i in $HOME/.inputrc; do [ -f $i ] || touch $i; done'",
     "runArgs": [
         "--net=host",
-        "--security-opt=label=type:container_runtime_t",
-        "-v=${localEnv:HOME}/.ssh:/root/.ssh",
-        "-v=${localEnv:HOME}/.inputrc:/root/.inputrc"
+        "--security-opt=label=type:container_runtime_t"
     ],
     "mounts": [
+        "source=${localEnv:HOME}/.ssh,target=/root/.ssh,type=bind",
+        "source=${localEnv:HOME}/.inputrc,target=/root/.inputrc,type=bind",
         // map in home directory - not strictly necessary but useful
         "source=${localEnv:HOME},target=${localEnv:HOME},type=bind,consistency=cached"
     ],

.github/workflows/code.yml

@@ -102,7 +102,7 @@ jobs:
           path: dist
 
       - name: Check for packaging errors
-        run: pipx run twine check dist/*
+        run: pipx run twine check --strict dist/*
 
       - name: Install python packages
         uses: ./.github/actions/install_requirements
@@ -165,6 +165,7 @@ jobs:
           push: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags') }}
           load: ${{ ! (github.event_name == 'push' && startsWith(github.ref, 'refs/tags')) }}
           tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
           context: .devcontainer
           # If you have a long docker build, uncomment the following to turn on caching
           # For short build times this makes it a little slower
@@ -179,6 +180,8 @@ jobs:
     needs: [lint, dist, test]
     if: ${{ github.event_name == 'push' && startsWith(github.ref, 'refs/tags') }}
     runs-on: ubuntu-latest
+    env:
+      HAS_PYPI_TOKEN: ${{ secrets.PYPI_TOKEN != '' }}
 
     steps:
       - uses: actions/download-artifact@v3
@@ -201,6 +204,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Publish to PyPI
+        if: ${{ env.HAS_PYPI_TOKEN }}
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           password: ${{ secrets.PYPI_TOKEN }}

.github/workflows/linkcheck.yml

@@ -8,11 +8,6 @@ on:
 
 jobs:
   docs:
-    strategy:
-      fail-fast: false
-      matrix:
-        python: ["3.10"]
-
     runs-on: ubuntu-latest
 
     steps:

.vscode/extensions.json

@@ -1,8 +1,9 @@
 {
     "recommendations": [
         "ms-vscode-remote.remote-containers",
-        "ms-python.vscode-pylance",
         "ms-python.python",
+        "tamasfe.even-better-toml",
+        "redhat.vscode-yaml",
         "ryanluker.vscode-coverage-gutters"
     ]
 }

docs/conf.py

@@ -4,9 +4,12 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+import sys
 from pathlib import Path
 from subprocess import check_output
 
+import requests
+
 import python3_pip_skeleton
 
 # -- General configuration ------------------------------------------------
@@ -126,8 +129,26 @@
 html_theme = "pydata_sphinx_theme"
 github_repo = project
 github_user = "DiamondLightSource"
+switcher_json = f"https://{github_user}.github.io/{github_repo}/switcher.json"
+switcher_exists = requests.get(switcher_json).ok
+if not switcher_exists:
+    print(
+        "*** Can't read version switcher, is GitHub pages enabled? \n"
+        "    Once Docs CI job has successfully run once, set the "
+        "Github pages source branch to be 'gh-pages' at:\n"
+        f"    https://github.com/{github_user}/{github_repo}/settings/pages",
+        file=sys.stderr,
+    )
 
 # Theme options for pydata_sphinx_theme
+# We don't check switcher because there are 3 possible states for a repo:
+# 1. New project, docs are not published so there is no switcher
+# 2. Existing project with latest skeleton, switcher exists and works
+# 3. Existing project with old skeleton that makes broken switcher,
+#    switcher exists but is broken
+# Point 3 makes checking switcher difficult, because the updated skeleton
+# will fix the switcher at the end of the docs workflow, but never gets a chance
+# to complete as the docs build warns and fails.
 html_theme_options = dict(
     logo=dict(
         text=project,
@@ -142,9 +163,10 @@
         )
     ],
     switcher=dict(
-        json_url=f"https://{github_user}.github.io/{github_repo}/switcher.json",
+        json_url=switcher_json,
         version_match=version,
     ),
+    check_switcher=False,
     navbar_end=["theme-switcher", "icon-links", "version-switcher"],
     external_links=[
         dict(

pyproject.toml

@@ -2,5 +2,111 @@
 requires = ["setuptools>=64", "setuptools_scm[toml]>=6.2", "wheel"]
 build-backend = "setuptools.build_meta"
 
+[project]
+name = "python3-pip-skeleton"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+]
+description = "One line description of your module"
+dependencies = [] # Add project dependencies here, e.g. ["click", "numpy"]
+dynamic = ["version"]
+license.file = "LICENSE"
+readme = "README.rst"
+requires-python = ">=3.8"
+
+[project.optional-dependencies]
+dev = [
+    "black",
+    "mypy",
+    "flake8-isort",
+    "Flake8-pyproject",
+    "pipdeptree",
+    "pre-commit",
+    "pydata-sphinx-theme>=0.12",
+    "pytest-cov",
+    "sphinx-autobuild",
+    "sphinx-copybutton",
+    "sphinx-design",
+    "toml",
+    "tox-direct",
+    "types-mock",
+    "types-toml",
+]
+
+[project.scripts]
+python3-pip-skeleton = "python3_pip_skeleton.__main__:main"
+
+[project.urls]
+GitHub = "https://github.com/DiamondLightSource/python3-pip-skeleton-cli"
+
+[[project.authors]] # Further authors may be added by duplicating this section
+email = "[email protected]"
+name = "Firstname Lastname"
+
+
 [tool.setuptools_scm]
 write_to = "src/python3_pip_skeleton/_version.py"
+
+[tool.mypy]
+ignore_missing_imports = true # Ignore missing stubs in imported modules
+
+[tool.isort]
+float_to_top = true
+profile = "black"
+
+[tool.flake8]
+extend-ignore = [
+    "E203", # See https://github.com/PyCQA/pycodestyle/issues/373
+    "F811", # support typing.overload decorator
+    "F722", # allow Annotated[typ, some_func("some string")]
+]
+max-line-length = 88 # Respect black's line length (default 88),
+exclude = [".tox", "venv"]
+
+
+[tool.pytest.ini_options]
+# Run pytest with all our checkers, and don't spam us with massive tracebacks on error
+addopts = """
+    --tb=native -vv --doctest-modules --doctest-glob="*.rst"
+    --cov=python3_pip_skeleton --cov-report term --cov-report xml:cov.xml
+    """
+# https://iscinumpy.gitlab.io/post/bound-version-constraints/#watch-for-warnings
+filterwarnings = "error"
+# Doctest python code in docs, python code in src docstrings, test functions in tests
+testpaths = "docs src tests"
+
+[tool.coverage.run]
+data_file = "/tmp/python3_pip_skeleton.coverage"
+
+[tool.coverage.paths]
+# Tests are run from installed location, map back to the src directory
+source = ["src", "**/site-packages/"]
+
+# tox must currently be configured via an embedded ini string
+# See: https://github.com/tox-dev/tox/issues/999
+[tool.tox]
+legacy_tox_ini = """
+[tox]
+skipsdist=True
+
+[testenv:{pre-commit,mypy,pytest,docs}]
+# Don't create a virtualenv for the command, requires tox-direct plugin
+direct = True
+passenv = *
+allowlist_externals =
+    pytest
+    pre-commit
+    mypy
+    sphinx-build
+    sphinx-autobuild
+commands =
+    pytest: pytest {posargs}
+    mypy: mypy src tests {posargs}
+    pre-commit: pre-commit run --all-files {posargs}
+    docs: sphinx-{posargs:build -EW --keep-going} -T docs build/html
+"""