Merge pull request #10 from DavidVujic/uv-support

add docs about supporting uv and the uv-specific commands

Author: DavidVujic

docs/commands.md

@@ -25,6 +25,11 @@ pdm run poly create workspace --name my_example_namespace --theme loose
 rye run poly create workspace --name my_example_namespace --theme loose
 ```
 
+#### uv
+``` shell
+uv run poly create workspace --name my_example_namespace --theme loose
+```
+
 ### Options
 `--name` (required) the workspace name, that will be used as the single top namespace for all bricks. __Choose the name wisely.__
 Have a look in [PEP-423](https://peps.python.org/pep-0423/#respect-ownership) for naming guidelines.
@@ -68,6 +73,11 @@ pdm run poly create component --name my_example_component
 rye run poly create component --name my_example_component
 ```
 
+#### uv
+``` shell
+uv run poly create component --name my_example_component
+```
+
 ### Options
 `--name` (required) the name of the component.
 
@@ -97,6 +107,11 @@ pdm run poly create base --name my_example_base
 rye run poly create base --name my_example_base
 ```
 
+#### uv
+``` shell
+uv run poly create base --name my_example_base
+```
+
 ### Options
 `--name` (required) the name of the base.
 
@@ -126,6 +141,11 @@ pdm run poly create project --name my_example_project
 rye run poly create project --name my_example_project
 ```
 
+#### uv
+``` shell
+uv run poly create project --name my_example_project
+```
+
 ### Options
 `--name` (required) the name of the project.
 
@@ -155,6 +175,11 @@ pdm run poly info
 rye run poly info
 ```
 
+#### uv
+``` shell
+uv run poly info
+```
+
 ### Options
 `--short` Display a view that is better adjusted to Workspaces with many projects.
 
@@ -181,6 +206,11 @@ pdm run poly diff
 rye run poly diff
 ```
 
+#### uv
+``` shell
+uv run poly diff
+```
+
 The `diff` command will compare the current state of the repository, compared to a `git tag`.
 The tool will look for the latest tag according to a certain pattern, such as `stable-*`.
 The pattern can be configured in the Workspace [configuration](configuration.md).
@@ -209,6 +239,11 @@ pdm run poly diff --since release
 rye run poly diff --since release
 ```
 
+#### Rye
+``` shell
+uv run poly diff --since release
+```
+
 ### Options
 `--short` Useful for determining what projects has been affected by the changes in CI.
 
@@ -247,6 +282,11 @@ pdm run poly libs
 rye run poly libs
 ```
 
+#### uv
+``` shell
+uv run poly libs
+```
+
 ### Options
 `--directory`
 Show info about libraries used in a specific project.
@@ -290,6 +330,11 @@ pdm run poly check
 rye run poly check
 ```
 
+#### uv
+``` shell
+uv run poly check
+```
+
 ### Options
 `--directory`
 Show info about libraries used in a specific project.
@@ -331,6 +376,11 @@ pdm run poly sync
 rye run poly sync
 ```
 
+#### uv
+``` shell
+uv run poly sync
+```
+
 This feature is useful for keeping projects in sync. The command will analyze code and add any missing bricks to the projects, including the development project.
 
 - projects: will add missing bricks to the project specific _pyproject.toml_, when imported by any of the already added bricks.
