PYTHON-4975 Use justfile as the task runner

Author: blink1073

.evergreen/scripts/ensure-hatch.sh

@@ -5,55 +5,57 @@ set -eu
 HERE=$(dirname ${BASH_SOURCE:-$0})
 pushd "$(dirname "$(dirname $HERE)")" > /dev/null
 
-# Ensure hatch is available.
-if [ ! -x "$(command -v hatch)" ]; then
-  # Install a virtual env with "hatch"
-  # Ensure there is a python venv.
-  . .evergreen/utils.sh
-
-  if [ -z "${PYTHON_BINARY:-}" ]; then
-      PYTHON_BINARY=$(find_python3)
-  fi
-  VENV_DIR=.venv
-  if [ ! -d $VENV_DIR ]; then
-    echo "Creating virtual environment..."
-    createvirtualenv "$PYTHON_BINARY" .venv
-    echo "Creating virtual environment... done."
-  fi
-  if [ -f $VENV_DIR/Scripts/activate ]; then
-    . $VENV_DIR/Scripts/activate
-  else
-    . $VENV_DIR/bin/activate
-  fi
+# Ensure hatch is available locally.
+VENV_DIR=.venv
+if [ -f $VENV_DIR/Scripts/hatch ]; then
+  return 0
+fi
+if [ -f $VENV_DIR/bin/hatch ]; then
+  return 0
+fi
+
+# Install a virtual env with "hatch"
+# Ensure there is a python venv.
+. .evergreen/utils.sh
 
-  python --version
-
-  echo "Installing hatch..."
-  python -m pip install -U pip
-  python -m pip install hatch || {
-    # Install rust and try again.
-    CARGO_HOME=${CARGO_HOME:-${DRIVERS_TOOLS}/.cargo}
-    # Handle paths on Windows.
-    if [ "Windows_NT" = "${OS:-}" ]; then # Magic variable in cygwin
-      CARGO_HOME=$(cygpath -m $CARGO_HOME)
-    fi
-    export RUSTUP_HOME="${CARGO_HOME}/.rustup"
-    ${DRIVERS_TOOLS}/.evergreen/install-rust.sh
-    source "${CARGO_HOME}/env"
-    python -m pip install hatch
-  }
-  # Ensure hatch does not write to user or global locations.
-  touch hatch_config.toml
-  HATCH_CONFIG=$(pwd)/hatch_config.toml
+if [ -z "${PYTHON_BINARY:-}" ]; then
+    PYTHON_BINARY=$(find_python3)
+fi
+
+if [ ! -d $VENV_DIR ]; then
+  echo "Creating virtual environment..."
+  createvirtualenv "$PYTHON_BINARY" .venv
+  echo "Creating virtual environment... done."
+fi
+if [ -f $VENV_DIR/Scripts/activate ]; then
+  . $VENV_DIR/Scripts/activate
+else
+  . $VENV_DIR/bin/activate
+fi
+
+echo "Installing hatch..."
+python -m pip install -U pip
+python -m pip install hatch || {
+  # Install rust and try again.
+  CARGO_HOME=${CARGO_HOME:-${DRIVERS_TOOLS}/.cargo}
+  # Handle paths on Windows.
   if [ "Windows_NT" = "${OS:-}" ]; then # Magic variable in cygwin
-      HATCH_CONFIG=$(cygpath -m "$HATCH_CONFIG")
+    CARGO_HOME=$(cygpath -m $CARGO_HOME)
   fi
-  export HATCH_CONFIG
-  hatch config restore
-  hatch config set dirs.data "$(pwd)/.hatch/data"
-  hatch config set dirs.cache "$(pwd)/.hatch/cache"
-
-  echo "Installing hatch... done."
+  export RUSTUP_HOME="${CARGO_HOME}/.rustup"
+  ${DRIVERS_TOOLS}/.evergreen/install-rust.sh
+  source "${CARGO_HOME}/env"
+  python -m pip install hatch
+}
+# Ensure hatch does not write to user or global locations.
+touch hatch_config.toml
+HATCH_CONFIG=$(pwd)/hatch_config.toml
+if [ "Windows_NT" = "${OS:-}" ]; then # Magic variable in cygwin
+    HATCH_CONFIG=$(cygpath -m "$HATCH_CONFIG")
 fi
-hatch --version
-popd > /dev/null
+export HATCH_CONFIG
+hatch config restore
+hatch config set dirs.data "$(pwd)/.hatch/data"
+hatch config set dirs.cache "$(pwd)/.hatch/cache"
+
+echo "Installing hatch... done."

.github/workflows/test-python.yml

@@ -29,18 +29,18 @@ jobs:
           cache-dependency-path: 'pyproject.toml'
       - name: Install Python dependencies
         run: |
-          python -m pip install -U pip hatch
+          python -m pip install -U pip hatch rust-just
       - name: Run linters
         run: |
