From c04757a385b29c7a413c88205cd9923f3f6dc636 Mon Sep 17 00:00:00 2001 From: Tobias Raabe Date: Sun, 20 Jul 2025 09:05:47 +0200 Subject: [PATCH 1/3] Add note about uv workspaces. --- docs/source/tutorials/set_up_a_project.md | 28 ++++++++++++++++------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/docs/source/tutorials/set_up_a_project.md b/docs/source/tutorials/set_up_a_project.md index f5637627..ec35646f 100644 --- a/docs/source/tutorials/set_up_a_project.md +++ b/docs/source/tutorials/set_up_a_project.md @@ -83,12 +83,20 @@ version = "0.1.0" requires-python = ">=3.9" dependencies = ["pytask"] +[build-system] +requires = ["uv_build"] +build-backend = "uv_build" + [tool.pytask.ini_options] paths = ["src/my_project"] ``` uv automatically handles build system configuration and package discovery. +```{seealso} +Another benefit of using uv is that it makes it easy handling repositories with multiple packages allowing you to separate the package with tasks from your potential scientific package. Read more about [workspaces in the uv documentation](https://docs.astral.sh/uv/concepts/projects/workspaces/). +``` + ```` ````{tab-item} pixi @@ -104,6 +112,10 @@ requires-python = ">=3.9" channels = ["conda-forge"] platforms = ["linux-64", "osx-64", "osx-arm64", "win-64"] +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" + [dependencies] pytask = "*" python = ">=3.9" @@ -120,16 +132,16 @@ paths = ["src/my_project"] Create a `pyproject.toml` file for project configuration: ```toml -[build-system] -requires = ["hatchling"] -build-backend = "hatchling.build" - [project] name = "my_project" version = "0.1.0" requires-python = ">=3.9" dependencies = ["pytask"] +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" + [tool.pytask.ini_options] paths = ["src/my_project"] ``` @@ -162,15 +174,15 @@ dependencies: And a `pyproject.toml` file for project configuration: ```toml -[build-system] -requires = ["hatchling"] -build-backend = "hatchling.build" - [project] name = "my_project" version = "0.1.0" requires-python = ">=3.9" +[build-system] +requires = ["hatchling"] +build-backend = "hatchling" + [tool.pytask.ini_options] paths = ["src/my_project"] ``` From 157448a85bf9fb56246eb4dc1f5a282a9b84c9ee Mon Sep 17 00:00:00 2001 From: Tobias Raabe Date: Sun, 20 Jul 2025 09:42:14 +0200 Subject: [PATCH 2/3] Refine docs. --- .../bp_structure_of_a_research_project.md | 4 ++ docs/source/how_to_guides/index.md | 1 + docs/source/how_to_guides/using_workspaces.md | 51 +++++++++++++++++++ docs/source/tutorials/set_up_a_project.md | 10 ++-- 4 files changed, 62 insertions(+), 4 deletions(-) create mode 100644 docs/source/how_to_guides/using_workspaces.md diff --git a/docs/source/how_to_guides/bp_structure_of_a_research_project.md b/docs/source/how_to_guides/bp_structure_of_a_research_project.md index 3a06d6a2..89363020 100644 --- a/docs/source/how_to_guides/bp_structure_of_a_research_project.md +++ b/docs/source/how_to_guides/bp_structure_of_a_research_project.md @@ -23,6 +23,10 @@ As an example, look at two repositories from a COVID-19 forecasting project. - [sid](https://github.com/covid-19-impact-lab/sid) contains the code for the epidemiological model which is applied in the research project. +```{seealso} +Consider using [workspaces](using_workspaces.md) which instead of separate repositories. +``` + Separating the model code from the research project provided several benefits. - The model code is isolated and has its own test suite. Assessing and ensuring the code diff --git a/docs/source/how_to_guides/index.md b/docs/source/how_to_guides/index.md index 53068ee0..d01ecae9 100644 --- a/docs/source/how_to_guides/index.md +++ b/docs/source/how_to_guides/index.md @@ -23,6 +23,7 @@ provisional_nodes_and_task_generators writing_custom_nodes extending_pytask the_data_catalog +using_workspaces ``` ## Best Practice Guides diff --git a/docs/source/how_to_guides/using_workspaces.md b/docs/source/how_to_guides/using_workspaces.md new file mode 100644 index 00000000..d1d74355 --- /dev/null +++ b/docs/source/how_to_guides/using_workspaces.md @@ -0,0 +1,51 @@ +# Using workspaces + +There are situations where you want to structure your project as a multi-package +workspace. Reasons are + +- You are developing a scientific package alongside the project that you want to publish + later. +- The code for dealing with the dataset should be reused in other projects. +- You want to strictly separate the pytask tasks from the remaining code to be able to + switch to another build system. + +In those instances, a workspace might be the right choice. + +```text +project +├── packages +│ ├── data +│ │ ├── pyproject.toml +│ │ └── src +│ │ └── data +│ │ ├── __init__.py +│ │ └── ... +│ ├── analysis +│ │ ├── pyproject.toml +│ │ └── src +│ │ └── analysis +│ │ ├── __init__.py +│ │ └── ... +│ └── tasks +│ ├── pyproject.toml +│ └── src +│ └── tasks +│ ├── __init__.py +│ └── ... +│ +├── pyproject.toml +├── README.md +├── ... +``` + +## Using workspaces with uv + +uv provides excellent support for workspaces which you can read more about in the +[uv documentation](https://docs.astral.sh/uv/concepts/projects/workspaces). + +## Using workspaces with pixi + +pixi is still working on a native workspace experience, but there are workarounds. + +- https://github.com/prefix-dev/pixi/discussions/387 +- https://github.com/Andre-Medina/python-pixi-mono-template diff --git a/docs/source/tutorials/set_up_a_project.md b/docs/source/tutorials/set_up_a_project.md index ec35646f..8dcb86d9 100644 --- a/docs/source/tutorials/set_up_a_project.md +++ b/docs/source/tutorials/set_up_a_project.md @@ -6,6 +6,12 @@ tutorial explains the minimal setup. If you want to use pytask with a collection of scripts, you can skip this lesson and move to the next section of the tutorials. +```{seealso} +In case you are thinking about developing multiple packages in the project that should be separated (one for dealing with the data, one for the analysis and a package for the pytask tasks), consider using a [workspace](../how_to_guides/using_workspaces.md). +``` + +## The directory structure + The following directory tree gives an overview of the project's different parts. ```text @@ -93,10 +99,6 @@ paths = ["src/my_project"] uv automatically handles build system configuration and package discovery. -```{seealso} -Another benefit of using uv is that it makes it easy handling repositories with multiple packages allowing you to separate the package with tasks from your potential scientific package. Read more about [workspaces in the uv documentation](https://docs.astral.sh/uv/concepts/projects/workspaces/). -``` - ```` ````{tab-item} pixi From be2a772540d06b2819ad530df358134d0f396b1d Mon Sep 17 00:00:00 2001 From: Tobias Raabe Date: Sun, 20 Jul 2025 09:49:45 +0200 Subject: [PATCH 3/3] Fix. --- .../how_to_guides/bp_structure_of_a_research_project.md | 2 +- docs/source/how_to_guides/using_workspaces.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/how_to_guides/bp_structure_of_a_research_project.md b/docs/source/how_to_guides/bp_structure_of_a_research_project.md index 89363020..512a3f3a 100644 --- a/docs/source/how_to_guides/bp_structure_of_a_research_project.md +++ b/docs/source/how_to_guides/bp_structure_of_a_research_project.md @@ -24,7 +24,7 @@ As an example, look at two repositories from a COVID-19 forecasting project. epidemiological model which is applied in the research project. ```{seealso} -Consider using [workspaces](using_workspaces.md) which instead of separate repositories. +Nowadays, consider using [workspaces](using_workspaces.md) instead of separate repositories. ``` Separating the model code from the research project provided several benefits. diff --git a/docs/source/how_to_guides/using_workspaces.md b/docs/source/how_to_guides/using_workspaces.md index d1d74355..7e003c61 100644 --- a/docs/source/how_to_guides/using_workspaces.md +++ b/docs/source/how_to_guides/using_workspaces.md @@ -47,5 +47,5 @@ uv provides excellent support for workspaces which you can read more about in th pixi is still working on a native workspace experience, but there are workarounds. -- https://github.com/prefix-dev/pixi/discussions/387 -- https://github.com/Andre-Medina/python-pixi-mono-template +- [https://github.com/prefix-dev/pixi/discussions/387](https://github.com/prefix-dev/pixi/discussions/387) +- [https://github.com/Andre-Medina/python-pixi-mono-template](https://github.com/Andre-Medina/python-pixi-mono-template)