projen
Version:
CDK for software projects
1,316 lines • 67.8 kB
TypeScript
/**
* Metadata and configuration for uv.
*
* @schema UvConfiguration
*/
export interface UvConfiguration {
/**
* The default version specifier when adding a dependency.
*
* When adding a dependency to the project, if no constraint or URL is provided, a constraint
* is added based on the latest compatible version of the package. By default, a lower bound
* constraint is used, e.g., `>=1.2.3`.
*
* When `--frozen` is provided, no resolution is performed, and dependencies are always added
* without constraints.
*
* This option is in preview and may change in any future release.
*
* @schema UvConfiguration#add-bounds
*/
readonly addBounds?: string;
/**
* Allow insecure connections to host.
*
* Expects to receive either a hostname (e.g., `localhost`), a host-port pair (e.g.,
* `localhost:8080`), or a URL (e.g., `https://localhost`).
*
* WARNING: Hosts included in this list will not be verified against the system's certificate
* store. Only use `--allow-insecure-host` in a secure network with verified sources, as it
* bypasses SSL verification and could expose you to MITM attacks.
*
* @schema UvConfiguration#allow-insecure-host
*/
readonly allowInsecureHost?: string[];
/**
* Configuration for the uv build backend.
*
* Note that those settings only apply when using the `uv_build` backend, other build backends
* (such as hatchling) have their own configuration.
*
* @schema UvConfiguration#build-backend
*/
readonly buildBackend?: BuildBackendSettings;
/**
* PEP 508-style requirements, e.g., `ruff==0.5.0`, or `ruff @ https://...`.
*
* @schema UvConfiguration#build-constraint-dependencies
*/
readonly buildConstraintDependencies?: string[];
/**
* Path to the cache directory.
*
* @schema UvConfiguration#cache-dir
*/
readonly cacheDir?: string;
/**
* The keys to consider when caching builds for the project.
*
* Cache keys enable you to specify the files or directories that should trigger a rebuild when
* modified. By default, uv will rebuild a project whenever the `pyproject.toml`, `setup.py`,
* or `setup.cfg` files in the project directory are modified, or if a `src` directory is
* added or removed, i.e.:
*
* ```toml
* cache-keys = [{ file = "pyproject.toml" }, { file = "setup.py" }, { file = "setup.cfg" }, { dir = "src" }]
* ```
*
* As an example: if a project uses dynamic metadata to read its dependencies from a
* `requirements.txt` file, you can specify `cache-keys = [{ file = "requirements.txt" }, { file = "pyproject.toml" }]`
* to ensure that the project is rebuilt whenever the `requirements.txt` file is modified (in
* addition to watching the `pyproject.toml`).
*
* Globs are supported, following the syntax of the [`glob`](https://docs.rs/glob/0.3.1/glob/struct.Pattern.html)
* crate. For example, to invalidate the cache whenever a `.toml` file in the project directory
* or any of its subdirectories is modified, you can specify `cache-keys = [{ file = "*_/*.toml" }]`.
* Note that the use of globs can be expensive, as uv may need to walk the filesystem to
* determine whether any files have changed.
*
* Cache keys can also include version control information. For example, if a project uses
* `setuptools_scm` to read its version from a Git commit, you can specify `cache-keys = [{ git = { commit = true }, { file = "pyproject.toml" }]`
* to include the current Git commit hash in the cache key (in addition to the
* `pyproject.toml`). Git tags are also supported via `cache-keys = [{ git = { commit = true, tags = true } }]`.
*
* Cache keys can also include environment variables. For example, if a project relies on
* `MACOSX_DEPLOYMENT_TARGET` or other environment variables to determine its behavior, you can
* specify `cache-keys = [{ env = "MACOSX_DEPLOYMENT_TARGET" }]` to invalidate the cache
* whenever the environment variable changes.
*
* Cache keys only affect the project defined by the `pyproject.toml` in which they're
* specified (as opposed to, e.g., affecting all members in a workspace), and all paths and
* globs are interpreted as relative to the project directory.
*
* @schema UvConfiguration#cache-keys
*/
readonly cacheKeys?: any[];
/**
* Check an index URL for existing files to skip duplicate uploads.
*
* This option allows retrying publishing that failed after only some, but not all files have
* been uploaded, and handles error due to parallel uploads of the same file.
*
* Before uploading, the index is checked. If the exact same file already exists in the index,
* the file will not be uploaded. If an error occurred during the upload, the index is checked
* again, to handle cases where the identical file was uploaded twice in parallel.
*
* The exact behavior will vary based on the index. When uploading to PyPI, uploading the same
* file succeeds even without `--check-url`, while most other indexes error.
*
* The index must provide one of the supported hashes (SHA-256, SHA-384, or SHA-512).
*
* @schema UvConfiguration#check-url
*/
readonly checkUrl?: string;
/**
* Compile Python files to bytecode after installation.
*
* By default, uv does not compile Python (`.py`) files to bytecode (`__pycache__/*.pyc`);
* instead, compilation is performed lazily the first time a module is imported. For use-cases
* in which start time is critical, such as CLI applications and Docker containers, this option
* can be enabled to trade longer installation times for faster start times.
*
* When enabled, uv will process the entire site-packages directory (including packages that
* are not being modified by the current operation) for consistency. Like pip, it will also
* ignore errors.
*
* @schema UvConfiguration#compile-bytecode
*/
readonly compileBytecode?: boolean;
/**
* The maximum number of source distributions that uv will build concurrently at any given
* time.
*
* Defaults to the number of available CPU cores.
*
* @default the number of available CPU cores.
* @schema UvConfiguration#concurrent-builds
*/
readonly concurrentBuilds?: number;
/**
* The maximum number of in-flight concurrent downloads that uv will perform at any given
* time.
*
* @schema UvConfiguration#concurrent-downloads
*/
readonly concurrentDownloads?: number;
/**
* The number of threads used when installing and unzipping packages.
*
* Defaults to the number of available CPU cores.
*
* @default the number of available CPU cores.
* @schema UvConfiguration#concurrent-installs
*/
readonly concurrentInstalls?: number;
/**
* Settings to pass to the [PEP 517](https://peps.python.org/pep-0517/) build backend,
* specified as `KEY=VALUE` pairs.
*
* @schema UvConfiguration#config-settings
*/
readonly configSettings?: {
[key: string]: any;
};
/**
* Settings to pass to the [PEP 517](https://peps.python.org/pep-0517/) build backend for specific packages,
* specified as `KEY=VALUE` pairs.
*
* Accepts a map from package names to string key-value pairs.
*
* @schema UvConfiguration#config-settings-package
*/
readonly configSettingsPackage?: {
[key: string]: {
[key: string]: any;
};
};
/**
* A list of sets of conflicting groups or extras.
*
* @schema UvConfiguration#conflicts
*/
readonly conflicts?: SchemaConflictItem[][];
/**
* PEP 508-style requirements, e.g., `ruff==0.5.0`, or `ruff @ https://...`.
*
* @schema UvConfiguration#constraint-dependencies
*/
readonly constraintDependencies?: string[];
/**
* The list of `dependency-groups` to install by default.
*
* Can also be the literal `"all"` to default enable all groups.
*
* @schema UvConfiguration#default-groups
*/
readonly defaultGroups?: any;
/**
* Additional settings for `dependency-groups`.
*
* Currently this can only be used to add `requires-python` constraints
* to dependency groups (typically to inform uv that your dev tooling
* has a higher python requirement than your actual project).
*
* This cannot be used to define dependency groups, use the top-level
* `[dependency-groups]` table for that.
*
* @schema UvConfiguration#dependency-groups
*/
readonly dependencyGroups?: {
[key: string]: DependencyGroupSettings;
};
/**
* Pre-defined static metadata for dependencies of the project (direct or transitive). When
* provided, enables the resolver to use the specified metadata instead of querying the
* registry or building the relevant package from source.
*
* Metadata should be provided in adherence with the [Metadata 2.3](https://packaging.python.org/en/latest/specifications/core-metadata/)
* standard, though only the following fields are respected:
*
* - `name`: The name of the package.
* - (Optional) `version`: The version of the package. If omitted, the metadata will be applied
* to all versions of the package.
* - (Optional) `requires-dist`: The dependencies of the package (e.g., `werkzeug>=0.14`).
* - (Optional) `requires-python`: The Python version required by the package (e.g., `>=3.10`).
* - (Optional) `provides-extra`: The extras provided by the package.
*
* @schema UvConfiguration#dependency-metadata
*/
readonly dependencyMetadata?: StaticMetadata[];
/**
* PEP 508-style requirements, e.g., `ruff==0.5.0`, or `ruff @ https://...`.
*
* @schema UvConfiguration#dev-dependencies
*/
readonly devDependencies?: string[];
/**
* A list of environment markers, e.g., `python_version >= '3.6'`.
*
* @schema UvConfiguration#environments
*/
readonly environments?: string[];
/**
* Package names to exclude, e.g., `werkzeug`, `numpy`.
*
* @schema UvConfiguration#exclude-dependencies
*/
readonly excludeDependencies?: string[];
/**
* Limit candidate packages to those that were uploaded prior to a given point in time.
*
* Accepts a superset of [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) (e.g.,
* `2006-12-02T02:07:43Z`). A full timestamp is required to ensure that the resolver will
* behave consistently across timezones.
*
* @schema UvConfiguration#exclude-newer
*/
readonly excludeNewer?: string;
/**
* Limit candidate packages for specific packages to those that were uploaded prior to the given date.
*
* Accepts package-date pairs in a dictionary format.
*
* @schema UvConfiguration#exclude-newer-package
*/
readonly excludeNewerPackage?: {
[key: string]: string;
};
/**
* Additional build dependencies for packages.
*
* This allows extending the PEP 517 build environment for the project's dependencies with
* additional packages. This is useful for packages that assume the presence of packages like
* `pip`, and do not declare them as build dependencies.
*
* @schema UvConfiguration#extra-build-dependencies
*/
readonly extraBuildDependencies?: {
[key: string]: any[];
};
/**
* Extra environment variables to set when building certain packages.
*
* Environment variables will be added to the environment when building the
* specified packages.
*
* @schema UvConfiguration#extra-build-variables
*/
readonly extraBuildVariables?: {
[key: string]: {
[key: string]: string;
};
};
/**
* Extra URLs of package indexes to use, in addition to `--index-url`.
*
* Accepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/)
* (the simple repository API), or a local directory laid out in the same format.
*
* All indexes provided via this flag take priority over the index specified by
* [`index_url`](#index-url) or [`index`](#index) with `default = true`. When multiple indexes
* are provided, earlier values take priority.
*
* To control uv's resolution strategy when multiple indexes are present, see
* [`index_strategy`](#index-strategy).
*
* (Deprecated: use `index` instead.)
*
* @schema UvConfiguration#extra-index-url
*/
readonly extraIndexUrl?: string[];
/**
* Locations to search for candidate distributions, in addition to those found in the registry
* indexes.
*
* If a path, the target must be a directory that contains packages as wheel files (`.whl`) or
* source distributions (e.g., `.tar.gz` or `.zip`) at the top level.
*
* If a URL, the page must contain a flat list of links to package files adhering to the
* formats described above.
*
* @schema UvConfiguration#find-links
*/
readonly findLinks?: string[];
/**
* The strategy to use when selecting multiple versions of a given package across Python
* versions and platforms.
*
* By default, uv will optimize for selecting the latest version of each package for each
* supported Python version (`requires-python`), while minimizing the number of selected
* versions across platforms.
*
* Under `fewest`, uv will minimize the number of selected versions for each package,
* preferring older versions that are compatible with a wider range of supported Python
* versions or platforms.
*
* @schema UvConfiguration#fork-strategy
*/
readonly forkStrategy?: string;
/**
* The indexes to use when resolving dependencies.
*
* Accepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/)
* (the simple repository API), or a local directory laid out in the same format.
*
* Indexes are considered in the order in which they're defined, such that the first-defined
* index has the highest priority. Further, the indexes provided by this setting are given
* higher priority than any indexes specified via [`index_url`](#index-url) or
* [`extra_index_url`](#extra-index-url). uv will only consider the first index that contains
* a given package, unless an alternative [index strategy](#index-strategy) is specified.
*
* If an index is marked as `explicit = true`, it will be used exclusively for the
* dependencies that select it explicitly via `[tool.uv.sources]`, as in:
*
* ```toml
* [[tool.uv.index]]
* name = "pytorch"
* url = "https://download.pytorch.org/whl/cu121"
* explicit = true
*
* [tool.uv.sources]
* torch = { index = "pytorch" }
* ```
*
* If an index is marked as `default = true`, it will be moved to the end of the prioritized list, such that it is
* given the lowest priority when resolving packages. Additionally, marking an index as default will disable the
* PyPI default index.
*
* @schema UvConfiguration#index
*/
readonly index?: Index[];
/**
* The strategy to use when resolving against multiple index URLs.
*
* By default, uv will stop at the first index on which a given package is available, and
* limit resolutions to those present on that first index (`first-index`). This prevents
* "dependency confusion" attacks, whereby an attacker can upload a malicious package under the
* same name to an alternate index.
*
* @schema UvConfiguration#index-strategy
*/
readonly indexStrategy?: string;
/**
* The URL of the Python package index (by default: <https://pypi.org/simple>).
*
* Accepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/)
* (the simple repository API), or a local directory laid out in the same format.
*
* The index provided by this setting is given lower priority than any indexes specified via
* [`extra_index_url`](#extra-index-url) or [`index`](#index).
*
* (Deprecated: use `index` instead.)
*
* @schema UvConfiguration#index-url
*/
readonly indexUrl?: string;
/**
* Attempt to use `keyring` for authentication for index URLs.
*
* At present, only `--keyring-provider subprocess` is supported, which configures uv to
* use the `keyring` CLI to handle authentication.
*
* @schema UvConfiguration#keyring-provider
*/
readonly keyringProvider?: string;
/**
* The method to use when installing packages from the global cache.
*
* Defaults to `clone` (also known as Copy-on-Write) on macOS, and `hardlink` on Linux and
* Windows.
*
* WARNING: The use of symlink link mode is discouraged, as they create tight coupling between
* the cache and the target environment. For example, clearing the cache (`uv cache clean`)
* will break all installed packages by way of removing the underlying source files. Use
* symlinks with caution.
*
* @default clone` (also known as Copy-on-Write) on macOS, and `hardlink` on Linux and
* @schema UvConfiguration#link-mode
*/
readonly linkMode?: string;
/**
* Whether the project is managed by uv. If `false`, uv will ignore the project when
* `uv run` is invoked.
*
* @schema UvConfiguration#managed
*/
readonly managed?: boolean;
/**
* Whether to load TLS certificates from the platform's native certificate store.
*
* By default, uv loads certificates from the bundled `webpki-roots` crate. The
* `webpki-roots` are a reliable set of trust roots from Mozilla, and including them in uv
* improves portability and performance (especially on macOS).
*
* However, in some cases, you may want to use the platform's native certificate store,
* especially if you're relying on a corporate trust root (e.g., for a mandatory proxy) that's
* included in your system's certificate store.
*
* @schema UvConfiguration#native-tls
*/
readonly nativeTls?: boolean;
/**
* Don't install pre-built wheels.
*
* The given packages will be built and installed from source. The resolver will still use
* pre-built wheels to extract package metadata, if available.
*
* @schema UvConfiguration#no-binary
*/
readonly noBinary?: boolean;
/**
* Don't install pre-built wheels for a specific package.
*
* @schema UvConfiguration#no-binary-package
*/
readonly noBinaryPackage?: string[];
/**
* Don't build source distributions.
*
* When enabled, resolving will not run arbitrary Python code. The cached wheels of
* already-built source distributions will be reused, but operations that require building
* distributions will exit with an error.
*
* @schema UvConfiguration#no-build
*/
readonly noBuild?: boolean;
/**
* Disable isolation when building source distributions.
*
* Assumes that build dependencies specified by [PEP 518](https://peps.python.org/pep-0518/)
* are already installed.
*
* @schema UvConfiguration#no-build-isolation
*/
readonly noBuildIsolation?: boolean;
/**
* Disable isolation when building source distributions for a specific package.
*
* Assumes that the packages' build dependencies specified by [PEP 518](https://peps.python.org/pep-0518/)
* are already installed.
*
* @schema UvConfiguration#no-build-isolation-package
*/
readonly noBuildIsolationPackage?: string[];
/**
* Don't build source distributions for a specific package.
*
* @schema UvConfiguration#no-build-package
*/
readonly noBuildPackage?: string[];
/**
* Avoid reading from or writing to the cache, instead using a temporary directory for the
* duration of the operation.
*
* @schema UvConfiguration#no-cache
*/
readonly noCache?: boolean;
/**
* Ignore all registry indexes (e.g., PyPI), instead relying on direct URL dependencies and
* those provided via `--find-links`.
*
* @schema UvConfiguration#no-index
*/
readonly noIndex?: boolean;
/**
* Ignore the `tool.uv.sources` table when resolving dependencies. Used to lock against the
* standards-compliant, publishable package metadata, as opposed to using any local or Git
* sources.
*
* @schema UvConfiguration#no-sources
*/
readonly noSources?: boolean;
/**
* Disable network access, relying only on locally cached data and locally available files.
*
* @schema UvConfiguration#offline
*/
readonly offline?: boolean;
/**
* PEP 508-style requirements, e.g., `ruff==0.5.0`, or `ruff @ https://...`.
*
* @schema UvConfiguration#override-dependencies
*/
readonly overrideDependencies?: string[];
/**
* Whether the project should be considered a Python package, or a non-package ("virtual")
* project.
*
* Packages are built and installed into the virtual environment in editable mode and thus
* require a build backend, while virtual projects are _not_ built or installed; instead, only
* their dependencies are included in the virtual environment.
*
* Creating a package requires that a `build-system` is present in the `pyproject.toml`, and
* that the project adheres to a structure that adheres to the build backend's expectations
* (e.g., a `src` layout).
*
* @schema UvConfiguration#package
*/
readonly package?: boolean;
/**
* @schema UvConfiguration#pip
*/
readonly pip?: PipOptions;
/**
* The strategy to use when considering pre-release versions.
*
* By default, uv will accept pre-releases for packages that _only_ publish pre-releases,
* along with first-party requirements that contain an explicit pre-release marker in the
* declared specifiers (`if-necessary-or-explicit`).
*
* @schema UvConfiguration#prerelease
*/
readonly prerelease?: string;
/**
* Whether to enable experimental, preview features.
*
* @schema UvConfiguration#preview
*/
readonly preview?: boolean;
/**
* The URL for publishing packages to the Python package index (by default:
* <https://upload.pypi.org/legacy/>).
*
* @schema UvConfiguration#publish-url
*/
readonly publishUrl?: string;
/**
* Mirror URL to use for downloading managed PyPy installations.
*
* By default, managed PyPy installations are downloaded from [downloads.python.org](https://downloads.python.org/).
* This variable can be set to a mirror URL to use a different source for PyPy installations.
* The provided URL will replace `https://downloads.python.org/pypy` in, e.g., `https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2`.
*
* Distributions can be read from a
* local directory by using the `file://` URL scheme.
*
* @schema UvConfiguration#pypy-install-mirror
*/
readonly pypyInstallMirror?: string;
/**
* Whether to allow Python downloads.
*
* @schema UvConfiguration#python-downloads
*/
readonly pythonDownloads?: string;
/**
* URL pointing to JSON of custom Python installations.
*
* Note that currently, only local paths are supported.
*
* @schema UvConfiguration#python-downloads-json-url
*/
readonly pythonDownloadsJsonUrl?: string;
/**
* Mirror URL for downloading managed Python installations.
*
* By default, managed Python installations are downloaded from [`python-build-standalone`](https://github.com/astral-sh/python-build-standalone).
* This variable can be set to a mirror URL to use a different source for Python installations.
* The provided URL will replace `https://github.com/astral-sh/python-build-standalone/releases/download` in, e.g., `https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz`.
*
* Distributions can be read from a local directory by using the `file://` URL scheme.
*
* @schema UvConfiguration#python-install-mirror
*/
readonly pythonInstallMirror?: string;
/**
* Whether to prefer using Python installations that are already present on the system, or
* those that are downloaded and installed by uv.
*
* @schema UvConfiguration#python-preference
*/
readonly pythonPreference?: string;
/**
* Reinstall all packages, regardless of whether they're already installed. Implies `refresh`.
*
* @schema UvConfiguration#reinstall
*/
readonly reinstall?: boolean;
/**
* Reinstall a specific package, regardless of whether it's already installed. Implies
* `refresh-package`.
*
* @schema UvConfiguration#reinstall-package
*/
readonly reinstallPackage?: string[];
/**
* A list of environment markers, e.g., `sys_platform == 'darwin'.
*
* @schema UvConfiguration#required-environments
*/
readonly requiredEnvironments?: string[];
/**
* Enforce a requirement on the version of uv.
*
* If the version of uv does not meet the requirement at runtime, uv will exit
* with an error.
*
* Accepts a [PEP 440](https://peps.python.org/pep-0440/) specifier, like `==0.5.0` or `>=0.5.0`.
*
* @schema UvConfiguration#required-version
*/
readonly requiredVersion?: string;
/**
* The strategy to use when selecting between the different compatible versions for a given
* package requirement.
*
* By default, uv will use the latest compatible version of each package (`highest`).
*
* @schema UvConfiguration#resolution
*/
readonly resolution?: string;
/**
* The sources to use when resolving dependencies.
*
* `tool.uv.sources` enriches the dependency metadata with additional sources, incorporated
* during development. A dependency source can be a Git repository, a URL, a local path, or an
* alternative registry.
*
* See [Dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/) for more.
*
* @schema UvConfiguration#sources
*/
readonly sources?: {
[key: string]: any[];
};
/**
* Configure trusted publishing.
*
* By default, uv checks for trusted publishing when running in a supported environment, but
* ignores it if it isn't configured.
*
* uv's supported environments for trusted publishing include GitHub Actions and GitLab CI/CD.
*
* @schema UvConfiguration#trusted-publishing
*/
readonly trustedPublishing?: TrustedPublishing;
/**
* Allow package upgrades, ignoring pinned versions in any existing output file.
*
* @schema UvConfiguration#upgrade
*/
readonly upgrade?: boolean;
/**
* Allow upgrades for a specific package, ignoring pinned versions in any existing output
* file.
*
* Accepts both standalone package names (`ruff`) and version specifiers (`ruff<0.5.0`).
*
* @schema UvConfiguration#upgrade-package
*/
readonly upgradePackage?: string[];
/**
* The workspace definition for the project, if any.
*
* @schema UvConfiguration#workspace
*/
readonly workspace?: ToolUvWorkspace;
}
/**
* Converts an object of type 'UvConfiguration' to JSON representation.
* @internal
*/
export declare function toJson_UvConfiguration(obj: UvConfiguration | undefined): Record<string, any> | undefined;
/**
* Settings for the uv build backend (`uv_build`).
*
* Note that those settings only apply when using the `uv_build` backend, other build backends
* (such as hatchling) have their own configuration.
*
* All options that accept globs use the portable glob patterns from
* [PEP 639](https://packaging.python.org/en/latest/specifications/glob-patterns/).
*
* @schema BuildBackendSettings
*/
export interface BuildBackendSettings {
/**
* Data includes for wheels.
*
* Each entry is a directory, whose contents are copied to the matching directory in the wheel
* in `<name>-<version>.data/(purelib|platlib|headers|scripts|data)`. Upon installation, this
* data is moved to its target location, as defined by
* <https://docs.python.org/3.12/library/sysconfig.html#installation-paths>. Usually, small
* data files are included by placing them in the Python module instead of using data includes.
*
* - `scripts`: Installed to the directory for executables, `<venv>/bin` on Unix or
* `<venv>\Scripts` on Windows. This directory is added to `PATH` when the virtual
* environment is activated or when using `uv run`, so this data type can be used to install
* additional binaries. Consider using `project.scripts` instead for Python entrypoints.
* - `data`: Installed over the virtualenv environment root.
*
* Warning: This may override existing files!
*
* - `headers`: Installed to the include directory. Compilers building Python packages
* with this package as build requirement use the include directory to find additional header
* files.
* - `purelib` and `platlib`: Installed to the `site-packages` directory. It is not recommended
* to use these two options.
*
* @schema BuildBackendSettings#data
*/
readonly data?: WheelDataIncludes;
/**
* If set to `false`, the default excludes aren't applied.
*
* Default excludes: `__pycache__`, `*.pyc`, and `*.pyo`.
*
* @schema BuildBackendSettings#default-excludes
*/
readonly defaultExcludes?: boolean;
/**
* The name of the module directory inside `module-root`.
*
* The default module name is the package name with dots and dashes replaced by underscores.
*
* Package names need to be valid Python identifiers, and the directory needs to contain a
* `__init__.py`. An exception are stubs packages, whose name ends with `-stubs`, with the stem
* being the module name, and which contain a `__init__.pyi` file.
*
* For namespace packages with a single module, the path can be dotted, e.g., `foo.bar` or
* `foo-stubs.bar`.
*
* For namespace packages with multiple modules, the path can be a list, e.g.,
* `["foo", "bar"]`. We recommend using a single module per package, splitting multiple
* packages into a workspace.
*
* Note that using this option runs the risk of creating two packages with different names but
* the same module names. Installing such packages together leads to unspecified behavior,
* often with corrupted files or directory trees.
*
* @schema BuildBackendSettings#module-name
*/
readonly moduleName?: any;
/**
* The directory that contains the module directory.
*
* Common values are `src` (src layout, the default) or an empty path (flat layout).
*
* @schema BuildBackendSettings#module-root
*/
readonly moduleRoot?: string;
/**
* Build a namespace package.
*
* Build a PEP 420 implicit namespace package, allowing more than one root `__init__.py`.
*
* Use this option when the namespace package contains multiple root `__init__.py`, for
* namespace packages with a single root `__init__.py` use a dotted `module-name` instead.
*
* To compare dotted `module-name` and `namespace = true`, the first example below can be
* expressed with `module-name = "cloud.database"`: There is one root `__init__.py` `database`.
* In the second example, we have three roots (`cloud.database`, `cloud.database_pro`,
* `billing.modules.database_pro`), so `namespace = true` is required.
*
* ```text
* src
* └── cloud
* └── database
* ├── __init__.py
* ├── query_builder
* │ └── __init__.py
* └── sql
* ├── parser.py
* └── __init__.py
* ```
*
* ```text
* src
* ├── cloud
* │ ├── database
* │ │ ├── __init__.py
* │ │ ├── query_builder
* │ │ │ └── __init__.py
* │ │ └── sql
* │ │ ├── __init__.py
* │ │ └── parser.py
* │ └── database_pro
* │ ├── __init__.py
* │ └── query_builder.py
* └── billing
* └── modules
* └── database_pro
* ├── __init__.py
* └── sql.py
* ```
*
* @schema BuildBackendSettings#namespace
*/
readonly namespace?: boolean;
/**
* Glob expressions which files and directories to exclude from the source distribution.
*
* @schema BuildBackendSettings#source-exclude
*/
readonly sourceExclude?: string[];
/**
* Glob expressions which files and directories to additionally include in the source
* distribution.
*
* `pyproject.toml` and the contents of the module directory are always included.
*
* @schema BuildBackendSettings#source-include
*/
readonly sourceInclude?: string[];
/**
* Glob expressions which files and directories to exclude from the wheel.
*
* @schema BuildBackendSettings#wheel-exclude
*/
readonly wheelExclude?: string[];
}
/**
* Converts an object of type 'BuildBackendSettings' to JSON representation.
* @internal
*/
export declare function toJson_BuildBackendSettings(obj: BuildBackendSettings | undefined): Record<string, any> | undefined;
/**
* A single item in a conflicting set.
*
* Each item is a pair of an (optional) package and a corresponding extra or group name for that
* package.
*
* @schema SchemaConflictItem
*/
export interface SchemaConflictItem {
/**
* @schema SchemaConflictItem#extra
*/
readonly extra?: string;
/**
* @schema SchemaConflictItem#group
*/
readonly group?: string;
/**
* @schema SchemaConflictItem#package
*/
readonly package?: string;
}
/**
* Converts an object of type 'SchemaConflictItem' to JSON representation.
* @internal
*/
export declare function toJson_SchemaConflictItem(obj: SchemaConflictItem | undefined): Record<string, any> | undefined;
/**
* @schema DependencyGroupSettings
*/
export interface DependencyGroupSettings {
/**
* Version of python to require when installing this group
*
* @schema DependencyGroupSettings#requires-python
*/
readonly requiresPython?: string;
}
/**
* Converts an object of type 'DependencyGroupSettings' to JSON representation.
* @internal
*/
export declare function toJson_DependencyGroupSettings(obj: DependencyGroupSettings | undefined): Record<string, any> | undefined;
/**
* A subset of the Python Package Metadata 2.3 standard as specified in
* <https://packaging.python.org/specifications/core-metadata/>.
*
* @schema StaticMetadata
*/
export interface StaticMetadata {
/**
* @schema StaticMetadata#name
*/
readonly name: string;
/**
* @schema StaticMetadata#provides-extra
*/
readonly providesExtra?: string[];
/**
* @schema StaticMetadata#requires-dist
*/
readonly requiresDist?: string[];
/**
* PEP 508-style Python requirement, e.g., `>=3.10`
*
* @schema StaticMetadata#requires-python
*/
readonly requiresPython?: string;
/**
* PEP 440-style package version, e.g., `1.2.3`
*
* @schema StaticMetadata#version
*/
readonly version?: string;
}
/**
* Converts an object of type 'StaticMetadata' to JSON representation.
* @internal
*/
export declare function toJson_StaticMetadata(obj: StaticMetadata | undefined): Record<string, any> | undefined;
/**
* @schema Index
*/
export interface Index {
/**
* When uv should use authentication for requests to the index.
*
* ```toml
* [[tool.uv.index]]
* name = "my-index"
* url = "https://<omitted>/simple"
* authenticate = "always"
* ```
*
* @schema Index#authenticate
*/
readonly authenticate?: string;
/**
* Cache control configuration for this index.
*
* When set, these headers will override the server's cache control headers
* for both package metadata requests and artifact downloads.
*
* ```toml
* [[tool.uv.index]]
* name = "my-index"
* url = "https://<omitted>/simple"
* cache-control = { api = "max-age=600", files = "max-age=3600" }
* ```
*
* @schema Index#cache-control
*/
readonly cacheControl?: IndexCacheControl;
/**
* Mark the index as the default index.
*
* By default, uv uses PyPI as the default index, such that even if additional indexes are
* defined via `[[tool.uv.index]]`, PyPI will still be used as a fallback for packages that
* aren't found elsewhere. To disable the PyPI default, set `default = true` on at least one
* other index.
*
* Marking an index as default will move it to the front of the list of indexes, such that it
* is given the highest priority when resolving packages.
*
* @schema Index#default
*/
readonly default?: boolean;
/**
* Mark the index as explicit.
*
* Explicit indexes will _only_ be used when explicitly requested via a `[tool.uv.sources]`
* definition, as in:
*
* ```toml
* [[tool.uv.index]]
* name = "pytorch"
* url = "https://download.pytorch.org/whl/cu121"
* explicit = true
*
* [tool.uv.sources]
* torch = { index = "pytorch" }
* ```
*
* @schema Index#explicit
*/
readonly explicit?: boolean;
/**
* The format used by the index.
*
* Indexes can either be PEP 503-compliant (i.e., a PyPI-style registry implementing the Simple
* API) or structured as a flat list of distributions (e.g., `--find-links`). In both cases,
* indexes can point to either local or remote resources.
*
* @schema Index#format
*/
readonly format?: string;
/**
* Status codes that uv should ignore when deciding whether
* to continue searching in the next index after a failure.
*
* ```toml
* [[tool.uv.index]]
* name = "my-index"
* url = "https://<omitted>/simple"
* ignore-error-codes = [401, 403]
* ```
*
* @schema Index#ignore-error-codes
*/
readonly ignoreErrorCodes?: number[];
/**
* The name of the index.
*
* Index names can be used to reference indexes elsewhere in the configuration. For example,
* you can pin a package to a specific index by name:
*
* ```toml
* [[tool.uv.index]]
* name = "pytorch"
* url = "https://download.pytorch.org/whl/cu121"
*
* [tool.uv.sources]
* torch = { index = "pytorch" }
* ```
*
* @schema Index#name
*/
readonly name?: string;
/**
* The URL of the upload endpoint.
*
* When using `uv publish --index <name>`, this URL is used for publishing.
*
* A configuration for the default index PyPI would look as follows:
*
* ```toml
* [[tool.uv.index]]
* name = "pypi"
* url = "https://pypi.org/simple"
* publish-url = "https://upload.pypi.org/legacy/"
* ```
*
* @schema Index#publish-url
*/
readonly publishUrl?: string;
/**
* The URL of the index.
*
* Expects to receive a URL (e.g., `https://pypi.org/simple`) or a local path.
*
* @schema Index#url
*/
readonly url: string;
}
/**
* Converts an object of type 'Index' to JSON representation.
* @internal
*/
export declare function toJson_Index(obj: Index | undefined): Record<string, any> | undefined;
/**
* Settings that are specific to the `uv pip` command-line interface.
*
* These values will be ignored when running commands outside the `uv pip` namespace (e.g.,
* `uv lock`, `uvx`).
*
* @schema PipOptions
*/
export interface PipOptions {
/**
* Include all optional dependencies.
*
* Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.
*
* @schema PipOptions#all-extras
*/
readonly allExtras?: boolean;
/**
* Allow `uv pip sync` with empty requirements, which will clear the environment of all
* packages.
*
* @schema PipOptions#allow-empty-requirements
*/
readonly allowEmptyRequirements?: boolean;
/**
* The style of the annotation comments included in the output file, used to indicate the
* source of each package.
*
* @schema PipOptions#annotation-style
*/
readonly annotationStyle?: string;
/**
* Allow uv to modify an `EXTERNALLY-MANAGED` Python installation.
*
* WARNING: `--break-system-packages` is intended for use in continuous integration (CI)
* environments, when installing into Python installations that are managed by an external
* package manager, like `apt`. It should be used with caution, as such Python installations
* explicitly recommend against modifications by other package managers (like uv or pip).
*
* @schema PipOptions#break-system-packages
*/
readonly breakSystemPackages?: boolean;
/**
* Compile Python files to bytecode after installation.
*
* By default, uv does not compile Python (`.py`) files to bytecode (`__pycache__/*.pyc`);
* instead, compilation is performed lazily the first time a module is imported. For use-cases
* in which start time is critical, such as CLI applications and Docker containers, this option
* can be enabled to trade longer installation times for faster start times.
*
* When enabled, uv will process the entire site-packages directory (including packages that
* are not being modified by the current operation) for consistency. Like pip, it will also
* ignore errors.
*
* @schema PipOptions#compile-bytecode
*/
readonly compileBytecode?: boolean;
/**
* Settings to pass to the [PEP 517](https://peps.python.org/pep-0517/) build backend,
* specified as `KEY=VALUE` pairs.
*
* @schema PipOptions#config-settings
*/
readonly configSettings?: {
[key: string]: any;
};
/**
* Settings to pass to the [PEP 517](https://peps.python.org/pep-0517/) build backend for specific packages,
* specified as `KEY=VALUE` pairs.
*
* @schema PipOptions#config-settings-package
*/
readonly configSettingsPackage?: {
[key: string]: {
[key: string]: any;
};
};
/**
* The header comment to include at the top of the output file generated by `uv pip compile`.
*
* Used to reflect custom build scripts and commands that wrap `uv pip compile`.
*
* @schema PipOptions#custom-compile-command
*/
readonly customCompileCommand?: string;
/**
* Pre-defined static metadata for dependencies of the project (direct or transitive). When
* provided, enables the resolver to use the specified metadata instead of querying the
* registry or building the relevant package from source.
*
* Metadata should be provided in adherence with the [Metadata 2.3](https://packaging.python.org/en/latest/specifications/core-metadata/)
* standard, though only the following fields are respected:
*
* - `name`: The name of the package.
* - (Optional) `version`: The version of the package. If omitted, the metadata will be applied
* to all versions of the package.
* - (Optional) `requires-dist`: The dependencies of the package (e.g., `werkzeug>=0.14`).
* - (Optional) `requires-python`: The Python version required by the package (e.g., `>=3.10`).
* - (Optional) `provides-extra`: The extras provided by the package.
*
* @schema PipOptions#dependency-metadata
*/
readonly dependencyMetadata?: StaticMetadata[];
/**
* Include `--no-binary` and `--only-binary` entries in the output file generated by `uv pip compile`.
*
* @schema PipOptions#emit-build-options
*/
readonly emitBuildOptions?: boolean;
/**
* Include `--find-links` entries in the output file generated by `uv pip compile`.
*
* @schema PipOptions#emit-find-links
*/
readonly emitFindLinks?: boolean;
/**
* Include comment annotations indicating the index used to resolve each package (e.g.,
* `# from https://pypi.org/simple`).
*
* @schema PipOptions#emit-index-annotation
*/
readonly emitIndexAnnotation?: boolean;
/**
* Include `--index-url` and `--extra-index-url` entries in the output file generated by `uv pip compile`.
*
* @schema PipOptions#emit-index-url
*/
readonly emitIndexUrl?: boolean;
/**
* Whether to emit a marker string indicating the conditions under which the set of pinned
* dependencies is valid.
*
* The pinned dependencies may be valid even when the marker expression is
* false, but when the expression is true, the requirements are known to
* be correct.
*
* @schema PipOptions#emit-marker-expression
*/
readonly emitMarkerExpression?: boolean;
/**
* Limit candidate packages to those that were uploaded prior to a given point in time.
*
* Accepts a superset of [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) (e.g.,
* `2006-12-02T02:07:43Z`). A full timestamp is required to ensure that the resolver will
* behave consistently across timezones.
*
* @schema PipOptions#exclude-newer
*/
readonly excludeNewer?: string;
/**
* Limit candidate packages for specific packages to those that were uploaded prior to the given date.
*
* Accepts package-date pairs in a dictionary format.
*
* @schema PipOptions#exclude-newer-package
*/
readonly excludeNewerPackage?: {
[key: string]: string;
};
/**
* Include optional dependencies from the specified extra; may be provided more than once.
*
* Only applies to `pyproject.toml`, `setup.py`, and `setup.cfg` sources.
*
* @schema PipOptions#extra
*/
readonly extra?: string[];
/**
* Additional build dependencies for packages.
*
* This allows extending the PEP 517 build environment for the project's dependencies with
* additional packages. This is useful for packages that assume the presence of packages like
* `pip`, and do not declare them as build dependencies.
*
* @schema PipOptions#extra-build-dependencies
*/
readonly extraBuildDependencies?: {
[key: string]: any[];
};
/**
* Extra environment variables to set when building certain packages.
*
* Environment variables will be added to the environment when building the
* specified packages.
*
* @schema PipOptions#extra-build-variables
*/
readonly extraBuildVariables?: {
[key: string]: {
[key: string]: string;
};
};
/**
* Extra URLs of package indexes to use, in addition to `--index-url`.
*
* Accepts either a repository compliant with [PEP 503](https://peps.python.org/pep-0503/)
* (the simple repository API), or a local directory laid out in the same format.
*
* All indexes provided via this flag take priority over the index specified by
* [`index_url`](#index-url). When multiple indexes are provided, earlier values take priority.
*
* To control uv's resolution strategy when multiple indexes are present, see
* [`index_strategy`](#index-strategy).
*
* @schema PipOptions#extra-index-url
*/
readonly extraIndexUrl?: string[];
/**
* Locations to search for candidate distributions, in addition to those found in the registry
* indexes.
*
* If a path, the target must be a directory that contains packages as wheel files (`.whl`) or
* source distributions (e.g., `.tar.gz` or `.zip`) at the top level.
*
* If a URL, the page must contain a flat list of links to package files adhering to the
* formats described above.
*
* @schema PipOptions#find-links
*/
readonly findLinks?: string[];
/**
* The strategy to use when selecting multiple versions of a given package across Python
* versions and platforms.
*
* By default, uv will optimize for selecting the latest version of each package for each
* supported Python version (`requires-python`), while minimizing the number of selected
* versions across platforms.
*
* Under `fewest`, uv will minimize the number of selected versions for each package,
* preferring older versions that are compatible with a wider range of supported Python
* versions or platforms.
*
* @schema PipOptions#fork-strategy
*/
readonly forkStrategy?: string;
/**
* Include distribution hashes in the output file.
*
* @schema PipOptions#generate-hashes
*/
readonly generateHashes?: boolean;
/**
* Include the followi