Merge pull request #90 from berkeleybop/uv-migration

replace poetry with uv in best practices doc

Author: sierra-moxon

best_practice/index.md

@@ -424,9 +424,9 @@ If there is anything you don't understand, **ask on slack**!
    - Follow conventional variable naming
       - Example: https://docs.fast.ai/dev/abbr.html
 - See the [Working with Python Environments](/best_practice/python_environments) guide for details on installing Python versions and managing virtual environments.      
-- All repos should use [poetry](https://python-poetry.org/)
-  - Set up this way: `poetry new --src my-project-name`
-  - OR use `linkml-ws new` for schema-centric repos
+- All repos should use [uv](https://github.com/astral-sh/uv)
+  - Set up this way: `uv init --package my-project-name`
+  - OR use [`linkml-project-copier`](https://github.com/linkml/linkml-project-copier) for schema-centric repos
   - follow standard layouts, with code in `src/`
 - Linting/formatting:
   - Use [black](https://github.com/psf/black) and [flake8](https://pypi.org/project/flake8/) and ruff

best_practice/python_environments.md

@@ -4,207 +4,289 @@ published: true
 title: Working with Python Environments
 ---
 
-## Managing Python Versions
+## Managing Python Versions and Virtual Environments with uv
 
-Most projects we work on require Python 3.8 or greater. A few projects may require an even later version. In either case it is necessary to be able to have multiple versions of Python installed and easily switch between them. Both can be accomplished using [pyenv](https://github.com/pyenv/pyenv).
+Most projects we work on require Python 3.9 or greater. Many require a later version. In either case it is necessary to be able to have multiple versions of Python installed and easily switch between them, as well as manage project-specific dependencies. We use [uv](https://github.com/astral-sh/uv) to handle both Python version management and virtual environments.
 
-### Installing pyenv
+### Installing uv
 
-Use one of the [recommended installation methods](https://github.com/pyenv/pyenv#installation). If you are using Windows use the [pyenv-win fork](https://github.com/pyenv-win/pyenv-win/blob/master/docs/installation.md).
+Follow [uv's recommended installation methods](https://github.com/astral-sh/uv#installation). The quickest way is usually:
+
+```shell
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Or on macOS with Homebrew:
+
+```shell
+brew install uv
+```
 
 To verify that the installation was successful run the following and ensure that it prints out a version number:
 
 ```shell
-pyenv --version
+uv --version
 ```
 
 ### Installing Python Versions
 
-Running the `pyenv versions` command will list the versions of Python that pyenv knows about. If you just installed pyenv the output should say that either no Python version are installed:
+uv can install and manage Python versions directly. To see available Python versions:
+
+```shell
+uv python list --all-versions
+```
+
+To install a specific Python version:
 
 ```shell
-$ pyenv versions
-Warning: no Python detected on the system
+uv python install 3.11
 ```
 
-Or that a system version (not managed by pyenv) is installed and active (denoted by the asterisk):
+Or install the latest patch version of a minor release:
 
 ```shell
-$ pyenv versions
-* system (set by [...]/.pyenv/version)
+uv python install 3.11  # Installs latest 3.11.x
 ```
 
-Use the `pyenv install` command to install new versions of Python that will be managed by pyenv. For example to install a Python 3.8 version[^1]:
+To see which Python versions are currently installed:
 
 ```shell
-pyenv install 3.8.15
+uv python list
 ```
 
-This can be repeated for any other versions you would like to install. The `pyenv install --list` command will show all the versions available for installation.
+### Selecting a Python Version for Your Project
 
-Once you have a few Python versions installed by pyenv, verify they are listed in the output of `pyenv versions`:
+When creating a new project, you can specify which Python version to use:
 
 ```shell
-pyenv versions
-* system (set by [...]/.pyenv/version)
-  3.8.15
-  3.9.15
-  3.10.8
+uv init --python 3.11 my-project
+cd my-project
 ```
 
-### Selecting a Python Version
+For existing projects, uv will use the Python version specified in the `pyproject.toml` file's `requires-python` field. You can also specify a Python version when syncing:
 
-pyenv allows setting a Python version at three levels: global, local, and shell[^2]. When getting set up for the first time, the most important version to set is the global version. Depending on the projects you work on, you may never use local or shell versions at all. 
+```shell
+uv sync --python 3.11
+```
 
-To set the global Python version use the `pyenv global <version>` command. For example:
+Or pin a specific Python version for your project:
 
 ```shell
-pyenv global 3.8.15
+uv python pin 3.11
 ```
 
-Verify that this version is now the default Python version by running:
+This creates a `.python-version` file in your project directory that uv will respect.
+
+## Managing Virtual Environments
+
+uv automatically creates and manages virtual environments for your projects. By default, it creates them in a `.venv` directory within your project folder.
+
+### Creating Virtual Environments
+
+For a new project:
 
 ```shell
-$ python --version
-Python 3.8.15
+uv init my-project
+cd my-project
+uv sync
 ```
 
-The selected version can also be verified with the `pyenv versions`. The asterisk indicates the currently selected Python version:
+You can also create a project with a specific structure:
 
 ```shell
-$ pyenv versions
-  system
-* 3.8.15 (set by [...]/.pyenv/version)
-  3.9.15
-  3.10.8
+uv init --package my-project  # Creates a package structure
+uv init --app my-project      # Creates an application structure
 ```
 
-## Managing Virtual Environments
+For an existing project with a `pyproject.toml` file:
 
-Dependencies for different projects need to managed independently in what Python calls virtual environments. Generally each project will have one virtual environment and we use [Poetry](https://python-poetry.org/docs/) to manage those environments. 
+```shell
+uv sync
+```
 
-### Installing Poetry
+This will:
+- Create a virtual environment in `.venv`
+- Install the Python version specified in `pyproject.toml`
+- Install all project dependencies
 
-First you should have at least one Python 3.7+ version installed and set as the global version through pyenv. Then follow [Poetry's recommended installation methods](https://python-poetry.org/docs/#installation).
+### Adding Dependencies
 
-To verify that the installation was successful run the following and ensure that it prints out a version number:
+Use `uv add` to add new dependencies to your project:
 
 ```shell
-poetry --version
+uv add requests
 ```
 
-### Configuring Poetry
+This updates your `pyproject.toml` and `uv.lock` files and installs the package.
 
-By default Poetry creates virtual environments in one central location. However, we find it more convenient to have the virtual environment created within the project directory itself (specifically in a directory called `.venv`). This behavior can be enabled by running:
+For development dependencies:
 
 ```shell
-poetry config virtualenvs.in-project true
+uv add --dev pytest black mypy
 ```
 
-By default Poetry has its own mechanism for locating (but **not** installing) different Python versions[^3]. This can cause some confusion when used alongside pyenv. Instead of having Poetry attempt to find the right Python version when creating a virtual environment, we want to use pyenv to activate an appropriate version and then use that version to create the virtual environment[^4]. To allow that to work set the following option:
+For optional dependency groups:
 
 ```shell
-poetry config virtualenvs.prefer-active-python true
+uv add --group docs sphinx sphinx-rtd-theme
 ```
 
-### Creating Virtual Environments
+### Updating Dependencies
 
-If you start working on an existing project that already uses Poetry (i.e. it has a `pyproject.toml` and `poetry.lock` file in the root of the project), first ensure that you have a compatible Python version. You can find out which Python versions are acceptable for the project by looking at the `python` entry in the `tool.poetry.dependencies` section of the `pyproject.toml` file. If necessary install and/or activate a compatible Python version using pyenv as described above. 
+Update a specific package:
 
-Next create the virtual environment and install the projects dependencies into it by running:
+```shell
+uv add requests@latest
+```
+
+Update to a specific version:
 
 ```shell
-poetry install
+uv add requests==2.31.0
 ```
 
-To start a new project that uses Poetry use either the `poetry new` or `poetry init` command. `poetry new` generates a simple project directory structure, including a `pyproject.toml` file, based on a name you provide. Using the `--src` option to create a `src` directory is recommended:
+Update all packages to their latest compatible versions:
 
 ```shell
-poetry new --src my-project
-cd my-project
-poetry install
+uv sync --upgrade
 ```
 
-`poetry init` will interactively prompt you to build a custom `pyproject.toml` file. It does not create any other files.
+Update only specific packages:
 
 ```shell
-mkdir my-project
-cd my-project
-poetry init
-poetry install
+uv sync --upgrade-package requests --upgrade-package urllib3
 ```
 
-### Adding New Dependencies
+### Inspecting Dependencies
 
-Use `poetry add` to add a new dependency to a project.
+View the dependency tree:
 
 ```shell
-poetry add requests
+uv tree
 ```
 
-This will install the requests package into the project's virtual environment, add it to the `pyproject.toml` file, and update the `poetry.lock` file with information about the exact version installed.
+Show outdated packages:
 
-In order to synchronize your poetry.lock file with any manual changes to pyproject.yaml directly, be sure to run: 
 ```shell
-poetry lock --no-update
+uv pip list --outdated
 ```
 
-### Updating Dependencies
+### Running Commands
 
-The `poetry add` command can also be used to upgrade a package to a particular version (or range of versions):
+Run commands in the project's virtual environment:
 
 ```shell
-poetry add requests@^2.25.0
+uv run python src/main.py
+uv run pytest
+uv run black .
 ```
 
-Or automatically upgrade to the latest version:
+For interactive sessions, you can activate the virtual environment:
 
 ```shell
-poetry add requests@latest
+source .venv/bin/activate  # On Unix/macOS
+# or
+.venv\Scripts\activate     # On Windows
+
+python src/main.py  # Uses the virtual environment's Python
+deactivate          # Exit the virtual environment
 ```
 
-To update a dependency to the latest version that still respects what is specified in `pyproject.toml` use the `poetry update` command:
+## Advanced Features
+
+### Running Tools Without Installation
+
+Run Python tools without installing them globally:
 
 ```shell
-poetry update requests
+uv tool run black .
+uv tool run --from ruff ruff check
+uv tool run --python 3.12 mypy src/
 ```
 
-If you need to debug a dependency tree, use the `poetry show` command:
+### Installing Global Tools
+
+Install tools globally for command-line use:
 
 ```shell
-poetry show --tree my_package
+uv tool install black
+uv tool install ruff
 ```
 
-### Running Commands
+### Working with Scripts
 
-Use the `poetry run` command to run commands in the project's virtual environment. For example to run an arbitrary Python module:
+Run Python scripts with inline dependencies:
 
 ```shell
-poetry run python src/main.py
+uv run --with pandas,matplotlib analysis.py
 ```
 
-Or if your project (or one of its dependencies) provides a CLI (e.g. pytest):
+Create self-contained scripts with dependency declarations:
+
+```python
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#     "requests",
+#     "rich",
+# ]
+# ///
+
+import requests
+from rich import print
+
+response = requests.get("https://api.github.com")
+print(response.json())
+```
+
+Then run it with:
 
 ```shell
-poetry run pytest
+uv run script.py
 ```
 
-For interactive sessions it may be more convenient to activate the virtual environment in which case `poetry run` will not be necessary. This can be accomplished by running:
+### Working with Requirements Files
+
+Export dependencies to a requirements file:
 
 ```shell
-poetry shell
-python src/main.py  # this will use the virtual environment's Python version
-exit                # deactivate the virtual environment
+uv pip compile pyproject.toml -o requirements.txt
 ```
 
-## Further Reading
+Install from a requirements file:
 
-* [Documentation on all pyenv subcommands](https://github.com/pyenv/pyenv/blob/master/COMMANDS.md#command-reference)
-* [Documentation on all poetry subcommands](https://python-poetry.org/docs/cli/)
+```shell
+uv pip sync requirements.txt
+```
+
+## Migrating from Other Tools
+
+### From pip/venv
+
+If you have a `requirements.txt` file:
+
+```shell
+uv init
+uv pip sync requirements.txt
+uv add --dev <your-dev-packages>
+```
 
-## Footnotes 
+### From Poetry
+
+uv can read `pyproject.toml` files created by Poetry. Simply run:
+
+```shell
+uv sync
+```
+
+To fully migrate, you may want to:
+1. Remove the `[tool.poetry]` sections from `pyproject.toml`
+2. Delete `poetry.lock`
+3. Run `uv sync` to generate `uv.lock`
+
+## Further Reading
 
-[^1]: Use `pyenv latest --known <prefix>` to list latest version that matches `<prefix>`. For example: `pyenv latest --known 3.8`.
-[^2]: This guide mainly focuses on setting the global Python version. See the pyenv documentation for more information about setting [local](https://github.com/pyenv/pyenv/blob/master/COMMANDS.md#pyenv-local) and [shell](https://github.com/pyenv/pyenv/blob/master/COMMANDS.md#pyenv-shell) versions.
-[^3]: For more information see the `poetry env` [documentation](https://python-poetry.org/docs/managing-environments/), but it **not** recommended to use this feature in conjunction with pyenv.
-[^4]: If an incompatible Python version was active when you attempt to create a virtual environment via `poetry install` you will see a message like: `The currently activated Python version 3.8.15 is not supported by the project (^3.9.0).` Or, when attempting to run the Python executable: `Current Python version (3.8.15) is not allowed by the project (^3.9.0).` In this case, instead of using the `poetry env` command just delete the virtual environment (`rm -rf .venv`), ensure a compatible Python version is activated via pyenv (`pyenv global 3.9.15`), and recreate the virtual environment (`poetry install`)
+* [uv Documentation](https://docs.astral.sh/uv/)
+* [uv Python Discovery](https://docs.astral.sh/uv/guides/python/)
+* [uv Configuration](https://docs.astral.sh/uv/configuration/)
+* [Migrating to uv](https://docs.astral.sh/uv/guides/migration/)