@@ -364,6 +414,11 @@ pdm run poly deps
 rye run poly deps
 ```
 
+#### uv
+``` shell
+uv run poly deps
+```
+
 ### Options
 `--directory`
 Show brick depencencies for a specific project.
@@ -461,3 +516,25 @@ or run the test, filtered by pytest markers
 ``` shell
 rye run pytest -m <<< echo "$query"
 ```
+
+#### uv
+``` shell
+# store the comma-separated list of bricks in a bash variable
+changes="$(uv run poly diff --bricks --short)"
+
+# transform it into a pytest query,
+# i.e. from "hello,world,something" to "hello or world or something"
+query="${changes//,/ or }"
+```
+
+Run the test, filtered by keyword expression
+
+``` shell
+uv run pytest -k <<< echo "$query"
+```
+
+or run the test, filtered by pytest markers
+
+``` shell
+uv run pytest -m <<< echo "$query"
+```

docs/dependencies.md

@@ -46,3 +46,8 @@ pdm run poly check --directory projects/my-project
 ``` shell
 rye run poly check --directory projects/my-project
 ```
+
+### uv
+``` shell
+uv run poly check --directory projects/my-project
+```

docs/deployment.md

@@ -6,8 +6,8 @@ Packaging and deploying Polylith projects is done by using the Poetry Multiproje
 The `poetry build-project` command will make it possible to use relative package includes as how components and bases are added to Python Polylith projects. 
 Relative includes are currently not possible by default in __Poetry__, that is where the __Multiproject__ plugin comes in.
 
-## Hatch, PDM and Rye
-Hatch and PDM support relative includes via the `[tool.poetry.bricks]` configuration.
+## Hatch, PDM, Rye and uv
+Hatch, PDM, Rye and uv support relative includes via the `[tool.poetry.bricks]` configuration.
 Nothing extra needed other than the build hooks.
 
 ### Building source distributions (sdist)?
@@ -16,7 +16,7 @@ you will need to add the path in the project-specific `pyroject.toml`.
 
 If you only provide `wheel` distributions, this is optional.
 
-#### Hatch and Rye
+#### Hatch, Rye and uv
 ```toml
 [tool.hatch.build.targets.wheel]
 packages = ["<your top namespace here>"]
@@ -64,6 +64,14 @@ rye build --wheel
 rye build --sdist
 ```
 
+#### uv
+``` shell
+cd path/to_project
+
+uvx --from build pyproject-build --installer uv
+```
+
+
 This command will create a project specific _dist_ folder containing a _wheel_ and an _sdist_.
 You can use the available __build__ options with this command too.
 
@@ -92,7 +100,7 @@ The `build-project` command, with a custom top namespace:
 poetry build-project --with-top-namespace my_custom_namespace
 ```
 
-#### Hatch, PDM and Rye
+#### Hatch, PDM, Rye and uv
 A custom top namespace is defined in the project-specific `pyproject.toml`:
 
 ``` toml

docs/examples.md

@@ -9,6 +9,7 @@ Here are some examples of how to setup __Python__ with the Polylith Architecture
     - [for PDM](https://github.com/DavidVujic/python-polylith-example-pdm)
     - [for Rye](https://github.com/DavidVujic/python-polylith-example-rye)
     - [for Pants](https://github.com/DavidVujic/python-polylith-example-pants)
+    - [for uv](https://github.com/DavidVujic/python-polylith-example-uv)
 - [Python Polylith Microservices Example](https://github.com/ttamg/python-polylith-microservices-example) by Matt Gosden
 - [Aws CDK App with Polylith](https://github.com/ybenitezf/cdk_polylith) by Yoel Benítez Fonseca
 

docs/index.md

@@ -46,7 +46,7 @@ In short, Polylith is about:
 The __Python tools for the Polylith Architecture__ is available as two options:
 
 - A __Poetry__ plugin. The plugin will add Polylith specific features to Poetry.
-- A standalone CLI supporting __Hatch__, __PDM__, __Rye__ and __Pantsbuild__ (and Poetry).
+- A standalone CLI supporting __Hatch__, __PDM__, __Rye__, __Pantsbuild__ and __uv__ (and Poetry).
 
 ### Use cases
 

docs/installation.md

@@ -15,7 +15,7 @@ poetry self add poetry-polylith-plugin
 
 Done!
 
-## Hatch, PDM, Rye and Pantsbuild
+## Hatch, PDM, Rye, Pantsbuild and uv
 
 No globally added tools needed. Add the project-specific dependencies (see the [Setup](setup.md) and [Projects & pyproject.toml](projects.md) section),
 and the build hook plugins to add support for the Polylith structure and when packaging libraries.

docs/migrating.md

@@ -20,7 +20,7 @@ packages = [
 # insert the needed 3rd party libraries here
 ```
 
-## Hatch, PDM and Rye
+## Hatch, PDM, Rye and uv
 ``` toml
 [project]
 dependencies = [] # insert the needed 3rd party libraries here
@@ -65,13 +65,20 @@ cd path/to/project
 pdm build
 ```
 
