From f265c9ef09c36f9f838615cfb84d764f920038a3 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Wed, 6 Aug 2025 18:45:11 +0000 Subject: [PATCH 1/2] Improve section 1.3 of the course --- docs/1. Initializing/1.3. uv (project).md | 104 ++++++++++++---------- 1 file changed, 55 insertions(+), 49 deletions(-) diff --git a/docs/1. Initializing/1.3. uv (project).md b/docs/1. Initializing/1.3. uv (project).md index 4b5f5aef..2b270810 100644 --- a/docs/1. Initializing/1.3. uv (project).md +++ b/docs/1. Initializing/1.3. uv (project).md @@ -2,13 +2,13 @@ description: Discover how to use uv to manage project dependencies and build Python packages, streamlining the process of creating production-ready artifacts. --- -# 1.3. uv (project) +# 🚀 1.3. uv (project) -## What is a package? +## 📦 What is a package? -A [Python package](https://packaging.python.org/en/latest/) is a set of Python modules grouped together that can be installed and used within your projects. Python packages help you manage the functionality of Python by allowing you to add and utilize external libraries and frameworks that are not part of the standard Python library. +A [Python package](https://packaging.python.org/en/latest/) is a collection of Python modules that can be installed and used in your projects. Packages allow you to leverage external libraries and frameworks, extending Python's built-in capabilities. -[uv](https://docs.astral.sh/uv/) simplifies the management of these packages by handling them as dependencies. When using uv, developers can easily specify which packages are needed for their projects through a `pyproject.toml` file. Uv ensures that all specified dependencies are installed in the correct versions, maintaining a stable and conflict-free environment for development. Here’s an example of specifying dependencies with uv: +[uv](https://docs.astral.sh/uv/) simplifies the management of these packages by treating them as dependencies. With uv, you can declare the packages your project needs in a `pyproject.toml` file. uv then ensures that the correct versions of these dependencies are installed, creating a stable and conflict-free development environment. Here’s a basic example of how to specify dependencies with uv: ```toml # https://docs.astral.sh/uv/reference/pyproject-toml/ @@ -29,9 +29,9 @@ dev = [ You will learn more on how to construct and publish Python Package in the [Package section of this course](../3. Productionizing/3.0. Package.md). -## Why do you need a package manager? +## 🤔 Why do you need a package manager? -In the Python ecosystem, the distribution and installation of software through packages is a standard practice. These packages, often available in Wheel or zip formats, encapsulate source code along with vital metadata. Manually handling these packages and their dependencies can quickly become cumbersome, underscoring the need for package managers. Tools like uv automate these processes, boosting productivity and guaranteeing consistent environments across development and deployment. +In the Python ecosystem, software is typically distributed and installed as packages. These packages, often in Wheel or zip format, contain source code and essential metadata. Manually managing these packages and their dependencies can be a tedious and error-prone process. Package managers like uv automate these tasks, which boosts productivity and ensures that your development and deployment environments are consistent.
Python Environment @@ -40,32 +40,31 @@ In the Python ecosystem, the distribution and installation of software through p By default, uv will download and install Python packages from [PyPI](https://pypi.org/), a repository of software for the Python programming language. If needed, [other Python repositories](https://warehouse.pypa.io/repository-projects/) can be configured to provide extra sources of dependencies. -## Why should you use uv in your project? +## ✨ Why should you use uv in your project? -Incorporating uv into your project brings several key advantages: +Using uv in your project offers several key benefits: -- **Improved Environment Management**: uv streamlines the management of different project environments, promoting consistent development practices. -- **Simplified Package Building and Distribution**: It provides a unified workflow for building, distributing, and installing packages, easing the complexities usually associated with these tasks. -- **Uniform Project Metadata**: uv employs a standardized approach to defining project metadata, including dependencies, authors, and versioning, through a `pyproject.toml` file. This standardization ensures clarity and uniformity. +- **Improved Environment Management**: uv simplifies the management of project environments, which helps maintain consistency. +- **Simplified Package Building and Distribution**: It provides a unified workflow for building, distributing, and installing packages, which reduces complexity. +- **Standardized Project Metadata**: uv uses a standard `pyproject.toml` file to define project metadata, such as dependencies, authors, and versioning. This ensures that your project is easy to understand and maintain. -Compared to traditional approaches that involve pip, venv, and manual dependency management, uv offers a more cohesive and friendly experience, merging multiple package and environment management tasks into a single, simplified process. +Compared to traditional tools like pip and venv, uv provides a more cohesive and user-friendly experience by combining package and environment management into a single, streamlined process. -## How can you use uv for your MLOps project? +## 🛠️ How can you use uv for your MLOps project? -Integrating uv into your MLOps project involves several key steps designed to configure and prepare your development environment: +To integrate uv into your MLOps project, you can follow these steps to set up your development environment: - Begin by creating a new project directory and navigate into it. - Run `uv init` in your terminal. This command starts an interactive guide to help set initial project parameters, such as package name, version, description, author, and dependencies. This step generates a `pyproject.toml` file, crucial for your project's configuration under uv. - Run `uv sync` to install the project dependencies and source code. This will let you access your project code through `uv run` and its command-line utilities. -The `pyproject.toml` file plays a central role in defining your project’s dependencies and settings. +The `pyproject.toml` file is central to defining your project's dependencies and settings. Let's break down a typical example: ```toml # https://docs.astral.sh/uv/reference/settings/ # https://packaging.python.org/en/latest/guides/writing-pyproject-toml/ -# PROJECT - +# Project metadata [project] name = "bikes" version = "4.1.0" @@ -75,54 +74,45 @@ readme = "README.md" license = { file = "LICENSE.txt" } keywords = ["mlops", "python", "package"] requires-python = ">=3.13" + +# Main dependencies dependencies = [ "loguru>=0.7.3", "matplotlib>=3.10.1", "mlflow>=2.20.3", - "numba>=0.61.0", - "numpy>=2.1.3", - "omegaconf>=2.3.0", - "pandas>=2.2.3", - "pandera>=0.23.0", - "plotly>=6.0.0", - "plyer>=2.1.0", - "psutil>=7.0.0", - "pyarrow>=19.0.1", - "pydantic-settings>=2.8.1", - "pydantic>=2.10.6", - "pynvml>=12.0.0", "scikit-learn>=1.6.1", - "setuptools>=75.8.2", - "shap>=0.46.0", - "hatchling>=1.27.0", + # ... and so on ] -# LINKS - +# Project URLs [project.urls] Homepage = "https://github.com/fmind/mlops-python-package" Documentation = "https://fmind.github.io/mlops-python-package/bikes.html" Repository = "https://github.com/fmind/mlops-python-package" -"Bug Tracker" = "https://github.com/fmind/mlops-python-package/issues" -Changelog = "https://github.com/fmind/mlops-python-package/blob/main/CHANGELOG.md" - -# SCRIPTS +# Command-line scripts [project.scripts] bikes = 'bikes.scripts:main' -# SYSTEMS - +# Build system configuration [build-system] requires = ["hatchling"] build-backend = "hatchling.build" ``` +Here’s what each section means: + +- **`[project]`**: This section contains general metadata about your project, such as its name, version, and description. +- **`dependencies`**: This is a list of the main dependencies that your project needs to run. +- **`[project.urls]`**: This section allows you to include helpful links, such as to the project's homepage or documentation. +- **`[project.scripts]`**: Here, you can define command-line scripts that will be created when your package is installed. +- **`[build-system]`**: This section specifies the build tool that `uv` will use to create your package. + At the end of the installation process, a `uv.lock` file is generated with all the project dependencies that have been installed. You can remove and regenerate the `uv.lock` file if you wish to update the list of dependencies. -## How can you install dependencies for your project with uv? +## ➕ How can you install dependencies for your project with uv? -Uv differentiates between main (production) and development dependencies, offering an organized approach to dependency management. To add dependencies, use the following commands: +uv distinguishes between main (production) and development dependencies, which allows for a more organized approach to dependency management. To add dependencies, you can use the following commands: ```bash # For main dependencies @@ -134,13 +124,13 @@ $ uv add --group dev ipykernel Executing these commands updates the `pyproject.toml` file, accurately managing and versioning your project's dependencies. -## What is the difference between main and dev dependencies in uv? +## Main vs. Dev Dependencies in uv -In uv, dependencies are divided into two types: [main dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/#project-dependencies) and [development (dev) dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/#development-dependencies). +In uv, dependencies are categorized into two types: [main dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/#project-dependencies) and [development (dev) dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/#development-dependencies). -**Main Dependencies**: These are essential for your project's production environment—your application can't run without them. For example, libraries like Pandas or XGBoost would be main dependencies for an MLOps project. +- **Main Dependencies**: These are essential for your project to run in a production environment. For example, libraries like pandas or scikit-learn are typically main dependencies in an MLOps project. -**Development Dependencies**: These are used only during development and testing, such as testing frameworks (e.g., pytest) or linters (e.g., ruff). They are not required in production. +- **Development Dependencies**: These are only used for development and testing purposes. Examples include testing frameworks like `pytest` or linters like `ruff`. They are not required for the application to run in production. Here’s a simple example in a `pyproject.toml` file: @@ -158,11 +148,27 @@ dev = [ This setup helps keep production environments lean by excluding unnecessary development tools. -## Can you use uv to download Python dependencies from your own organization's code repository? +## 🏢 Using Custom Repositories + +uv supports [custom package repositories](https://docs.astral.sh/uv/concepts/projects/dependencies/#dependency-sources), including private and organizational ones. This allows you to use proprietary packages alongside those from the public PyPI. You can easily add a custom repository and configure authentication using uv's commands, which ensures secure and flexible dependency management. + +## ⚡ Common `uv` Commands + +Here is a quick reference for some of the most common `uv` commands: + +- **`uv init`**: Initializes a new project by creating a `pyproject.toml` file. +- **`uv add`**: Adds a new dependency to your project. +- **`uv sync`**: Installs the dependencies listed in your `pyproject.toml` file. +- **`uv run`**: Executes a command in the project's virtual environment. +- **`uv pip install`**: Installs a package into the virtual environment. +- **`uv pip uninstall`**: Uninstalls a package from the virtual environment. +- **`uv pip list`**: Lists the installed packages in the virtual environment. + +## 🔒 The `uv.lock` File -Uv supports incorporating [custom package repositories, including private or organizational ones](https://docs.astral.sh/uv/concepts/projects/dependencies/#dependency-sources). This capability allows for the use of proprietary packages in conjunction with those from the public PyPI. Adding a custom repository and setting up authentication is facilitated by uv's configuration commands, offering secure and adaptable dependency management. +The `uv.lock` file is generated after you install your project's dependencies. It records the exact versions of all the packages that were installed, including their dependencies. This is crucial for ensuring that your project is reproducible. When you share your project with others, they can use the `uv.lock` file to create an identical environment, which helps to avoid bugs and inconsistencies. -## uv (project) additional resources +## 📚 Additional Resources - **[`pyproject.toml` example from the MLOps Python Package](https://github.com/fmind/mlops-python-package/blob/main/pyproject.toml)** - [uv: Unified Python packaging](https://astral.sh/blog/uv-unified-python-packaging) From 07d67d52d32122e9b379567a9e3bac9aba5a1a89 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A9d=C3=A9ric=20Hurier=20=28Fmind=29?= Date: Thu, 7 Aug 2025 21:20:43 +0200 Subject: [PATCH 2/2] review --- docs/1. Initializing/1.3. uv (project).md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/1. Initializing/1.3. uv (project).md b/docs/1. Initializing/1.3. uv (project).md index 2b270810..150882ac 100644 --- a/docs/1. Initializing/1.3. uv (project).md +++ b/docs/1. Initializing/1.3. uv (project).md @@ -160,14 +160,18 @@ Here is a quick reference for some of the most common `uv` commands: - **`uv add`**: Adds a new dependency to your project. - **`uv sync`**: Installs the dependencies listed in your `pyproject.toml` file. - **`uv run`**: Executes a command in the project's virtual environment. -- **`uv pip install`**: Installs a package into the virtual environment. -- **`uv pip uninstall`**: Uninstalls a package from the virtual environment. -- **`uv pip list`**: Lists the installed packages in the virtual environment. ## 🔒 The `uv.lock` File The `uv.lock` file is generated after you install your project's dependencies. It records the exact versions of all the packages that were installed, including their dependencies. This is crucial for ensuring that your project is reproducible. When you share your project with others, they can use the `uv.lock` file to create an identical environment, which helps to avoid bugs and inconsistencies. +## 🔑 Key Takeaways + +- **Unified Tool**: `uv` streamlines Python project management by combining the functionalities of `pip`, `venv`, `pipx`, and `pyenv` into a single, fast tool. +- **`pyproject.toml`**: This file is central to `uv` projects, defining metadata, dependencies (main and development), and build configurations. +- **Dependency Management**: `uv` simplifies adding, managing, and synchronizing project dependencies, ensuring consistent environments. +- **Reproducibility**: The `uv.lock` file guarantees reproducible environments by locking exact dependency versions. + ## 📚 Additional Resources - **[`pyproject.toml` example from the MLOps Python Package](https://github.com/fmind/mlops-python-package/blob/main/pyproject.toml)**