Skip to content

uv Helpers

These helpers wrap the uv pip commands most often used in nox session bootstrap. They are designed to compose cleanly: start with setup_uv() for the common case, then drop to the lower-level helpers when you need more control over how requirement files are compiled or installed.

liblaf.nox_recipes.Resolution

Bases: StrEnum


              flowchart TD
              liblaf.nox_recipes.Resolution[Resolution]

              

              click liblaf.nox_recipes.Resolution href "" "liblaf.nox_recipes.Resolution"

Dependency resolution strategies supported by uv pip.

Attributes:

  • HIGHEST –

    Prefer the newest compatible versions.

  • LOWEST –

    Prefer the oldest compatible versions across the graph.

  • LOWEST_DIRECT –

    Prefer the oldest compatible versions for direct dependencies while still allowing newer transitive requirements when needed.

HIGHEST class-attribute instance-attribute 

HIGHEST = 'highest'

LOWEST class-attribute instance-attribute 

LOWEST = 'lowest'

LOWEST_DIRECT class-attribute instance-attribute 

LOWEST_DIRECT = 'lowest-direct'

liblaf.nox_recipes.setup_uv 

setup_uv(
    s: Session,
    *,
    extras: Iterable[str] = (),
    all_extras: bool = False,
    groups: Iterable[str] = (),
    resolution: Resolution | None = None,
    quiet: bool = True,
) -> None

Create and sync a session environment from pyproject.toml.

setup_uv() is the high-level helper for most projects. It compiles a constraints file, compiles the requested requirements against those constraints, syncs the session environment, and finally installs the current project in editable mode.

Parameters:

  • s

    (Session) –

    The active nox session.

  • extras

    (Iterable[str], default: () ) –

    Project extras to include while compiling and installing.

  • all_extras

    (bool, default: False ) –

    Whether to include every defined extra.

  • groups

    (Iterable[str], default: () ) –

    Dependency groups to include when compiling the session requirements.

  • resolution

    (Resolution | None, default: None ) –

    Optional dependency resolution strategy for the initial constraints compile.

  • quiet

    (bool, default: True ) –

    Whether to ask uv for quieter output.

Source code in src/liblaf/nox_recipes/_uv.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
def setup_uv(
    s: nox.Session,
    *,
    extras: Iterable[str] = (),
    all_extras: bool = False,
    groups: Iterable[str] = (),
    resolution: Resolution | None = None,
    quiet: bool = True,
) -> None:
    """Create and sync a session environment from `pyproject.toml`.

    `setup_uv()` is the high-level helper for most projects. It compiles a
    constraints file, compiles the requested requirements against those
    constraints, syncs the session environment, and finally installs the current
    project in editable mode.

    Args:
        s:
            The active `nox` session.
        extras:
            Project extras to include while compiling and installing.
        all_extras:
            Whether to include every defined extra.
        groups:
            Dependency groups to include when compiling the session
            requirements.
        resolution:
            Optional dependency resolution strategy for the initial constraints
            compile.
        quiet:
            Whether to ask `uv` for quieter output.
    """
    with tempfile.TemporaryDirectory() as tmpdir_str:
        tmpdir: Path = Path(tmpdir_str)
        constraints: Path = tmpdir / "constraints.txt"
        requirements: Path = tmpdir / "requirements.txt"
        uv_pip_compile(
            s,
            extras=extras,
            all_extras=all_extras,
            output_file=constraints,
            resolution=resolution,
            quiet=quiet,
        )
        uv_pip_compile(
            s,
            constraints=[constraints],
            extras=extras,
            all_extras=all_extras,
            groups=groups,
            output_file=requirements,
            quiet=quiet,
        )
        uv_pip_sync(s, requirements, quiet=quiet)
    uv_pip_install(s, editables=["."], no_deps=True, quiet=quiet)

liblaf.nox_recipes.uv_pip_compile 

uv_pip_compile(
    s: Session,
    *options: StrPath,
    constraints: Iterable[StrPath] = (),
    extras: Iterable[str] = (),
    all_extras: bool = False,
    groups: Iterable[str] = (),
    output_file: StrPath | None = None,
    resolution: Resolution | None = None,
    quiet: bool = True,
) -> None

Run uv pip compile against the current project's pyproject.toml.

Parameters:

  • s

    (Session) –

    The active nox session.

  • *options

    (StrPath, default: () ) –

    Additional command-line options appended before pyproject.toml.

  • constraints

    (Iterable[StrPath], default: () ) –

    Compiled requirement files passed with --constraints.

  • extras

    (Iterable[str], default: () ) –

    Project extras enabled during compilation.

  • all_extras

    (bool, default: False ) –

    Whether to enable every defined extra.

  • groups

    (Iterable[str], default: () ) –

    Dependency groups enabled during compilation.

  • output_file

    (StrPath | None, default: None ) –

    Optional destination file passed with --output-file.

  • resolution

    (Resolution | None, default: None ) –

    Optional dependency resolution strategy for uv.

  • quiet

    (bool, default: True ) –

    Whether to ask uv for quieter output.