-#### Rye
+### Rye
 ``` shell
 cd path/to_project
 
 rye build --sdist
 ```
 
+### uv
+``` shell
+cd path/to_project
+
+uvx --from build pyproject-build --installer uv
+```
+
 The output is a `wheel` and, more importantly, an `sdist` (a source distribution). It is essentially a _zip_ file containing all source code used in the project.
 
 That's all!

docs/projects.md

@@ -123,6 +123,59 @@ dev-mode-dirs = ["components", "bases", "development", "."]
 ```
 
 
+### The project-specific pyproject.toml file(s)
+``` toml
+[build-system]
+requires = ["hatchling", "hatch-polylith-bricks"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.hooks.polylith-bricks]
+# this section is needed to enable the hook in the build process, even if empty.
+```
+
+Polylith bricks are added in the `[tool.polylith.bricks]` section:
+
+``` toml
+[tool.polylith.bricks]
+"../../bases/my_namespace/my_base" = "my_namespace/my_base"
+"../../components/my_namespace/my_component" = "my_namespace/my_component"
+"../../components/my_namespace/my_other_component" = "my_namespace/my_other_component"
+```
+
+The `bases` and `components` folders are located at the workspace root.
+The project-specific `pyproject.toml` file is located in a subfolder of the `projects` folder.
+
+## uv
+
+### The pyproject.toml in the Workspace (i.e. the one in the root folder)
+Add the `polylith-cli` to the workspace `pyproject.toml` configuration.
+
+Add it manually, or by running `uv add polylith-cli --dev`:
+
+``` toml
+[tool.uv]
+dev-dependencies = ["polylith-cli"]
+```
+
+The default build backend for uv is Hatch.
+Add the `hatch-polylith-bricks` build hook plugin to the `pyproject.toml` file.
+
+``` toml
+[build-system]
+requires = ["hatchling", "hatch-polylith-bricks"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.hooks.polylith-bricks]
+# this section is needed to enable the hook in the build process, even if empty.
+```
+
+Make uv (and Hatch) aware of the way Polylith organizes source code:
+``` toml
+[tool.hatch.build]
+dev-mode-dirs = ["components", "bases", "development", "."]
+```
+
+
 ### The project-specific pyproject.toml file(s)
 ``` toml
 [build-system]

docs/setup.md

@@ -157,7 +157,7 @@ Make Rye (and Hatch) aware of the way Polylith organizes source code:
 dev-mode-dirs = ["components", "bases", "development", "."]
 ```
 
-Remove the `[project.scripts]` and `[tool.hatch.build.targets.wheel]` sections.
+Remove the `[tool.hatch.build.targets.wheel]` section.
 
 Run the `sync` command to update the virtual environment:
 
@@ -170,6 +170,47 @@ Finally, remove the `src` boilerplate code that was added by Rye in the first st
 rm -r src
 ```
 
+### uv
+``` shell
+uv init my_repo  # name your repo
+
+cd my_repo
+
+uv add polylith-cli --dev
+
+uv sync  # create a virtual environment and lock files
+```
+
+Create a workspace, with a basic Polylith folder structure.
+
+``` shell
+uv run poly create workspace --name my_namespace --theme loose
+```
+
+`--name` (required) the workspace name, that will be used as the single top namespace for all bricks.
+__Choose the name wisely.__ Have a look in [PEP-423](https://peps.python.org/pep-0423/#respect-ownership) for naming guidelines.
+
+`--theme` the structure of the workspace, `loose` is the recommended structure for Python.
+
+#### Edit the configuration
+The default build backend for uv is Hatch.
+Make uv (and Hatch) aware of the way Polylith organizes source code:
+``` toml
+[tool.hatch.build]
+dev-mode-dirs = ["components", "bases", "development", "."]
+```
+
+Run the `sync` command to update the virtual environment:
+
+``` shell
+uv sync
+```
+
+Finally, remove the `src` boilerplate code that was added by uv in the first step:
+``` shell
+rm -r src
+```
+
 ### Pantsbuild (aka Pants)
 Have a look in the Pants-specific [example repository](examples.md) for details on the setup.
 You will find examples of combining Pants with Polylith, by using the Hatch build backend in the project-specific configurations.