main.yml

version: 2.1


orbs:
  python: circleci/python@1.4.0
  codecov: codecov/codecov@3.2.4


executors:
  # Basically extending what the python orb's executor does:
  # - s/tag/version/
  # - default to 3.6, not 3.8 or w/e
  # - set common environment vars
  default:
    parameters:
      version:
        type: string
        default: "3.6"
    docker:
      - image: cimg/python:<< parameters.version >>
      # TODO: explicitly select 'resource_class: small' if credits ever become
      # too tight; seems like small uses 5 credits/min and medium, the default,
      # uses 10
    environment:
      TERM: screen-256color


commands:

  setup:
    steps:
      - checkout
      # This is worth using over a vanilla invocations task for 2 reasons:
      # - kinda hard to use invocations if it's not installed yet...
      # - the python orb is fully integrated with Circle's caching stuff
      - python/install-packages:
          # For now, we expect most Pythons 3.6-3.9+ to be happy with the
          # same pile of dependencies, so this lets us reuse the cache
          # across matrix cells.
          include-python-in-cache-key: false
          pre-install-steps:
            # This must occur here and not as a regular step; otherwise
            # cache loading stomps all over it and you get broken pip.
            - run: pip install pip==21.3.1
          pkg-manager: pip
          pip-dependency-file: dev-requirements.txt

  # "Wait around on errors" helper for circleci-cli local use
  debug:
    steps:
      - run:
          name: Debug hold...
          # Sleep for a very long time on failure, if opt-in env var set.
          # Necessary to keep circleci cli from nuking its containers :weary:
          # TODO: some non super nested way to get actual python version in use
          command: "test -z \"$DEBUG\" || (\n\n###### RUN vvvv LOCALLY LMAO\n# docker exec -it $(docker container ls --filter ancestor=cimg/python:3.6 --format \"{{.ID}}\") bash\n######\n\nsleep 18000)"
          when: on_fail
          no_output_timeout: 5h

  # Test+coverage+codecov, for test suites that need sudo
  # (allows running tests under sudo-capable user but performing final
  # report+upload as default user)
  sudo-coverage:
    steps:
      - run: inv ci.sudo-run 'inv coverage'
      - run: coverage xml
      - codecov/upload


jobs:

  test:
    parameters:
      # Python interpreter version
      version:
        type: string
      # Optional 'pip install' argstr for post-setup package tweaking,
      # eg 'some-dependency==some-older-version test-dep==better-for-circle'
      pip-overrides:
        type: string
        default: "" # evaluates falsey
      # For easier running eg integration tests w/ matrix-friendly setup
      task:
        type: string
        default: "test"
    executor:
      name: default
      version: "<< parameters.version >>"
    steps:
      - setup
      - when:
          condition: "<< parameters.pip-overrides >>"
          steps:
            # NOTE: eschewing python orb install-packages here, overkill/buggy
            - run: "pip install << parameters.pip-overrides >>"
      - run: "inv << parameters.task >>"
      - debug

  # Regular tests+coverage+codecov upload
  coverage:
    executor: default
    steps:
      - setup
      - run: inv coverage
      - run: coverage xml
      - codecov/upload
      - debug

  lint:
    executor: default
    steps:
      - setup
      - run: flake8
      - debug

  format:
    executor: default
    steps:
      - setup
      - run: inv blacken --check --diff
      - debug

  test-release:
    executor: default
    steps:
      - setup
      - run: inv release.all --dry-run
      - debug

  docs:
    executor: default
    parameters:
      task:
        type: string
        default: "sites"  # build www+docs
    steps:
      - setup
      - run: "inv << parameters.task >>"
      - debug