mirrors/uv

mirror of https://github.com/astral-sh/uv.git synced 2025-10-19 06:47:23 +00:00

Use prettier to format the documentation (#5708 )

To enforce the 100 character line limit in markdown files introduced in
https://github.com/astral-sh/uv/pull/5635, and to automate the
formatting of markdown files, i've added prettier and formatted our
markdown files with it.

I've excluded the changelog and the generated references documentation
from this for having too many changes, but we can also include them.

I'm not particular on which style we use. My main motivations are
(major) not having to reflow markdown files myself anymore and (minor)
consistence between all markdown files. I've chosen prettier for similar
reason as we chose black, it's a single good style that's automated and
shared in the community. I do prefer prettier's style of not breaking
inside of a link name though.

This PR is in two parts, the first adds prettier to CI and documents
using it, while the second actually formats the docs. When merge
conflicts arise, we can drop the last commit and regenerate it with `npx
prettier --prose-wrap always --write BENCHMARKS.md CONTRIBUTING.md
README.md STYLE.md docs/*.md docs/concepts/**/*.md docs/guides/**/*.md
docs/pip/**/*.md`.

---------

Co-authored-by: Zanie Blue <contact@zanie.dev>

2024-08-02 08:58:31 -05:00

4.6 KiB

Raw Blame History

Using uv in GitHub Actions

Installation

uv installation differs depending on the platform.

on Unix

name: Example on Unix

jobs:
  uv-example-linux:
    name: python-linux
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up uv
        # Install uv using the standalone installer
        run: curl -LsSf https://astral.sh/uv/install.sh | sh

on Windows

name: Example on Windows

jobs:
  uv-example-windows:
    name: python-windows
    runs-on: windows-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up uv
        # Install uv using the standalone installer
        run: irm https://astral.sh/uv/install.ps1 | iex
        shell: powershell

Using a matrix

name: Example

jobs:
  uv-example-multiplatform:
    name: python-${{ matrix.os }}

    strategy:
      matrix:
        os:
          - ubuntu-latest
          - windows-latest
          - macos-latest

      fail-fast: false

    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v4

      - name: Set up uv
        if: ${{ matrix.os == 'ubuntu-latest' || matrix.os == 'macos-latest' }}
        run: curl -LsSf https://astral.sh/uv/install.sh | sh

      - name: Set up uv
        if: ${{ matrix.os == 'windows-latest' }}
        run: irm https://astral.sh/uv/install.ps1 | iex
        shell: powershell

Setting up Python

Python can be installed with the python install command:

steps:
  # ... setup up uv ...

  - name: Set up Python
    run: uv python install

This will respect the Python version pinned in the project.

Or, when using a matrix, as in:

strategy:
  matrix:
    python-version:
      - "3.10"
      - "3.11"
      - "3.12"

Provide the version to the python install invocation:

steps:
  # ... setup up uv ...

  - name: Set up Python ${{ matrix.python-version }}
    run: uv python install ${{ matrix.python-version }}

Alternatively, the official GitHub setup-python action can be used. This is generally faster, but will not respect the project's pinned Python version.

steps:
  - name: "Set up Python"
    uses: actions/setup-python@v5
    with:
      python-version: 3.12

Syncing and running

Once uv and Python are installed, the project can be installed with uv sync and commands can be run in the environment with uv run:

steps:
  # ... setup up Python and uv ...

  - name: Install the project
    run: uv sync --all-extras --dev

  - name: Run tests
    # For example, using `pytest`
    run: uv run pytest tests

Caching

It may improve CI times to store uv's cache across workflow runs.

The cache can be saved and restored with the official GitHub cache action:

jobs:
  install_job:
    env:
      # Configure a constant location for the uv cache
      UV_CACHE_DIR: /tmp/.uv-cache

    steps:
      # ... setup up Python and uv ...

      - name: Restore uv cache
        uses: actions/cache@v4
        with:
          path: /tmp/.uv-cache
          key: uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
          restore-keys: |
            uv-${{ runner.os }}-${{ hashFiles('uv.lock') }}
            uv-${{ runner.os }}

      # ... install packages, run tests, etc ...

      - name: Minimize uv cache
        run: uv cache prune --ci

The uv cache prune --ci command is used to reduce the size of the cache and is optimized for CI. Its effect on performance is dependent on the packages being installed.

!!! tip

If using `uv pip`, use `requirements.txt` instead of `uv.lock` in the cache key.

Using `uv pip`

If using the uv pip interface instead of the uv project interface, uv requires a virtual environment by default. To allow installing packages into the system environment, use the --system flag on all uv invocations or set the UV_SYSTEM_PYTHON variable.

The UV_SYSTEM_PYTHON variable can be defined in at different scopes.

Opt-in for the entire workflow by defining it at the top level:

env:
  UV_SYSTEM_PYTHON: 1

jobs: ...

Or, opt-in for a specific job in the workflow:

jobs:
  install_job:
    env:
      UV_SYSTEM_PYTHON: 1
    ...

Or, opt-in for a specific step in a job:

steps:
  - name: Install requirements
    run: uv pip install -r requirements.txt
    env:
      UV_SYSTEM_PYTHON: 1

To opt-out again, the --no-system flag can be used in any uv invocation.

4.6 KiB Raw Blame History