python-ci.yaml

version: 2.1
description: Tools for testing Python projects.

commands:

  run-with-coverage:
    parameters:
      python:
        type: string
        default: "python"
      command:
        type: string
    steps:
      - run:
          name: "Run Tests"
          command: |
            << parameters.python >> --version
            mkdir -p coverage_output
            export COVERAGE_FILE=coverage_output/.coverage.$CIRCLE_BUILD_NUM
            << parameters.command >>
      - persist_to_workspace:
          root: coverage_output
          paths:
            - .coverage.*

  pip-install:
    parameters:
      python:
        type: string
        default: "python"
      extra_packages:
        type: string
        default: ""
      editable:
        type: boolean
        default: false
      package:
        type: string
        default: "."
      extras:
        type: string
        default: ""
    steps:
      - run:
          name: "Install Project"
          command: "<< parameters.python >> -m pip install << parameters.extra_packages >> <<# parameters.editable >>-e <</ parameters.editable >><< parameters.package >><< parameters.extras >>"

  pip-run-tests:
    parameters:
      python:
        type: string
        default: "python"
      prepare:
        type: steps
        default: []
      command:
        type: string
        default: pytest --cov
      extra_packages:
        type: string
        default: ""
      extras:
        type: string
        default: "[test]"
    steps:
      - checkout
      - pip-install:
          python: << parameters.python >>
          editable: true
          extra_packages: << parameters.extra_packages >>
          extras: << parameters.extras >>
      - steps: << parameters.prepare >>
      - run-with-coverage:
          python: << parameters.python >>
          command: "<< parameters.python >> -m << parameters.command >>"

  check-package:
    parameters:
      python:
        type: string
        default: "python"
      package:
        type: string
      test:
        type: steps
      extra_packages:
        type: string
        default: ""
      expect_changelog:
        type: boolean
        default: true
      typed:
        type: boolean
        default: false
    steps:
      - attach_workspace:
          at: dist
      - run:
          name: "Shows Distributions"
          command: "ls -lah dist"
      - run:
          name: "Shows wheel contents"
          command: "unzip -l dist/*.whl"
      - run:
          name: "Shows sdist contents"
          command: "tar tzf dist/*.tar.gz"
      - when:
          condition: << parameters.typed >>
          steps:
          - run:
              name: "Check py.typed in wheel"
              command: "unzip -l dist/*.whl | grep << parameters.package >>/py.typed"
          - run:
              name: "Check py.typed in source dist"
              command: "tar tzf dist/*.tar.gz | grep << parameters.package >>/py.typed"
      - run:
          name: "Check LICENSE in wheel"
          command: "unzip -l dist/*.whl | grep LICENSE"
      - run:
          name: "Check LICENSE in source dist"
          command: "tar tzf dist/*.tar.gz | grep LICENSE"
      - when:
          condition: << parameters.expect_changelog >>
          steps:
            - run:
                name: "Check CHANGELOG in source dist"
                command: "tar tzf dist/*.tar.gz | grep CHANGELOG"
      - pip-install:
          package: "dist/*.whl"
          extra_packages: << parameters.extra_packages >>
      - steps: << parameters.test >>
      - run:
          name: "Uninstall wheel"
          command: "<< parameters.python >> -m pip uninstall -y << parameters.package >>"
      - pip-install:
          package: "dist/*.tar.gz"
          extra_packages: << parameters.extra_packages >>
      - steps: << parameters.test >>

jobs:

  pip-run-tests:
    parameters:
      image:
        type: string
      prepare:
        type: steps
        default: []
      command:
        type: string
        default: pytest --cov
      extra_packages:
        type: string
        default: ""
      extras:
        type: string
        default: "[test]"
      python:
        type: string
        default: "python"
    docker:
      - image: << parameters.image >>
    steps:
      - pip-run-tests:
          prepare: << parameters.prepare >>
          command: << parameters.command >>
          extra_packages: << parameters.extra_packages >>
          extras: << parameters.extras >>
          python: << parameters.python >>

  pip-docs:
    parameters:
      image:
        type: string
        default: "cimg/python:3.11"
      python:
        type: string
        default: "python"
      sourcedir:
        type: string
        default: "docs"
      outdir:
        type: string
        default: "build/sphinx/html"
    docker:
      - image: << parameters.image >>
    steps:
      - checkout
      - pip-install:
          editable: true
          extras: "[docs]"
      - run:
          name: "Build Docs"
          command: |
            << parameters.python >> -m sphinx -W --keep-going  << parameters.sourcedir >> << parameters.outdir >>
            << parameters.python >> -m docutils --strict  --strict README.rst README.html
      - store_artifacts:
          path: << parameters.outdir >>
          destination: docs

  pip-setuptools-build-package:
    parameters:
      image:
        type: string
        default: cimg/python:3.11
    docker:
      - image: << parameters.image >>
    steps:
      - checkout
      - pip-install:
          editable: true
          extra_packages: "setuptools-git build"
      - run:
          name: "Build Distributions"
          command: "python -m build"
      - persist_to_workspace:
          root: dist
          paths:
            - "*"
      - store_artifacts:
          path: dist
          destination: dist

  coverage:
    parameters:
      image:
        type: string
        default: cimg/python:3.11
    docker:
      - image: << parameters.image >>
    steps:
      - checkout
      - attach_workspace:
          at: coverage_output
      - run:
          name: "Check coverage"
          command: |
            pip install coverage
            coverage combine coverage_output/
            coverage report --show-missing --fail-under=100

  typing:
    parameters:
      packages:
        type: string
      image:
        type: string
        default: cimg/python:3.11
      python:
        type: string
        default: "python"
      extras:
        type: string
        default: "[test]"
    docker:
      - image: << parameters.image >>
    steps:
      - checkout
      - pip-install:
          python: << parameters.python >>
          editable: true
          extras: << parameters.extras >>
      - run: "<< parameters.python >> -m mypy << parameters.packages >>"

  check-package:
    parameters:
      image:
        type: string
        default: cimg/python:3.11
      python:
        type: string
        default: "python"
      package:
        type: string
      extra_packages:
        type: string
        default: ""
      typed:
        type: boolean
        default: false
    docker:
      - image: << parameters.image >>
    steps:
      - attach_workspace:
          at: dist
      - check-package:
          python: <<  parameters.python >>
          package: <<  parameters.package >>
          typed: << parameters.typed >>
          test:
            - run:
                name: "Import package"
                command: python -c "import << parameters.package >>"

  release:
    parameters:
      config:
        type: string
        default: pyproject.toml
      image:
        type: string
        default: cimg/python:3.11
    docker:
      - image: << parameters.image >>
    steps:
      - checkout
      - attach_workspace:
          at: dist
      - run:
          name: "Shows Distributions"
          command: "ls -lah dist"
      - run:
          name: "Release"
          command: |
            pip install carthorse
            carthorse --config << parameters.config >>