Update reference documentation for PEP 735 (#8567)

Updates the CLI and setting documentation to reflect the PEP 735
changes.
This commit is contained in:
Zanie Blue 2024-10-25 13:15:32 -05:00
parent 07b6887c08
commit 8262e91e2f
4 changed files with 130 additions and 68 deletions

View file

@ -2596,34 +2596,38 @@ pub struct RunArgs {
#[arg(long, overrides_with("all_extras"), hide = true)]
pub no_all_extras: bool,
/// Include development dependencies.
/// Include the development dependency group.
///
/// Development dependencies are defined via `tool.uv.dev-dependencies` in a
/// `pyproject.toml`.
/// Development dependencies are defined via `dependency-groups.dev` or
/// `tool.uv.dev-dependencies` in a `pyproject.toml`.
///
/// This option is an alias for `--group dev`.
///
/// This option is only available when running in a project.
#[arg(long, overrides_with("no_dev"), hide = true)]
pub dev: bool,
/// Omit development dependencies.
/// Omit the development dependency group.
///
/// This option is an alias of `--no-group dev`.
///
/// This option is only available when running in a project.
#[arg(long, overrides_with("dev"))]
pub no_dev: bool,
/// Include dependencies from the specified local dependency group.
/// Include dependencies from the specified dependency group.
///
/// May be provided multiple times.
#[arg(long, conflicts_with("only_group"))]
pub group: Vec<GroupName>,
/// Exclude dependencies from the specified local dependency group.
/// Exclude dependencies from the specified dependency group.
///
/// May be provided multiple times.
#[arg(long)]
pub no_group: Vec<GroupName>,
/// Only include dependencies from the specified local dependency group.
/// Only include dependencies from the specified dependency group.
///
/// May be provided multiple times.
///
@ -2637,9 +2641,11 @@ pub struct RunArgs {
#[arg(short, long, conflicts_with = "script")]
pub module: bool,
/// Omit non-development dependencies.
/// Only include the development dependency group.
///
/// The project itself will also be omitted.
/// Omit other dependencies. The project itself will also be omitted.
///
/// This option is an alias for `--only-group dev`.
#[arg(long, conflicts_with("no_dev"))]
pub only_dev: bool,
@ -2794,33 +2800,39 @@ pub struct SyncArgs {
#[arg(long, overrides_with("all_extras"), hide = true)]
pub no_all_extras: bool,
/// Include development dependencies.
/// Include the development dependency group.
///
/// This option is an alias for `--group dev`.
#[arg(long, overrides_with("no_dev"), hide = true)]
pub dev: bool,
/// Omit development dependencies.
/// Omit the development dependency group.
///
/// This option is an alias for `--no-group dev`.
#[arg(long, overrides_with("dev"))]
pub no_dev: bool,
/// Omit non-development dependencies.
/// Only include the development dependency group.
///
/// The project itself will also be omitted.
/// Omit other dependencies. The project itself will also be omitted.
///
/// This option is an alias for `--only-group dev`.
#[arg(long, conflicts_with("no_dev"))]
pub only_dev: bool,
/// Include dependencies from the specified local dependency group.
/// Include dependencies from the specified dependency group.
///
/// May be provided multiple times.
#[arg(long, conflicts_with("only_group"))]
pub group: Vec<GroupName>,
/// Exclude dependencies from the specified local dependency group.
/// Exclude dependencies from the specified dependency group.
///
/// May be provided multiple times.
#[arg(long)]
pub no_group: Vec<GroupName>,
/// Only include dependencies from the specified local dependency group.
/// Only include dependencies from the specified dependency group.
///
/// May be provided multiple times.
///
@ -2992,7 +3004,9 @@ pub struct AddArgs {
#[arg(long, short, group = "sources", value_parser = parse_file_path)]
pub requirements: Vec<PathBuf>,
/// Add the requirements as development dependencies.
/// Add the requirements to the development dependency group.
///
/// This option is an alias for `--group dev`.
#[arg(long, conflicts_with("optional"), conflicts_with("group"))]
pub dev: bool,
@ -3005,7 +3019,7 @@ pub struct AddArgs {
#[arg(long, conflicts_with("dev"), conflicts_with("group"))]
pub optional: Option<ExtraName>,
/// Add the requirements to the specified local dependency group.
/// Add the requirements to the specified dependency group.
///
/// These requirements will not be included in the published metadata for the project.
#[arg(long, conflicts_with("dev"), conflicts_with("optional"))]
@ -3114,7 +3128,9 @@ pub struct RemoveArgs {
#[arg(required = true)]
pub packages: Vec<PackageName>,
/// Remove the packages from the development dependencies.
/// Remove the packages from the development dependency group.
///
/// This option is an alias for `--group dev`.
#[arg(long, conflicts_with("optional"), conflicts_with("group"))]
pub dev: bool,
@ -3122,7 +3138,7 @@ pub struct RemoveArgs {
#[arg(long, conflicts_with("dev"), conflicts_with("group"))]
pub optional: Option<ExtraName>,
/// Remove the packages from the specified local dependency group.
/// Remove the packages from the specified dependency group.
#[arg(long, conflicts_with("dev"), conflicts_with("optional"))]
pub group: Option<GroupName>,
@ -3194,36 +3210,42 @@ pub struct TreeArgs {
#[command(flatten)]
pub tree: DisplayTreeArgs,
/// Include development dependencies.
/// Include the development dependency group.
///
/// Development dependencies are defined via `tool.uv.dev-dependencies` in a
/// `pyproject.toml`.
/// Development dependencies are defined via `dependency-groups.dev` or
/// `tool.uv.dev-dependencies` in a `pyproject.toml`.
///
/// This option is an alias for `--group dev`.
#[arg(long, overrides_with("no_dev"), hide = true)]
pub dev: bool,
/// Omit non-development dependencies.
/// Only include the development dependency group.
///
/// The project itself will also be omitted.
/// Omit other dependencies. The project itself will also be omitted.
///
/// This option is an alias for `--only-group dev`.
#[arg(long, conflicts_with("no_dev"))]
pub only_dev: bool,
/// Omit development dependencies.
/// Omit the development dependency group.
///
/// This option is an alias for `--no-group dev`.
#[arg(long, overrides_with("dev"), conflicts_with = "invert")]
pub no_dev: bool,
/// Include dependencies from the specified local dependency group.
/// Include dependencies from the specified dependency group.
///
/// May be provided multiple times.
#[arg(long, conflicts_with("only_group"))]
pub group: Vec<GroupName>,
/// Exclude dependencies from the specified local dependency group.
/// Exclude dependencies from the specified dependency group.
///
/// May be provided multiple times.
#[arg(long)]
pub no_group: Vec<GroupName>,
/// Only include dependencies from the specified local dependency group.
/// Only include dependencies from the specified dependency group.
///
/// May be provided multiple times.
///
@ -3318,33 +3340,39 @@ pub struct ExportArgs {
#[arg(long, overrides_with("all_extras"), hide = true)]
pub no_all_extras: bool,
/// Include development dependencies.
/// Include the development dependency group.
///
/// This option is an alias for `--group dev`.
#[arg(long, overrides_with("no_dev"), hide = true)]
pub dev: bool,
/// Omit development dependencies.
/// Omit the development dependency group.
///
/// This option is an alias for `--no-group dev`.
#[arg(long, overrides_with("dev"))]
pub no_dev: bool,
/// Omit non-development dependencies.
/// Only include the development dependency group.
///
/// The project itself will also be omitted.
/// Omit other dependencies. The project itself will also be omitted.
///
/// This option is an alias for `--only-group dev`.
#[arg(long, conflicts_with("no_dev"))]
pub only_dev: bool,
/// Include dependencies from the specified local dependency group.
/// Include dependencies from the specified dependency group.
///
/// May be provided multiple times.
#[arg(long, conflicts_with("only_group"))]
pub group: Vec<GroupName>,
/// Exclude dependencies from the specified local dependency group.
/// Exclude dependencies from the specified dependency group.
///
/// May be provided multiple times.
#[arg(long)]
pub no_group: Vec<GroupName>,
/// Only include dependencies from the specified local dependency group.
/// Only include dependencies from the specified dependency group.
///
/// May be provided multiple times.
///

View file

@ -323,8 +323,15 @@ pub struct ToolUv {
)]
pub default_groups: Option<Vec<GroupName>>,
/// The project's development dependencies. Development dependencies will be installed by
/// default in `uv run` and `uv sync`, but will not appear in the project's published metadata.
/// The project's development dependencies.
///
/// Development dependencies will be installed by default in `uv run` and `uv sync`, but will
/// not appear in the project's published metadata.
///
/// Use of this field is not recommend anymore. Instead, use the `dependency-groups.dev` field
/// which is a standardized way to declare development dependencies. The contents of
/// `tool.uv.dev-dependencies` and `dependency-groups.dev` are combined to determine the the
/// final requirements of the `dev` dependency group.
#[cfg_attr(
feature = "schemars",
schemars(

View file

@ -163,7 +163,7 @@ uv run [OPTIONS] [COMMAND]
<p>Instead of checking if the lockfile is up-to-date, uses the versions in the lockfile as the source of truth. If the lockfile is missing, uv will exit with an error. If the <code>pyproject.toml</code> includes changes to dependencies that have not been included in the lockfile yet, they will not be present in the environment.</p>
<p>May also be set with the <code>UV_FROZEN</code> environment variable.</p>
</dd><dt><code>--group</code> <i>group</i></dt><dd><p>Include dependencies from the specified local dependency group.</p>
</dd><dt><code>--group</code> <i>group</i></dt><dd><p>Include dependencies from the specified dependency group.</p>
<p>May be provided multiple times.</p>
@ -280,13 +280,15 @@ uv run [OPTIONS] [COMMAND]
<p>Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.</p>
<p>May also be set with the <code>UV_NO_CONFIG</code> environment variable.</p>
</dd><dt><code>--no-dev</code></dt><dd><p>Omit development dependencies.</p>
</dd><dt><code>--no-dev</code></dt><dd><p>Omit the development dependency group.</p>
<p>This option is an alias of <code>--no-group dev</code>.</p>
<p>This option is only available when running in a project.</p>
</dd><dt><code>--no-editable</code></dt><dd><p>Install any editable dependencies, including the project and any workspace members, as non-editable</p>
</dd><dt><code>--no-group</code> <i>no-group</i></dt><dd><p>Exclude dependencies from the specified local dependency group.</p>
</dd><dt><code>--no-group</code> <i>no-group</i></dt><dd><p>Exclude dependencies from the specified dependency group.</p>
<p>May be provided multiple times.</p>
@ -315,11 +317,13 @@ uv run [OPTIONS] [COMMAND]
<p>When disabled, uv will only use locally cached data and locally available files.</p>
</dd><dt><code>--only-dev</code></dt><dd><p>Omit non-development dependencies.</p>
</dd><dt><code>--only-dev</code></dt><dd><p>Only include the development dependency group.</p>
<p>The project itself will also be omitted.</p>
<p>Omit other dependencies. The project itself will also be omitted.</p>
</dd><dt><code>--only-group</code> <i>only-group</i></dt><dd><p>Only include dependencies from the specified local dependency group.</p>
<p>This option is an alias for <code>--only-group dev</code>.</p>
</dd><dt><code>--only-group</code> <i>only-group</i></dt><dd><p>Only include dependencies from the specified dependency group.</p>
<p>May be provided multiple times.</p>
@ -728,7 +732,9 @@ uv add [OPTIONS] <PACKAGES|--requirements <REQUIREMENTS>>
<p>The index given by this flag is given lower priority than all other indexes specified via the <code>--index</code> flag.</p>
<p>May also be set with the <code>UV_DEFAULT_INDEX</code> environment variable.</p>
</dd><dt><code>--dev</code></dt><dd><p>Add the requirements as development dependencies</p>
</dd><dt><code>--dev</code></dt><dd><p>Add the requirements to the development dependency group.</p>
<p>This option is an alias for <code>--group dev</code>.</p>
</dd><dt><code>--directory</code> <i>directory</i></dt><dd><p>Change to the given directory prior to running the command.</p>
@ -768,7 +774,7 @@ uv add [OPTIONS] <PACKAGES|--requirements <REQUIREMENTS>>
<p>The project environment will not be synced.</p>
<p>May also be set with the <code>UV_FROZEN</code> environment variable.</p>
</dd><dt><code>--group</code> <i>group</i></dt><dd><p>Add the requirements to the specified local dependency group.</p>
</dd><dt><code>--group</code> <i>group</i></dt><dd><p>Add the requirements to the specified dependency group.</p>
<p>These requirements will not be included in the published metadata for the project.</p>
@ -1074,7 +1080,9 @@ uv remove [OPTIONS] <PACKAGES>...
<p>The index given by this flag is given lower priority than all other indexes specified via the <code>--index</code> flag.</p>
<p>May also be set with the <code>UV_DEFAULT_INDEX</code> environment variable.</p>
</dd><dt><code>--dev</code></dt><dd><p>Remove the packages from the development dependencies</p>
</dd><dt><code>--dev</code></dt><dd><p>Remove the packages from the development dependency group.</p>
<p>This option is an alias for <code>--group dev</code>.</p>
</dd><dt><code>--directory</code> <i>directory</i></dt><dd><p>Change to the given directory prior to running the command.</p>
@ -1106,7 +1114,7 @@ uv remove [OPTIONS] <PACKAGES>...
<p>The project environment will not be synced.</p>
<p>May also be set with the <code>UV_FROZEN</code> environment variable.</p>
</dd><dt><code>--group</code> <i>group</i></dt><dd><p>Remove the packages from the specified local dependency group</p>
</dd><dt><code>--group</code> <i>group</i></dt><dd><p>Remove the packages from the specified dependency group</p>
</dd><dt><code>--help</code>, <code>-h</code></dt><dd><p>Display the concise help for this command</p>
@ -1430,7 +1438,7 @@ uv sync [OPTIONS]
<p>Instead of checking if the lockfile is up-to-date, uses the versions in the lockfile as the source of truth. If the lockfile is missing, uv will exit with an error. If the <code>pyproject.toml</code> includes changes to dependencies that have not been included in the lockfile yet, they will not be present in the environment.</p>
<p>May also be set with the <code>UV_FROZEN</code> environment variable.</p>
</dd><dt><code>--group</code> <i>group</i></dt><dd><p>Include dependencies from the specified local dependency group.</p>
</dd><dt><code>--group</code> <i>group</i></dt><dd><p>Include dependencies from the specified dependency group.</p>
<p>May be provided multiple times.</p>
@ -1539,11 +1547,13 @@ uv sync [OPTIONS]
<p>Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.</p>
<p>May also be set with the <code>UV_NO_CONFIG</code> environment variable.</p>
</dd><dt><code>--no-dev</code></dt><dd><p>Omit development dependencies</p>
</dd><dt><code>--no-dev</code></dt><dd><p>Omit the development dependency group.</p>
<p>This option is an alias for <code>--no-group dev</code>.</p>
</dd><dt><code>--no-editable</code></dt><dd><p>Install any editable dependencies, including the project and any workspace members, as non-editable</p>
</dd><dt><code>--no-group</code> <i>no-group</i></dt><dd><p>Exclude dependencies from the specified local dependency group.</p>
</dd><dt><code>--no-group</code> <i>no-group</i></dt><dd><p>Exclude dependencies from the specified dependency group.</p>
<p>May be provided multiple times.</p>
@ -1573,11 +1583,13 @@ uv sync [OPTIONS]
<p>When disabled, uv will only use locally cached data and locally available files.</p>
</dd><dt><code>--only-dev</code></dt><dd><p>Omit non-development dependencies.</p>
</dd><dt><code>--only-dev</code></dt><dd><p>Only include the development dependency group.</p>
<p>The project itself will also be omitted.</p>
<p>Omit other dependencies. The project itself will also be omitted.</p>
</dd><dt><code>--only-group</code> <i>only-group</i></dt><dd><p>Only include dependencies from the specified local dependency group.</p>
<p>This option is an alias for <code>--only-group dev</code>.</p>
</dd><dt><code>--only-group</code> <i>only-group</i></dt><dd><p>Only include dependencies from the specified dependency group.</p>
<p>May be provided multiple times.</p>
@ -2074,7 +2086,7 @@ uv export [OPTIONS]
<p>If a <code>uv.lock</code> does not exist, uv will exit with an error.</p>
<p>May also be set with the <code>UV_FROZEN</code> environment variable.</p>
</dd><dt><code>--group</code> <i>group</i></dt><dd><p>Include dependencies from the specified local dependency group.</p>
</dd><dt><code>--group</code> <i>group</i></dt><dd><p>Include dependencies from the specified dependency group.</p>
<p>May be provided multiple times.</p>
@ -2181,7 +2193,9 @@ uv export [OPTIONS]
<p>Normally, configuration files are discovered in the current directory, parent directories, or user configuration directories.</p>
<p>May also be set with the <code>UV_NO_CONFIG</code> environment variable.</p>
</dd><dt><code>--no-dev</code></dt><dd><p>Omit development dependencies</p>
</dd><dt><code>--no-dev</code></dt><dd><p>Omit the development dependency group.</p>
<p>This option is an alias for <code>--no-group dev</code>.</p>
</dd><dt><code>--no-editable</code></dt><dd><p>Install any editable dependencies, including the project and any workspace members, as non-editable</p>
@ -2197,7 +2211,7 @@ uv export [OPTIONS]
<p>By default, all workspace members and their dependencies are included in the exported requirements file, with all of their dependencies. The <code>--no-emit-workspace</code> option allows exclusion of all the workspace members while retaining their dependencies.</p>
</dd><dt><code>--no-group</code> <i>no-group</i></dt><dd><p>Exclude dependencies from the specified local dependency group.</p>
</dd><dt><code>--no-group</code> <i>no-group</i></dt><dd><p>Exclude dependencies from the specified dependency group.</p>
<p>May be provided multiple times.</p>
@ -2219,11 +2233,13 @@ uv export [OPTIONS]
<p>When disabled, uv will only use locally cached data and locally available files.</p>
</dd><dt><code>--only-dev</code></dt><dd><p>Omit non-development dependencies.</p>
</dd><dt><code>--only-dev</code></dt><dd><p>Only include the development dependency group.</p>
<p>The project itself will also be omitted.</p>
<p>Omit other dependencies. The project itself will also be omitted.</p>
</dd><dt><code>--only-group</code> <i>only-group</i></dt><dd><p>Only include dependencies from the specified local dependency group.</p>
<p>This option is an alias for <code>--only-group dev</code>.</p>
</dd><dt><code>--only-group</code> <i>only-group</i></dt><dd><p>Only include dependencies from the specified dependency group.</p>
<p>May be provided multiple times.</p>
@ -2405,7 +2421,7 @@ uv tree [OPTIONS]
<p>If the lockfile is missing, uv will exit with an error.</p>
<p>May also be set with the <code>UV_FROZEN</code> environment variable.</p>
</dd><dt><code>--group</code> <i>group</i></dt><dd><p>Include dependencies from the specified local dependency group.</p>
</dd><dt><code>--group</code> <i>group</i></dt><dd><p>Include dependencies from the specified dependency group.</p>
<p>May be provided multiple times.</p>
@ -2516,9 +2532,11 @@ uv tree [OPTIONS]
<p>May also be set with the <code>UV_NO_CONFIG</code> environment variable.</p>
</dd><dt><code>--no-dedupe</code></dt><dd><p>Do not de-duplicate repeated dependencies. Usually, when a package has already displayed its dependencies, further occurrences will not re-display its dependencies, and will include a (*) to indicate it has already been shown. This flag will cause those duplicates to be repeated</p>
</dd><dt><code>--no-dev</code></dt><dd><p>Omit development dependencies</p>
</dd><dt><code>--no-dev</code></dt><dd><p>Omit the development dependency group.</p>
</dd><dt><code>--no-group</code> <i>no-group</i></dt><dd><p>Exclude dependencies from the specified local dependency group.</p>
<p>This option is an alias for <code>--no-group dev</code>.</p>
</dd><dt><code>--no-group</code> <i>no-group</i></dt><dd><p>Exclude dependencies from the specified dependency group.</p>
<p>May be provided multiple times.</p>
@ -2536,11 +2554,13 @@ uv tree [OPTIONS]
<p>When disabled, uv will only use locally cached data and locally available files.</p>
</dd><dt><code>--only-dev</code></dt><dd><p>Omit non-development dependencies.</p>
</dd><dt><code>--only-dev</code></dt><dd><p>Only include the development dependency group.</p>
<p>The project itself will also be omitted.</p>
<p>Omit other dependencies. The project itself will also be omitted.</p>
</dd><dt><code>--only-group</code> <i>only-group</i></dt><dd><p>Only include dependencies from the specified local dependency group.</p>
<p>This option is an alias for <code>--only-group dev</code>.</p>
</dd><dt><code>--only-group</code> <i>only-group</i></dt><dd><p>Only include dependencies from the specified dependency group.</p>
<p>May be provided multiple times.</p>

View file

@ -49,8 +49,15 @@ default-groups = ["docs"]
### [`dev-dependencies`](#dev-dependencies) {: #dev-dependencies }
The project's development dependencies. Development dependencies will be installed by
default in `uv run` and `uv sync`, but will not appear in the project's published metadata.
The project's development dependencies.
Development dependencies will be installed by default in `uv run` and `uv sync`, but will
not appear in the project's published metadata.
Use of this field is not recommend anymore. Instead, use the `dependency-groups.dev` field
which is a standardized way to declare development dependencies. The contents of
`tool.uv.dev-dependencies` and `dependency-groups.dev` are combined to determine the the
final requirements of the `dev` dependency group.
**Default value**: `[]`