-          hatch run lint:run-manual
+          just-manual
       - name: Run compilation
         run: |
           export PYMONGO_C_EXT_MUST_BUILD=1
           pip install -v -e .
           python tools/fail_if_no_c.py
       - name: Run typecheck
         run: |
-          hatch run typing:check
+          just typing
       - run: |
           sudo apt-get install -y cppcheck
       - run: |
@@ -75,7 +75,7 @@ jobs:
           allow-prereleases: true
       - name: Install dependencies
         run: |
-          pip install -U pip
+          pip install -U pip rust-just
           if [[ "${{ matrix.python-version }}" == "3.13" ]]; then
             pip install --pre cffi setuptools
             pip install --no-build-isolation hatch
@@ -95,7 +95,7 @@ jobs:
           if [[ "${{ matrix.python-version }}" == "3.13t" ]]; then
             pytest -v --durations=5 --maxfail=10
           else
-            hatch run test:test
+            just test
           fi
 
   doctest:
@@ -113,14 +113,14 @@ jobs:
           cache-dependency-path: 'pyproject.toml'
       - name: Install dependencies
         run: |
-          pip install -U hatch pip
+          pip install -U hatch pip rust-just
       - name: Start MongoDB
         uses: supercharge/[email protected]
         with:
           mongodb-version: '8.0.0-rc4'
       - name: Run tests
         run: |
-          hatch run doctest:test
+          just doctest
 
   docs:
     name: Docs Checks
@@ -137,10 +137,10 @@ jobs:
           python-version: '3.9'
       - name: Install dependencies
         run: |
-          pip install -U pip hatch
+          pip install -U pip hatch rust-just
       - name: Build docs
         run: |
-          hatch run doc:build
+          just docs
 
   linkcheck:
     name: Link Check
@@ -160,7 +160,7 @@ jobs:
           pip install -U pip hatch
       - name: Build docs
         run: |
-          hatch run doc:linkcheck
+          just docs-linkcheck
 
   typing:
     name: Typing Tests
@@ -179,10 +179,10 @@ jobs:
           cache-dependency-path: 'pyproject.toml'
       - name: Install dependencies
         run: |
-          pip install -U pip hatch
+          pip install -U pip hatch rust-just
       - name: Run typecheck
         run: |
-          hatch run typing:check
+          just typing
 
   make_sdist:
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -28,9 +28,10 @@ including 4 space indents and 79 character line limits.
 
 -   Avoid backward breaking changes if at all possible.
 -   Write inline documentation for new classes and methods.
