From d4fad8d53b4b89aaaca1c66cdaf6cd0abe406046 Mon Sep 17 00:00:00 2001 From: Alister Trabattoni Date: Mon, 1 Jun 2026 16:59:31 +0200 Subject: [PATCH 1/4] Migrate dev workflow from conda to uv Replace conda environment setup and pip install with uv-based workflow in contribute.md. Move pytest and ruff from optional-dependencies to uv dependency-groups, and consolidate tests group. Minor prose fixes (typos, line wrapping) throughout the contributing guide. --- docs/contribute.md | 81 +++++++++++++++++----------------------------- pyproject.toml | 18 +++-------- 2 files changed, 34 insertions(+), 65 deletions(-) diff --git a/docs/contribute.md b/docs/contribute.md index 00a4902..df7b7ec 100644 --- a/docs/contribute.md +++ b/docs/contribute.md @@ -1,9 +1,12 @@ # Development +This project uses [Git](https://git-scm.com/) for version control and [uv](https://docs.astral.sh/uv/) for Python packaging and environment management. + +Ensure both tools are installed and available in your environment. + ## Configure development environment -1. Be sure to have a github account with some SSH key configured. -(or you won't be able to push modifications) and that you configured git: +1. Be sure to have a github account with some SSH key configured (or you won't be able to push modifications) and that you configured git: ``` git config --global user.name "Your Name Comes Here" git config --global user.email you@yourdomain.example.com @@ -20,31 +23,23 @@ cd xdas git checkout dev ``` -4. Create a dedicated conda environment -``` -conda create -n xdas-dev -conda activate xdas-dev -conda install pip -``` - -5. Install xdas and optional dependencies in editable mode: +4. Create virtual environment and install development dependencies: ``` -pip install -e ".[dev,docs,tests]" +uv sync --all-groups ``` -6. Check that all tests are passing (one test is not passing but this is ok): +5. Check that all tests are passing and that test coverage is 100\%: ``` -pytest +uv run pytest --cov ``` -7. Check that the documentation builds without errors: +6. Check that the documentation builds without errors: ``` cd docs -make html +uv run make html cd .. ``` -You can then inspect the documentation by opening `index.html` in docs/_build/html with -any browser (see later). +You can then inspect the documentation by opening `index.html` in docs/_build/html with any browser (see later). ## Package structure @@ -60,9 +55,7 @@ Here a quick overview: ## Adding a function -Most of the time, you will add functions (or methods) to implement new features. -Small internal functions can be quite undocumented but ideally, function that will bue -used by users requires to: +Most of the time, you will add functions (or methods) to implement new features. Small internal functions can be quite undocumented but ideally, function that will be used by users requires to: - write the body of the function - write a docstring that explains how to use the function - add an example into the docstring @@ -82,22 +75,19 @@ The usual workflow is: - publish your branch online - make a pull request to ask the permission to merge your code. -To do this you can either use git in the [terminal](https://git-scm.com/docs/gittutorial) -or within [VS Code](https://code.visualstudio.com/docs/sourcecontrol/overview). +To do this you can either use git in the [terminal](https://git-scm.com/docs/gittutorial) or within [VS Code](https://code.visualstudio.com/docs/sourcecontrol/overview). ## How to write a docstring with examples -You need to add multiline string that follows the -[numpydoc](https://numpydoc.readthedocs.io/) style. Here an example: +You need to add multiline string that follows the [numpydoc](https://numpydoc.readthedocs.io/) style. Here an example: ```python def your_function(arg1, arg2=None): """ Explain in one line the main objective. - Add additional information with with as many comments as you wants. You will need - to wrap you code (ideally max 88 char per line). + Add additional information with with as many comments as you wants. You will need to wrap you code (ideally max 88 char per line). Parameters ---------- @@ -120,25 +110,21 @@ def your_function(arg1, arg2=None): return do_something_with_args(arg1, arg2) ``` -Note that the outputs of the examples will be used as tests. `pytest` will check that -the hard coded output matches what the code actually outputs. This is a first -quick way to add tests to your function. +Note that the outputs of the examples will be used as tests. `pytest` will check that the hard coded output matches what the code actually outputs. This is a first quick way to add tests to your function. ## How to format your code Run (in the root xdas folder or where you are working): ``` -ruff check --fix && ruff format +uv run ruff check --fix +uv run ruff format ``` ## How to add tests [`pytest`](https://docs.pytest.org) is used for testing. -If you are working on a function in a script in `xdas/dir/file.py` then test must be -located in `tests/dir/test_file.py`. In `pytest` each test is one function. Each function -can check several things with the `assert` python statement. Functions -can be grouped into classes. Bellow an example: +If you are working on a function in a script in `xdas/dir/file.py` then test must be located in `tests/dir/test_file.py`. In `pytest` each test is one function. Each function can check several things with the `assert` python statement. Functions can be grouped into classes. Bellow an example: ```python import pytest @@ -150,37 +136,30 @@ class TestMyModule: my_function(-1) ``` -Note that here we have one test class for the entire module (the `file.py`) but we could -have one test class per function if those require to test a lot of things. When testing -classes, one testing class per developed class is generally the way to go. +Note that here we have one test class for the entire module (the `file.py`) but we could have one test class per function if those require to test a lot of things. When testing classes, one testing class per developed class is generally the way to go. -The to run check that your test are passing: +To run and check that your tests are passing: ``` -pytest +uv run pytest --cov ``` -Note that VS Code as a nice -[set of features](https://code.visualstudio.com/docs/python/testing) to run test. +Note that VS Code has a nice [set of features](https://code.visualstudio.com/docs/python/testing) to run tests. ## Editing the documentation The documentation is written in [markdown](https://www.markdownguide.org/basic-syntax/). -It uses the [MyST](https://jupyterbook.org/en/stable/content/myst.html) syntax to run -code as if the documentation was a jupyter notebook. +It uses the [MyST](https://jupyterbook.org/en/stable/content/myst.html) syntax to run code as if the documentation was a jupyter notebook. -The simpler si probably to take inspiration from some pre-existing documentation. +The simplest is probably to take inspiration from some pre-existing documentation. -If you need some stuff to be run outside some documentation page (e.g. to generate some -data) you can place your code at the end of the `docs/conf.py` file. +If you need some stuff to be run outside some documentation page (e.g. to generate some data) you can place your code at the end of the `docs/conf.py` file. To build the documentation go in the docs folder an run: ``` -make html +uv run make html ``` -You can then inspect the documentation by opening `index.html` in docs/_build/html with -any browser. +You can then inspect the documentation by opening `index.html` in docs/_build/html with any browser. -Note that VS Code as an extension called Live Preview to render html. Once this extension is installed, -right click on the `index.html` file and click on Show preview. \ No newline at end of file +Note that VS Code has an extension called Live Preview to render html. Once this extension is installed, right click on the `index.html` file and click on Show preview. diff --git a/pyproject.toml b/pyproject.toml index 2c072eb..bb0d14f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -30,8 +30,8 @@ dependencies = [ "pyzmq", ] -[project.optional-dependencies] -dev = ["build", "ruff", "twine"] +[dependency-groups] +dev = ["ruff", "pyright", "pytest", "pytest-cov"] docs = [ "ipykernel", "matplotlib", @@ -41,14 +41,7 @@ docs = [ "sphinx-copybutton", "sphinx", ] -tests = [ - "dascore", - "pytest", - "pytest-cov", - "psutil", - "seisbench", - "torch", -] +tests = ["dascore", "psutil", "seisbench", "torch"] [tool.ruff.lint] extend-select = ["I", "D"] @@ -62,10 +55,7 @@ convention = "numpy" "docs/**" = ["D"] [tool.pytest.ini_options] -addopts = [ - "--doctest-modules", - "--import-mode=importlib", -] +addopts = ["--doctest-modules", "--import-mode=importlib"] doctest_optionflags = "NORMALIZE_WHITESPACE" markers = ["slow: marks tests as slow (skip with --skip-slow)"] From aba00cad3569d67ce86e3e5a56f4f86dcd33a00b Mon Sep 17 00:00:00 2001 From: Alister Trabattoni Date: Mon, 1 Jun 2026 17:08:52 +0200 Subject: [PATCH 2/4] Update CI workflows to use uv Replace setup-python + pip with astral-sh/setup-uv and uv sync --all-groups. Use uv run for pytest invocations to match the new dependency-groups layout. --- .github/workflows/code-coverage.yaml | 15 +++++---------- .github/workflows/tests.yaml | 12 ++++-------- 2 files changed, 9 insertions(+), 18 deletions(-) diff --git a/.github/workflows/code-coverage.yaml b/.github/workflows/code-coverage.yaml index 1451a47..6f7ca3b 100644 --- a/.github/workflows/code-coverage.yaml +++ b/.github/workflows/code-coverage.yaml @@ -10,21 +10,16 @@ jobs: - name: Checkout code uses: actions/checkout@v4 - - name: Set up Python - uses: actions/setup-python@v5 + - name: Set up uv + uses: astral-sh/setup-uv@v6 with: - python-version: 3.14 + python-version: "3.14" - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install '.[tests]' + run: uv sync --all-groups - name: Run tests with coverage - run: coverage run --source=xdas -m pytest - - - name: Generate coverage report - run: coverage xml + run: uv run pytest --cov --cov-report=xml - name: Upload coverage reports to Codecov uses: codecov/codecov-action@v4 diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml index 7a4e350..b67a337 100644 --- a/.github/workflows/tests.yaml +++ b/.github/workflows/tests.yaml @@ -12,15 +12,11 @@ jobs: steps: - uses: actions/checkout@v4 - - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v5 + - name: Set up uv + uses: astral-sh/setup-uv@v6 with: python-version: ${{ matrix.python-version }} - cache: 'pip' - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install '.[tests]' + run: uv sync --all-groups - name: Test with pytest - run: | - pytest + run: uv run pytest From bd492ca5b54041335cb3b5e6a6242fb8aacadacc Mon Sep 17 00:00:00 2001 From: Alister Trabattoni Date: Mon, 1 Jun 2026 17:13:10 +0200 Subject: [PATCH 3/4] Remove pyright dependency for now. --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index bb0d14f..7b9de42 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -31,7 +31,7 @@ dependencies = [ ] [dependency-groups] -dev = ["ruff", "pyright", "pytest", "pytest-cov"] +dev = ["ruff", "pytest", "pytest-cov"] docs = [ "ipykernel", "matplotlib", From 239ebd09aee02b843f7e8e9bb62904a94724e987 Mon Sep 17 00:00:00 2001 From: Alister Trabattoni Date: Mon, 1 Jun 2026 17:20:18 +0200 Subject: [PATCH 4/4] Ignore uv.lock. --- .gitignore | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index e925a3c..290327d 100644 --- a/.gitignore +++ b/.gitignore @@ -166,4 +166,7 @@ cython_debug/ # AI agents CLAUDE.md -.claude \ No newline at end of file +.claude + +# uv lock not relevant for a library +uv.lock