Merge pull request #22 from epics-containers/dev

Update to use skeleton module

.gitattributes

@@ -1 +1 @@
-*/_version_git.py export-subst
+src/*/_version_git.py export-subst

.github/workflows/code.yml

@@ -3,87 +3,92 @@ name: Code CI
 on:
   push:
     branches:
+      # Restricting to these branches and tags stops duplicate jobs on internal
+      # PRs but stops CI running on internal branches without a PR. Delete the
+      # next 5 lines to restore the original behaviour
       - master
       - main
     tags:
       - "*"
   pull_request:
+  schedule:
+    # Run every Monday at 8am to check latest versions of dependencies
+    - cron: '0 8 * * MON'
 
 jobs:
-  build:
-    strategy:
-      fail-fast: false
-      matrix:
-        os: ["ubuntu-latest"]  # can add windows-latest, macos-latest
-        python: ["3.7", "3.8", "3.9"]
-        pipenv: ["skip-lock"]  # --${flag} will be passed to pipenv command
-
-        include:
-          # Add an extra Python3.7 runner to publish wheels and use the lockfile
-          - os: "ubuntu-latest"
-            python: "3.7"
-            pipenv: "deploy"
-            publish: true
-
-    name: build/${{ matrix.python }}/${{ matrix.os }}/${{ matrix.pipenv }}
-    runs-on: ${{ matrix.os }}
-
+  lint:
+    runs-on: "ubuntu-latest"
     steps:
-      - name: Checkout Source
-        uses: actions/checkout@v2
+      - name: Run black, flake8, mypy
+        uses: dls-controls/pipenv-run-action@v1
         with:
-          # require history to get back to last tag for version number of branches
-          fetch-depth: 0
+          pipenv-run: lint
 
-      - name: Set up Python ${{ matrix.python }}
-        uses: actions/setup-python@v2
+  wheel:
+    runs-on: "ubuntu-latest"
+    steps:
+      - uses: actions/checkout@v2
         with:
-          python-version: ${{ matrix.python }}
+          fetch-depth: 0
 
       - name: Create Sdist and Wheel
-        if: matrix.publish
         # Set SOURCE_DATE_EPOCH from git commit for reproducible build
         # https://reproducible-builds.org/
         # Set group writable and umask to do the same to match inside DLS
         run: |
           chmod -R g+w .
           umask 0002
           SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct) pipx run build --sdist --wheel
+
       - name: Test cli works from the installed wheel
-        if: matrix.publish
         # Can remove the repository reference after https://github.com/pypa/pipx/pull/733
         run: pipx run --spec dist/*.whl ${GITHUB_REPOSITORY##*/} --version
 