--   We use [hatch](https://hatch.pypa.io/dev/) for our script runner and packaging tool.
+-   We use [hatch](https://hatch.pypa.io/dev/) for python environment management and packaging.
+-   We use [just](https://just.systems/man/en/) as our task runner.
 -   Write tests and make sure they pass (make sure you have a mongod
-    running on the default port, then execute `hatch run test:test` from the cmd
+    running on the default port, then execute `just test` from the cmd
     line to run the test suite).
 -   Add yourself to doc/contributors.rst `:)`
 
@@ -148,17 +149,17 @@ To run `pre-commit` manually, run:
 pre-commit run --all-files
 ```
 
-To run a manual hook like `mypy` manually, run:
+To run a manual hook like `ruff` manually, run:
 
 ```bash
-pre-commit run --all-files --hook-stage manual mypy
+pre-commit run --all-files --hook-stage manual ruff
 ```
 
-Typically we use `hatch` to run the linters, e.g.
+Typically we use `just` to run the linters, e.g.
 
 ```bash
-hatch run typing:check-mypy
-hatch run lint:build-manual
+just typing-mypy
+just run lint-manual
 ```
 
 ## Documentation
@@ -176,13 +177,13 @@ documentation including narrative docs, and the [Sphinx docstring format](https:
 You can build the documentation locally by running:
 
 ```bash
-hatch run doc:build
+just docs-build
 ```
 
 When updating docs, it can be helpful to run the live docs server as:
 
 ```bash
-hatch run doc:serve
+just docs-serve
 ```
 
 Browse to the link provided, and then as you make changes to docstrings or narrative docs,
@@ -192,13 +193,13 @@ the pages will re-render and the browser will automatically refresh.
 ## Running Tests Locally
 
 -   Ensure you have started the appropriate Mongo Server(s).
--   Run `pip install hatch` to use `hatch` for testing or run
-    `pip install -e ".[test]"` to run `pytest` directly.
--   Run `hatch run test:test` or `pytest` to run all of the tests.
+-   Run `just install` to set up `hatch` in a local virtual environment, or you can manually
+    create a virtual environment and run `pytest` directly.
+-   Run `just test` or `pytest` to run all of the tests.
 -   Append `test/<mod_name>.py::<class_name>::<test_name>` to run
     specific tests. You can omit the `<test_name>` to test a full class
     and the `<class_name>` to test a full module. For example:
-    `hatch run test:test -- test/test_change_stream.py::TestUnifiedChangeStreamsErrors::test_change_stream_errors_on_ElectionInProgress`.
+    `just test test/test_change_stream.py::TestUnifiedChangeStreamsErrors::test_change_stream_errors_on_ElectionInProgress`.
 -   Use the `-k` argument to select tests by pattern.
 
 ## Running Load Balancer Tests Locally
@@ -211,15 +212,15 @@ the pages will re-render and the browser will automatically refresh.
 -   Start the load balancer using:
     `MONGODB_URI='mongodb://localhost:27017,localhost:27018/' $PWD/drivers-evergreen-tools/.evergreen/run-load-balancer.sh start`.
 -   Run the tests from the `pymongo` checkout directory using:
-    `TEST_LOADBALANCER=1 hatch run test:test-eg`.
+    `TEST_LOADBALANCER=1 just test-eg`.
 
 ## Running Encryption Tests Locally
 - Clone `drivers-evergreen-tools`:
   `git clone [email protected]:mongodb-labs/drivers-evergreen-tools.git`.
 - Run `export DRIVERS_TOOLS=$PWD/drivers-evergreen-tools`
-- Run `AWS_PROFILE=<profile> hatch run encryption:setup` after setting up your AWS profile with `aws configure sso`.
-- Run the tests with `TEST_ENCRYPTION=1 hatch run test:test-eg`.
-- When done, run `hatch run encryption:teardown` to clean up.
+- Run `AWS_PROFILE=<profile> just setup-encryption` after setting up your AWS profile with `aws configure sso`.
+- Run the tests with `TEST_ENCRYPTION=1 just test-eg`.
+- When done, run `just teardown-encryption` to clean up.
 
 ## Re-sync Spec Tests
 

hatch.toml

@@ -30,23 +30,10 @@ check-strict-pyright = [
 ]
 check = ["check-mypy", "check-pyright", "check-strict-pyright"]
 
-[envs.lint]
-skip-install = true
-dependencies = ["pre-commit"]
-[envs.lint.scripts]
-run = "pre-commit run --all-files"
-run-manual = "pre-commit run --all-files --hook-stage manual"
-
 [envs.test]
 features = ["test"]
 [envs.test.scripts]
 test = "pytest -v --durations=5 --maxfail=10 {args}"
 test-eg = "bash ./.evergreen/run-tests.sh {args}"
 test-async = "pytest -v --durations=5 --maxfail=10 -m default_async {args}"
 test-mockupdb = ["pip install -U git+https://github.com/mongodb-labs/mongo-mockup-db@master", "test -m mockupdb"]
-
-[envs.encryption]
-skip-install = true
-[envs.encryption.scripts]
-setup = "bash .evergreen/setup-encryption.sh"
-teardown = "bash .evergreen/teardown-encryption.sh"

justfile

@@ -0,0 +1,64 @@
+# See https://just.systems/man/en/ for instructions
+set shell := ["bash", "-c"]
+set dotenv-load
+set dotenv-filename := "./.evergreen/scripts/env.sh"
+
+# Make the default recipe private so it doesn't show up in the list.
+[private]
+default:
+  @just --list
+
+install:
+    bash .evergreen/scripts/ensure-hatch.sh
+
+[group('docs')]
+docs-build:
+    source .evergreen/scripts/ensure-hatch.sh && hatch run doc:build
+
+[group('docs')]
+docs-serve:
+    source .evergreen/scripts/ensure-hatch.sh && hatch run doc:serve
+
+[group('docs')]
+docs-linkcheck:
+    hatch run doc:linkcheck
+
+[group('docs')]
+docs-test:
+    source .evergreen/scripts/ensure-hatch.sh && hatch run doctest:test
+
+[group('typing')]
+typing:
+    source .evergreen/scripts/ensure-hatch.sh && hatch run typing:check
+
+[group('typing')]
+typing-mypy:
+    source .evergreen/scripts/ensure-hatch.sh && hatch run typing:mypy
+
+[group('lint')]
+lint:
+    pre-commit run --all-files
+
+[group('lint')]
+lint-manual:
+    pre-commit run --all-files --hook-stage manual
+
+[group('test')]
+test *args:
+    source .evergreen/scripts/ensure-hatch.sh && hatch run test:test {{args}}
+
+[group('test')]
+test-mockupdb:
+    source .evergreen/scripts/ensure-hatch.sh && hatch run test:test-mockupdb
+
+[group('test')]
+test-eg *args:
+    source .evergreen/scripts/ensure-hatch.sh && hatch run test:test-eg {{args}}
+
+[group('encryption')]
+setup-encryption:
+    bash .evergreen/setup-encryption.sh
+
+[group('encryption')]
+teardown-encryption:
+    bash .evergreen/teardown-encryption.sh