[RHOAIENG-17006] document the migration of dependencies from pipenv to uv (#1520)

---------

Co-authored-by: Jiri Daněk <[email protected]>

Author: mtchoum1

docs/uv-guide.md

@@ -0,0 +1,162 @@
+# A Guide to Python Package Management with `uv`
+
+`uv` is a fast Python package installer and resolver, designed to be a drop-in replacement for `pip` and `pip-tools`. It aims to provide a more efficient and reliable experience for managing Python dependencies.
+
+This guide will walk you through common `uv` workflows: upgrading packages, locking dependencies, creating `requirements.txt` files, and resolving conflicts.
+
+More Info: https://docs.astral.sh/uv/
+---
+
+## 1. Adding Packages
+
+Packages can be added to the `pyproject.toml` file using `uv add`.
+
+```bash
+# Add a single package
+uv add requests # Adds the latest compatible release of requests
+
+# Add a single package at a specified version
+uv add requests~=2.25  # Adds the latest 2.25.* release of requests
+
+# Add multiple packages
+uv add beautifulsoup4 lxml # Adds the latest compatible release of both beautifulsoup4 and lxml
+
+# Add a single package to a certain group
+uv add requests --group group1 # Adds the latest compatible release of requests to only group1
+```
+
+---
+
+## 2. Upgrading Packages
+
+Navigate to the `pyproject.toml` file, locate the image group, and update the version to your desired one. Afterward, execute `uv lock` to prevent any dependency conflicts.
+
+Locking dependencies means creating a precise list of *all* direct and transitive dependencies, including their exact versions, that your project needs. This ensures reproducible builds across different environments. `uv` uses `uv lock`.
+
+### Creating an `uv lock` File
+
+The pyproject.toml file lists dependencies, with each image having its own dependency group.
+
+Now, use `uv lock` to generate a locked `uv.lock` file. This file will contain all direct and transitive dependencies with their exact versions for the entire repo.
+
+### Compiling and Locking
+
+Now, use `uv pip compile` to generate a locked `requirements.txt` file. This file will contain the exact versions of all direct and transitive dependencies for each image, determined by specifying its dependency group.
+
+```bash
+# Generate requirements.txt for the datascience image
+uv pip compile --format requirements.txt --python 3.11 -o jupyter/datascience/ubi9-python-3.11/requirements.txt --generate-hashes --group jupyter-datascience-image --no-annotate -q pyproject.toml
+```
+
+After running this, `requirements.txt` might look something like this (versions will vary):
+
+**`requirements.txt` example:**
+```
+# This file was autogenerated by uv via the following command:
+#    uv pip compile --format requirements.txt --python 3.11 -o jupyter/datascience/ubi9-python-3.11/requirements.txt --generate-hashes --group jupyter-datascience-image --python-platform linux --no-annotate
+aiohappyeyeballs==2.6.1 \
+    --hash=sha256:c3f9d0113123803ccadfdf3f0faa505bc78e6a72d1cc4806cbd719826e943558 \
+    --hash=sha256:f349ba8f4b75cb25c99c5c2d84e997e485204d2902a9597802b0371f09331fb8
+aiohttp==3.12.13 \
+    --hash=sha256:03d5eb3cfb4949ab4c74822fb3326cd9655c2b9fe22e4257e2100d44215b2e2b \
+    --hash=sha256:04076d8c63471e51e3689c93940775dc3d12d855c0c80d18ac5a1c68f0904358 \
+```
+
+### Installing from a Locked File
+
+To install exactly the versions specified in your locked file:
+
+```bash
+uv pip install --no-deps -r requirements.txt
+```
+
+This is crucial for deployment and team collaboration, as everyone will be using the exact same dependency versions.
+
+---
+
+## 3. Resolving Conflicts
+
+Dependency conflicts occur when two or more packages require incompatible versions of the same dependency or incompatible indices from different sources. `uv`'s resolver is designed to be fast and provide helpful error messages when conflicts arise.
+
+### How `uv` Handles Conflicts
+
+When you run `uv lock`, `uv pip install`, or `uv pip compile`, `uv` attempts to find a set of package versions that satisfy all requirements. If it cannot, it will report a conflict.
+
+**Example of a potential conflict:**
+
+Imagine `package_A` requires `dependency_X==1.0` and `package_B` requires `dependency_X>=2.0`.
+
+If you try to install both:
+
+```toml
+# pyproject.toml
+package_A
+package_B
+```
+```bash
+uv lock
+```
+
+`uv` would output an error similar to this (simplified):
+
+```
+error: Failed to resolve dependencies:
+  - package_A requires dependency_X==1.0
+  - package_B requires dependency_X>=2.0
+  The requested versions of dependency_X (1.0 and >=2.0) are incompatible.
+```
+
+### Strategies for Resolving Conflicts
+
+1.  **Review Error Messages:** `uv`'s error messages are usually very informative, pointing out exactly which packages are in conflict and what their version requirements are. Read them carefully.
+
+2.  **Utilize uv group and conflict:**
+    `uv` introduces the concept of "groups" (similar to extras or development dependencies) which can be defined in `pyproject.toml`. This is a powerful way to manage different sets of dependencies, especially when some dependencies might conflict with others required for different aspects of your project.
+    ```toml
+    [dependency-groups]
+    group1 = [
+        "package_A==1.0"
+    ]
+    group2 = [
+        "package_B>=2.0"
+    ]
+
+    [tool.uv]
+    conflicts = [
+        [
+            { group = "group1" },
+            { group = "group2" }
+        ],
+    ]
+    ```
+
+4.  **Utilize markers for Conditional Dependencies:**
+    When working with projects where different packages are needed, in the same aspects of your project, for various platforms, systems, or Python versions, you can leverage environment markers (PEP 508). uv supports these markers in `pyproject.toml` files, allowing you to specify dependencies that are only installed under certain conditions. This approach is crucial for resolving conflicts that might arise on specific platforms or with particular Python versions.
+    ```
+    # Works for different package
+    requests
+    package_A; sys_platform == "win32"
+    package_B; os_name == "posix"
+
+    # Works for same package
+    requests
+    package_A~=1.24.3; sys_platform == "win32"
+    package_A~=2.35.6; os_name == "posix"
+    ```
+
+5.  **Utilize dependency-metadata:**
+    When managing projects where different packages are needed, in the same aspects of your project, for the identical environment markers, and yet still yield dependency resolution conflicts, you can utilize dependency metadata to force `uv` to install specific dependencies at particular versions and/or particular environment markers.
+    ```
+    [[tool.uv.dependency-metadata]]
+    name = "package_A"
+    version = "1.0"
+    requires-dist = [
+        "dependency_X==2.0"
+    ]
+    ```
+
+---
+
+## Conclusion
+
+`uv` offers a powerful and fast way to manage Python packages. By understanding how to use `uv lock` for locking dependencies and the strategies for resolving conflicts, you can maintain a robust and reproducible development environment for your Python projects.