-      - name: Use a non-editable install to test the installed wheel
-        if: matrix.pipenv == 'skip-lock'
-        run: sed -i 's/editable *= *true/editable = false/' Pipfile
+      - name: Upload Wheel and Sdist as artifacts
+        uses: actions/upload-artifact@v2
+        with:
+          name: dist
+          path: dist/*
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ["ubuntu-latest"]  # can add windows-latest, macos-latest
+        python: ["3.7", "3.8", "3.9"]
+        pipenv: ["skip-lock"]
 
-      - name: Install Python Dependencies
-        run: |
-          pip install pipenv
-          pipenv install --dev --${{ matrix.pipenv }} --python $(python -c 'import sys; print(sys.executable)') && pipenv graph
-      - name: Run Tests
-        # https://github.com/pytest-dev/pytest/issues/2042
-        run: PY_IGNORE_IMPORTMISMATCH=1 pipenv run tests
+        include:
+          # Add an extra Python3.7 runner to use the lockfile
+          - os: "ubuntu-latest"
+            python: "3.7"
+            pipenv: "deploy"
+
+    runs-on: ${{ matrix.os }}
+    env:
+      # https://github.com/pytest-dev/pytest/issues/2042
+      PY_IGNORE_IMPORTMISMATCH: "1"
+
+    steps:
+      - name: Setup repo and test
+        uses: dls-controls/pipenv-run-action@v1
+        with:
+          python-version: ${{ matrix.python }}
+          pipenv-install: --dev --${{ matrix.pipenv }}
+          allow-editable-installs: ${{ matrix.pipenv == 'deploy' }}
+          pipenv-run: tests
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v2
         with:
-          name: ${{ toJSON(matrix) }}
+          name: ${{ matrix.python }}/${{ matrix.os }}/${{ matrix.pipenv }}
           files: cov.xml
 
-      - name: Upload Wheel and Sdist as artifacts
-        if: matrix.publish
-        uses: actions/upload-artifact@v2
-        with:
-          name: dist
-          path: dist/*
-
   release:
-    needs: [build]
+    needs: [lint, wheel, test]
     runs-on: ubuntu-latest
     # upload to PyPI and make a release on every tag
-    if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
     steps:
       - uses: actions/download-artifact@v2
         with:
@@ -93,10 +98,10 @@ jobs:
       - name: Github Release
         # We pin to the SHA, not the tag, for security reasons.
         # https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
-        uses: softprops/action-gh-release@2d72d869af3bf23602f9593a1e3fd739b80ac1eb  # v0.1.12
+        uses: softprops/action-gh-release@1e07f4398721186383de40550babbdf2b84acfc5  # v0.1.14
         with:
           files: dist/*
-          body: See [Changelog](CHANGELOG.rst) for more details
+          generate_release_notes: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 

.github/workflows/docs.yml

@@ -11,39 +11,29 @@ on:
   pull_request:
 
 jobs:
-  build:
-    name: "Docs CI"
+  docs:
     runs-on: ubuntu-latest
 
     steps:
-      - name: Checkout Source
-        uses: actions/checkout@v2
-        with:
-          # require history to get back to last tag for version number of branches
-          fetch-depth: 0
-
-      - name: Set up Python
-        uses: actions/setup-python@v2
-        with:
-          python-version: "3.7"
+      - name: Avoid git conflicts when tag and branch pushed at same time
+        if: startsWith(github.ref, 'refs/tags')
+        run: sleep 60
 
       - name: Install Packages
+        # Can delete this if you don't use graphviz in your docs
         run: sudo apt-get install graphviz
 
-      - name: Install Python Dependencies
-        run: |
-          pip install pipenv
-          pipenv install --dev --deploy --python $(which python) && pipenv graph
-      - name: Build Docs
-        run: pipenv run docs
+      - name: Build docs
+        uses: dls-controls/pipenv-run-action@v1
+        with:
+          pipenv-run: docs
 
       - name: Move to versioned directory
         # e.g. master or 0.1.2
         run: mv build/html ".github/pages/${GITHUB_REF##*/}"
 
-      - name: Avoid git conflicts when tag and branch pushed at same time
-        if: startsWith(github.ref, 'refs/tags')
-        run: sleep 60
+      - name: Write versions.txt
+        run: pipenv run sphinx_rtd_theme_github_versions .github/pages
 
       - name: Publish Docs to gh-pages
         if: github.event_name == 'push'

.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v2.3.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-merge-conflict
+
+  - repo: local
+    hooks:
+      - id: black
+        name: Run black
+        stages: [commit]
+        language: system
+        entry: pipenv run black --check --diff
+        types: [python]
+
+      - id: flake8
+        name: Run flake8
+        stages: [commit]
+        language: system
+        entry: pipenv run flake8
+        types: [python]
+        exclude: setup.py
+
+      - id: mypy
+        name: Run mypy
+        stages: [commit]
+        language: system
+        entry: pipenv run mypy src tests
+        pass_filenames: false

.vscode/launch.json

@@ -7,11 +7,17 @@
         {
             "name": "Debug Unit Test",
             "type": "python",
-            "request": "test",
+            "request": "launch",
             "justMyCode": false,
+            "program": "${file}",
+            "purpose": ["debug-test"],
+            "console": "integratedTerminal",
             "env": {
+                // The default config in setup.cfg's "[tool:pytest]" adds coverage.
+                // Cannot have coverage and debugging at the same time.
+                // https://github.com/microsoft/vscode-python/issues/693
                 "PYTEST_ADDOPTS": "--no-cov"
-            }
+            },
         }
     ]
 }

.vscode/settings.json

@@ -2,10 +2,10 @@
     "editor.defaultFormatter": "ms-python.python",
     "python.linting.pylintEnabled": false,
     "python.linting.flake8Enabled": true,
