main.yml

version: 2.1


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


executors:
  # Basically extending what the python orb's executor does:
  # - s/tag/version/
  # - more conservative interpreter version (usually)
  # - set common environment vars
  default:
    parameters:
      # This serves both as a 'local' variable and as as method for overriding
      # in certain test cells (eg, main test suite matrix)
      version:
        type: string
        default: "3.9"
    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:
      # Don't use the Python user site-packages; one is pre-populated by CI (at
      # least, as of 2025ish?) and will cause the "real" site-packages to omit
      # those packages, leading to subtle problems with subshells (like when
      # using sudo).
      # TODO: this can /probably/ go away once use of uv is stable?
      PYTHONNOUSERSITE: "1"
      # Not-in-CWD UV venv location (else all the tools have to be told to
      # ignore it, sigh)
      UV_PROJECT_ENVIRONMENT: "/home/circleci/venv"
      # So we get pretty output for some subcommands.
      TERM: screen-256color


commands:

  setup:
    steps:
      - checkout
      # Debuggery - which uv is this container on?
      - run: "which uv && uv --version"
      # General Debuggery
      - run: |
          whoami ; echo
          pwd ; echo
          env|sort
      # Explicitly generate uv venv w/ pip inside. (alas, uv sync doesn't
      # accept this arg [yet?])
      - run: |
          pwd
          uv venv --seed
      # 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:
          # pkg-manager + venv-cache /might/ work around not wanting uv.lock in
          # git?
          pkg-manager: "uv"
          venv-cache: false
          args: "--verbose"
          # For now, we expect most Pythons 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
          # Inform the caching layer where our venv is.
          # TODO: can we ref $UV_PROJECT_ENVIRONMENT in here? unlikely??
          # TODO: does circle have any sorta global-to-workflow variables we
          # could use instead?
          venv-path: '["/home/circleci/venv"]'
          # TODO: if 3.2.0+ is fixed re: ability to use local exec, then we can
          # use cache-folder-prefix here, depending on what the real default
          # value is (it's either empty string - meaning pwd - or /tmp/cache)
      # Safety check vs lockfile
      - run: "uv tree"
      # Set up for human interactive-like shell env re: venv path, etc,
      # Use multiline string for easier quoting; ensure venv comes /first/ in
      # case we override global commands like pip
      - run: |
          echo 'export PATH="$UV_PROJECT_ENVIRONMENT"/bin:"$PATH"' >> "$BASH_ENV"
      # Finally, safety check helping prove new PATH works: do we see the
      # seeded pip?
      - run: which -a pip

  # "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.9 --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

  downstream:
    description: Grab a downstream project and run its tests with ourselves installed
    parameters:
      git_url:
        type: string
      safety_check:
        type: string
      test_command:
        type: string
    steps:
      # NOTE: no orb/setup, we don't want to 'set up' the host project's own
      # env here! Doing so can confuse subprocesses within the downstream test
      # suites, and it's not actually necessary, all we need is the checkout
      # itself anyways.
      - checkout
      - run: |
          git clone --depth 1 << parameters.git_url >> downstream
          cd downstream
          uv venv --seed venv
          source venv/bin/activate
          # TODO: make configurable or just make uv-forward once fabric's
          # pyproject'd up
          pip install -r dev-requirements.txt
          pip install -e .
          pip install -e ..
          pip list
          << parameters.safety_check >>
          << parameters.test_command >>


jobs:

  test:
    parameters:
      # Python interpreter version
      version:
        type: string
      # Some cells in matrices may want semi-arbitrary extra packages
      # installed.
      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