Source code in src/liblaf/nox_recipes/_uv.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
def uv_pip_compile(
    s: nox.Session,
    *options: StrPath,
    constraints: Iterable[StrPath] = (),
    extras: Iterable[str] = (),
    all_extras: bool = False,
    groups: Iterable[str] = (),
    output_file: StrPath | None = None,
    resolution: Resolution | None = None,
    quiet: bool = True,
) -> None:
    """Run `uv pip compile` against the current project's `pyproject.toml`.

    Args:
        s:
            The active `nox` session.
        *options:
            Additional command-line options appended before `pyproject.toml`.
        constraints:
            Compiled requirement files passed with `--constraints`.
        extras:
            Project extras enabled during compilation.
        all_extras:
            Whether to enable every defined extra.
        groups:
            Dependency groups enabled during compilation.
        output_file:
            Optional destination file passed with `--output-file`.
        resolution:
            Optional dependency resolution strategy for `uv`.
        quiet:
            Whether to ask `uv` for quieter output.
    """
    args: list[StrPath] = ["uv", "pip", "compile"]
    for constraint in constraints:
        args.extend(("--constraints", constraint))
    for extra in extras:
        args.extend(("--extra", extra))
    if all_extras:
        args.append("--all-extras")
    for group in groups:
        args.extend(("--group", group))
    if output_file:
        args.extend(("--output-file", output_file))
    args.extend(("--generate-hashes", "--emit-index-url", "--emit-index-annotation"))
    if resolution:
        args.extend(("--resolution", resolution))
    if isinstance(s.python, str):
        args.extend(("--python-version", s.python))
    if quiet:
        args.append("--quiet")
    args.extend(options)
    args.append("pyproject.toml")
    s.run_install(*args, external=True)

liblaf.nox_recipes.uv_pip_sync 

uv_pip_sync(
    s: Session, *src_files: StrPath, quiet: bool = True
) -> None

Run uv pip sync for one or more compiled requirement files.

Parameters:

  • s

    (Session) –

    The active nox session.

  • *src_files

    (StrPath, default: () ) –

    Requirement files consumed by uv pip sync.

  • quiet

    (bool, default: True ) –

    Whether to ask uv for quieter output.

Source code in src/liblaf/nox_recipes/_uv.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
def uv_pip_sync(s: nox.Session, *src_files: StrPath, quiet: bool = True) -> None:
    """Run `uv pip sync` for one or more compiled requirement files.

    Args:
        s:
            The active `nox` session.
        *src_files:
            Requirement files consumed by `uv pip sync`.
        quiet:
            Whether to ask `uv` for quieter output.
    """
    args: list[StrPath] = ["uv", "pip", "sync"]
    if isinstance(s.python, str):
        args.extend(("--python-version", s.python))
    args.append("--strict")
    if quiet:
        args.append("--quiet")
    args.extend(src_files)
    s.run_install(*args, external=True)

liblaf.nox_recipes.uv_pip_install 

uv_pip_install(
    s: Session,
    *options: StrPath,
    constraints: Iterable[StrPath] = (),
    editables: Iterable[str] = (),
    extras: Iterable[str] = (),
    all_extras: bool = False,
    groups: Iterable[str] = (),
    no_deps: bool = False,
    resolution: Resolution | None = None,
    quiet: bool = True,
) -> None

Run uv pip install with session-oriented defaults.

Parameters:

  • s

    (Session) –

    The active nox session.

  • *options

    (StrPath, default: () ) –

    Additional command-line options forwarded to uv pip install.

  • constraints

    (Iterable[StrPath], default: () ) –

    Compiled requirement files passed with --constraints.

  • editables

    (Iterable[str], default: () ) –

    Editable paths installed with --editable.

  • extras

    (Iterable[str], default: () ) –

    Project extras enabled during installation.

  • all_extras

    (bool, default: False ) –

    Whether to enable every defined extra.

  • groups

    (Iterable[str], default: () ) –

    Dependency groups enabled during installation.

  • no_deps

    (bool, default: False ) –

    Whether to pass --no-deps.

  • resolution

    (Resolution | None, default: None ) –

    Optional dependency resolution strategy for uv.

  • quiet

    (bool, default: True ) –

    Whether to ask uv for quieter output.

Source code in src/liblaf/nox_recipes/_uv.py 
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
def uv_pip_install(
    s: nox.Session,
    *options: StrPath,
    constraints: Iterable[StrPath] = (),
    editables: Iterable[str] = (),
    extras: Iterable[str] = (),
    all_extras: bool = False,
    groups: Iterable[str] = (),
    no_deps: bool = False,
    resolution: Resolution | None = None,
    quiet: bool = True,
) -> None:
    """Run `uv pip install` with session-oriented defaults.

    Args:
        s:
            The active `nox` session.
        *options:
            Additional command-line options forwarded to `uv pip install`.
        constraints:
            Compiled requirement files passed with `--constraints`.
        editables:
            Editable paths installed with `--editable`.
        extras:
            Project extras enabled during installation.
        all_extras:
            Whether to enable every defined extra.
        groups:
            Dependency groups enabled during installation.
        no_deps:
            Whether to pass `--no-deps`.
        resolution:
            Optional dependency resolution strategy for `uv`.
        quiet:
            Whether to ask `uv` for quieter output.
    """
    args: list[StrPath] = ["uv", "pip", "install"]
    for constraint in constraints:
        args.extend(("--constraints", constraint))
    for extra in extras:
        args.extend(("--extra", extra))
    if all_extras:
        args.append("--all-extras")
    if no_deps:
        args.append("--no-deps")
    if resolution:
        args.extend(("--resolution", resolution))
    if quiet:
        args.append("--quiet")
    for editable in editables:
        args.extend(("--editable", editable))
    for group in groups:
        args.extend(("--group", group))
    args.extend(options)
    s.run_install(*args, external=True)