+    "python.linting.mypyEnabled": true,
     "python.linting.enabled": true,
     "python.testing.pytestArgs": [],
     "python.testing.unittestEnabled": false,
-    "python.testing.nosetestsEnabled": false,
     "python.testing.pytestEnabled": true,
     "python.formatting.provider": "black",
     "python.languageServer": "Pylance",

CONTRIBUTING.rst

@@ -2,13 +2,12 @@ Contributing
 ============
 
 Contributions and issues are most welcome! All issues and pull requests are
-handled through github on the `epics-containers repository`_. Also, please check for
-any existing issues before filing a new one. If you have a great idea but it
-involves big changes, please file a ticket before making a pull request! We
-want to make sure you don't spend your time coding something that might not fit
-the scope of the project.
+handled through GitHub_. Also, please check for any existing issues before
+filing a new one. If you have a great idea but it involves big changes, please
+file a ticket before making a pull request! We want to make sure you don't spend
+your time coding something that might not fit the scope of the project.
 
-.. _epics-containers repository: https://github.com/epics-containers/ibek/issues
+.. _GitHub: https://github.com/epics-containers/ibek/issues
 
 Running the tests
 -----------------
@@ -34,14 +33,21 @@ The code in this repository conforms to standards set by the following tools:
 - isort_ for import ordering
 - mypy_ for static type checking
 
+These checks will be run by pre-commit_. You can either choose to run these
+tests on all files tracked by git::
+
+    $ pipenv run lint
+
+Or you can install a pre-commit hook that will run each time you do a ``git
+commit`` on just the files that have changed::
+
+    $ pipenv run pre-commit install
+
 .. _black: https://github.com/psf/black
 .. _flake8: http://flake8.pycqa.org/en/latest/
 .. _isort: https://github.com/timothycrosley/isort
 .. _mypy: https://github.com/python/mypy
-
-These tests will be run on code when running ``pipenv run tests`` and also
-automatically at check in. Please read the tool documentation for details
-on how to fix the errors it reports.
+.. _pre-commit: https://pre-commit.com/
 
 Documentation
 -------------
@@ -60,20 +66,37 @@ Docs follow the underlining convention::
     Heading 3
     ~~~~~~~~~
 
-
 You can build the docs from the project directory by running::
 
     $ pipenv run docs
     $ firefox build/html/index.html
 
-
 Release Process
 ---------------
 
 To make a new release, please follow this checklist:
 
 - Choose a new PEP440 compliant release number
-- Add a release note in CHANGELOG.rst
 - Git tag the version
-- Push to github and the actions will make a release on pypi
+- Push to GitHub and the actions will make a release on pypi
 - Push to internal gitlab and do a dls-release.py of the tag
+- Check and edit for clarity the autogenerated GitHub release_
+
+.. _release: https://epics-containers.github.io/ibek/releases
+
+Updating the tools
+------------------
+
+This module is merged with the dls-python3-skeleton_. This is a generic
+Python project structure which provides a means to keep tools and
+techniques in sync between multiple Python projects. To update to the
+latest version of the skeleton, run::
+
+    $ git pull https://github.com/dls-controls/dls-python3-skeleton skeleton
+
+Any merge conflicts will indicate an area where something has changed that
+conflicts with the setup of the current module. Check the `closed pull requests
+<https://github.com/dls-controls/dls-python3-skeleton/pulls?q=is%3Apr+is%3Aclosed>`_
+of the skeleton module for more details.
+
+.. _dls-python3-skeleton: https://dls-controls.github.io/dls-python3-skeleton

Pipfile

@@ -4,15 +4,14 @@ url = "https://pypi.org/simple"
 verify_ssl = true
 
 [dev-packages]
-# All other package requirements from setup.cfg
-ibek = {editable = true, path = ".", extras = ["dev"]}
+ibek = {editable = true, extras = ["dev"], path = "."}
 
 [packages]
-# All other package requirements from setup.cfg
 ibek = {editable = true, path = "."}
 
 [scripts]
-tests = "python -m pytest"
+lint = "pre-commit run --all-files --show-diff-on-failure --color=always -v"
+tests = "pytest"
 docs = "sphinx-build -EWT --keep-going docs build/html"
 # Delete any files that git ignore hides from us
 gitclean = "git clean -fdX"