pip-tools

https://pip-tools.readthedocs.io/en/stable/
Admin
pip-tools is a set of command-line utilities that help keep your pip-based Python packages fresh,...
Tokens:12,968
Snippets:191
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Command Property

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.repositories.local

Returns an instance of the install command. This property is part of the LocalRequirementsRepository.

```python
property command: InstallCommand¶
```

--------------------------------

### Install Production Requirements

Source: https://pip-tools.readthedocs.io/en/stable

Use `pip-sync` to install the exact versions of packages listed in the compiled `requirements.txt` file into your production environment.

```bash
$ pip-sync

```

--------------------------------

### Install pip-tools

Source: https://pip-tools.readthedocs.io/en/stable

Install pip-tools within your project's virtual environment using pip.

```bash
$ source /path/to/venv/bin/activate
(venv) $ python -m pip install pip-tools

```

--------------------------------

### Install Development Requirements

Source: https://pip-tools.readthedocs.io/en/stable

Use `pip-sync` with both compiled requirements files (`requirements.txt` and `dev-requirements.txt`) to install all necessary packages for your development environment.

```bash
$ pip-sync requirements.txt dev-requirements.txt

```

--------------------------------

### pyproject.toml for Setuptools

Source: https://pip-tools.readthedocs.io/en/stable

Example `pyproject.toml` configuration for a Setuptools-packaged Python application, specifying dynamic dependencies from a file.

```toml
[build-system]
requires = ["setuptools", "setuptools-scm"]
build-backend = "setuptools.build_meta"

[project]
requires-python = ">=3.9"
name = "foobar"
dynamic = ["dependencies", "optional-dependencies"]

[tool.setuptools.dynamic]
dependencies = { file = ["requirements.in"] }
optional-dependencies.test = { file = ["requirements-test.txt"] }


```

--------------------------------

### piptools._internal._pip_api.install_requirements

Source: https://pip-tools.readthedocs.io/en/stable/_sources/pkg/piptools._internal._pip_api.install_requirements.rst.txt

Documentation for the internal module used to interface with pip for installing requirements.

```APIDOC
## Internal Module: piptools._internal._pip_api.install_requirements

### Description
This module provides internal utility functions for interacting with the pip API to perform package installations. It is intended for internal use within the pip-tools package.

### Members
- The module includes all members, private members, and undocumented members as defined in the source code.

### Inheritance
- This module supports inheritance as defined in the package structure.
```

--------------------------------

### _compose_install_flags

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.scripts.sync

Composes a list of install flags based on the provided package finder and CLI configuration options.

```APIDOC
## _compose_install_flags

### Description
Compose install flags with the given finder and CLI options.

### Parameters
- **_finder** (PackageFinder) - Required
- **_no_index** (bool) - Required
- **_index_url** (str | None) - Required
- **_extra_index_url** (tuple[str, ...]) - Required
- **_trusted_host** (tuple[str, ...]) - Required
- **_find_links** (tuple[str, ...]) - Required
- **_user_only** (bool) - Required
- **_cert** (str | None) - Required
- **_client_cert** (str | None) - Required

### Response
- **Returns** (list[str]) - A list of command-line install flags.
```

--------------------------------

### Example Contributor Update Change Note

Source: https://pip-tools.readthedocs.io/en/stable/contributing

This is an example of a contributor update change note file. It should describe changes related to the contributor experience.

```markdown
`pip-tools` now tests on and officially supports `pip` version 25.2
-- by {user}`sirosen`.
```

--------------------------------

### Example Bugfix Change Note

Source: https://pip-tools.readthedocs.io/en/stable/contributing

This is an example of a bugfix change note file. It should describe a fix for undesired behavior.

```markdown
Fixed a bug which removed slashes from URLs in `-r` and `-c` in the output
of `pip-compile` -- by {user}`sirosen`.
```

--------------------------------

### piptools.sync.diff

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.sync

Compares compiled requirements with a list of currently installed packages to determine which packages need to be installed or uninstalled.

```APIDOC
## piptools.sync.diff

### Description
Calculate which packages should be installed or uninstalled. Compared are the compiled requirements and a list of currently installed modules.

### Parameters
#### Request Body
- **compiled_requirements** (Iterable[InstallRequirement]) - Required - An iterable of compiled requirements.
- **installed_dists** (Iterable[Distribution]) - Required - An iterable of installed distribution objects.

### Response
#### Success Response (200)
- **tuple[set[InstallRequirement], set[str]]** - A tuple containing a set of requirements to install and a set of package names to uninstall.
```

--------------------------------

### Get Dependencies Method

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.repositories.local

Retrieves a set of secondary dependencies for a given requirement. Dependencies are returned as InstallRequirements, not necessarily pinned.

```python
get_dependencies(_ireq : InstallRequirement_) → set[InstallRequirement]¶
```

--------------------------------

### Get Hashes Method

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.repositories.local

Returns a set of hashes for all files associated with a pinned InstallRequirement. This method requires a pinned requirement and cannot accept editable or unpinned ones.

```python
get_hashes(_ireq : InstallRequirement_) → set[str]¶
```

--------------------------------

### pyproject.toml for Hatch

Source: https://pip-tools.readthedocs.io/en/stable

Example `pyproject.toml` configuration for a Hatch-packaged Django application, defining core and optional development dependencies.

```toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-cool-django-app"
version = "42"
dependencies = ["django"]

[project.optional-dependencies]
dev = ["pytest"]


```

--------------------------------

### Combine --upgrade and --upgrade-package

Source: https://pip-tools.readthedocs.io/en/stable

Combine the --upgrade flag with --upgrade-package to upgrade all packages while constraining specific ones. This example upgrades all packages but constrains requests to versions less than 3.0.

```bash
$ pip-compile --upgrade --upgrade-package 'requests<3.0'

```

--------------------------------

### Define Development Requirements with Constraints

Source: https://pip-tools.readthedocs.io/en/stable

Create a `dev-requirements.in` file that includes `-c requirements.txt` to constrain development packages to those already selected for production. This example adds `django-debug-toolbar`.

```ini
# dev-requirements.in
-c requirements.txt
django-debug-toolbar<2.2

```

--------------------------------

### piptools.sync.sync

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.sync

Installs and uninstalls packages based on the provided sets of requirements and unrequirements, with options for dry run, flags, and user interaction.

```APIDOC
## piptools.sync.sync

### Description
Install and uninstall the given sets of modules.

### Parameters
#### Request Body
- **to_install** (Iterable[InstallRequirement]) - Required - A set of requirements to install.
- **to_uninstall** (Iterable[InstallRequirement]) - Required - A set of requirements to uninstall.
- **dry_run** (bool) - Optional - If True, perform a dry run without making changes. Defaults to False.
- **install_flags** (list[str] | None) - Optional - A list of flags to pass to the installation command. Defaults to None.
- **ask** (bool) - Optional - If True, ask for confirmation before proceeding. Defaults to False.
- **python_executable** (str | None) - Optional - The Python executable to use for installation. Defaults to None.

### Response
#### Success Response (200)
- **int** - The number of packages installed or uninstalled.
```

--------------------------------

### Pass pip arguments to pip-sync

Source: https://pip-tools.readthedocs.io/en/stable

Use the --pip-args option to pass flags directly to the underlying pip install command.

```bash
$ pip-sync requirements.txt --pip-args "--no-cache-dir --no-deps"
```

--------------------------------

### _get_installed_distributions

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.scripts.sync

Retrieves a list of currently installed distribution objects based on specified filters.

```APIDOC
## _get_installed_distributions

### Description
Return a list of installed Distribution objects.

### Parameters
- **_local_only** (bool) - Optional (default: True)
- **_user_only** (bool) - Optional (default: False)
- **_paths** (list[str] | None) - Optional

### Response
- **Returns** (list[Distribution]) - A list of installed distribution objects.
```

--------------------------------

### Define Production Requirements

Source: https://pip-tools.readthedocs.io/en/stable

Create a `requirements.in` file to specify the base dependencies for your production environment. This example constrains Django to a version less than 2.2.

```ini
# requirements.in
django<2.2

```

--------------------------------

### piptools.sync.diff_key_from_ireq

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.sync

Generates a unique key for comparing a compiled requirement with installed modules. For URL requirements, it includes a hash if available.

```APIDOC
## piptools.sync.diff_key_from_ireq

### Description
Calculate key for comparing a compiled requirement with installed modules. For URL requirements, only provide a useful key if the url includes a hash, e.g. #sha1=…, in any of the supported hash algorithms. Otherwise return `ireq.link` so the key will not match and the package will reinstall. Reinstall is necessary to ensure that packages will reinstall if the contents at the URL have changed but the version has not.

### Parameters
#### Request Body
- **ireq** (InstallRequirement) - Required - The compiled requirement to generate a key for.
```

--------------------------------

### get_pip_version_for_python_executable

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools._internal._pip_api.pip_version

Retrieves the version of pip installed for a specified Python executable path.

```APIDOC
## get_pip_version_for_python_executable

### Description
Returns the pip version associated with the provided Python executable path.

### Parameters
#### Path Parameters
- **_python_executable** (str) - Required - The file path to the Python executable.

### Response
- **Version** - The version object representing the pip version found for the executable.
```

--------------------------------

### piptools.sync.get_dists_to_ignore

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.sync

Returns a list of package names that should be ignored by `pip-sync`, based on the currently installed environment.

```APIDOC
## piptools.sync.get_dists_to_ignore

### Description
Return a collection of package names to ignore by `pip-sync`. Based on the currently installed environment. For example, when pip-tools is installed in the local environment, it should be ignored, including all of its dependencies (e.g. click). When pip-tools is not installed locally, click should also be installed/uninstalled depending on the given requirements.

### Parameters
#### Request Body
- **installed** (Iterable[Distribution]) - Required - An iterable of installed distribution objects.
```

--------------------------------

### relative_to_walk_up()

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools._compat.pip_compat

Computes a relative path between two paths, allowing the input to not be a subpath of the start, serving as a compatibility wrapper for pathlib.Path.relative_to with walk_up support.

```APIDOC
## relative_to_walk_up(_path, _start)

### Description
Compute a relative path allowing for the input to not be a subpath of the start. This is a compatibility helper for pathlib.Path.relative_to(..., walk_up=True) on all Python versions.

### Parameters
- **_path** (Path) - Required - The target path to make relative.
- **_start** (Path) - Required - The starting path for the relative calculation.

### Returns
- **Path** - The computed relative path.
```

--------------------------------

### Override Global and Compile-Specific Settings

Source: https://pip-tools.readthedocs.io/en/stable

Local settings in TOML configuration files take precedence over global ones. This example shows `generate-hashes` enabled globally, but `dry-run` disabled specifically for `pip-compile`.

```toml
[tool.pip-tools]
generate-hashes = true
dry-run = true

[tool.pip-tools.compile]
dry-run = false

```

--------------------------------

### Preview documentation

Source: https://pip-tools.readthedocs.io/en/stable/contributing

Build the documentation locally to preview changes, including the generated changelog.

```bash
tox run -e build-docs
```

--------------------------------

### Execute pip-sync

Source: https://pip-tools.readthedocs.io/en/stable

Synchronize the virtual environment with the generated requirements.txt file.

```bash
$ pip-sync
Uninstalling flake8-2.4.1:
    Successfully uninstalled flake8-2.4.1
Collecting click==4.1
    Downloading click-4.1-py2.py3-none-any.whl (62kB)
    100% |................................| 65kB 1.8MB/s
    Found existing installation: click 4.0
    Uninstalling click-4.0:
        Successfully uninstalled click-4.0
Successfully installed click-4.1
```

--------------------------------

### Run project tests

Source: https://pip-tools.readthedocs.io/en/stable/contributing

Execute the full test suite locally using tox.

```bash
tox -p all
```

--------------------------------

### Find Best Match Method

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.repositories.local

Finds the best matching pinned InstallRequirement for a given InstallRequirement from the external repository. Handles prereleases if specified.

```python
find_best_match(_ireq : InstallRequirement_, _prereleases : bool | None = None_) → InstallationCandidate¶
```

--------------------------------

### Compile requirements.txt from requirements.in

Source: https://pip-tools.readthedocs.io/en/stable

Generate a pinned `requirements.txt` file from a `requirements.in` file using `pip-compile`.

```bash
$ pip-compile requirements.in
#

```

--------------------------------

### Compile All Build Dependencies and Extras

Source: https://pip-tools.readthedocs.io/en/stable

Use `pip-compile` with `--all-build-deps` and `--all-extras` to generate a comprehensive constraints file from `pyproject.toml`. This ensures all build-time and optional dependencies are locked.

```bash
$ pip-compile --all-build-deps --all-extras --output-file=constraints.txt --strip-extras pyproject.toml
```

```text
#
# This file is autogenerated by pip-compile with Python 3.9
# by the following command:
#
#    pip-compile --all-build-deps --all-extras --output-file=constraints.txt --strip-extras pyproject.toml
#
asgiref==3.5.2
    # via django
attrs==22.1.0
    # via pytest
backports-zoneinfo==0.2.1
    # via django
django==4.1
    # via my-cool-django-app (pyproject.toml)
editables==0.3
    # via hatchling
hatchling==1.11.1
    # via my-cool-django-app (pyproject.toml::build-system.requires)
iniconfig==1.1.1
    # via pytest
packaging==21.3
    # via
    #   hatchling
    #   pytest
pathspec==0.10.2
    # via hatchling
pluggy==1.0.0
    # via
    #   hatchling
    #   pytest
py==1.11.0
    # via pytest
pyparsing==3.0.9
    # via packaging
pytest==7.1.2
    # via my-cool-django-app (pyproject.toml)
sqlparse==0.4.2
    # via django
tomli==2.0.1
    # via
    #   hatchling
    #   pytest

```

--------------------------------

### Compile dev-requirements.txt with extra dependencies

Source: https://pip-tools.readthedocs.io/en/stable

Generate a pinned `dev-requirements.txt` file from `pyproject.toml`, including the 'dev' extra dependencies.

```bash
$ pip-compile --extra dev -o dev-requirements.txt pyproject.toml
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    pip-compile --extra=dev --output-file=dev-requirements.txt pyproject.toml
#
asgiref==3.6.0
    # via django
attrs==22.2.0
    # via pytest
django==4.1.7
    # via my-cool-django-app (pyproject.toml)
exceptiongroup==1.1.1
    # via pytest
iniconfig==2.0.0
    # via pytest
packaging==23.0
    # via pytest
pluggy==1.0.0
    # via pytest
pytest==7.2.2
    # via my-cool-django-app (pyproject.toml)
sqlparse==0.4.3
    # via django
tomli==2.0.1
    # via pytest


```

--------------------------------

### Release process commands

Source: https://pip-tools.readthedocs.io/en/stable/contributing

Commands used during the release lifecycle for versioning, changelog generation, and tagging.

```bash
towncrier build --version v3.4.0
```

```bash
git push -u origin release/v3.4.0
```

```bash
git tag -a v3.4.0 -m v3.4.0
```

--------------------------------

### Compile requirements.txt from pyproject.toml

Source: https://pip-tools.readthedocs.io/en/stable

Generate a pinned `requirements.txt` file from `pyproject.toml` using `pip-compile`.

```bash
$ pip-compile -o requirements.txt pyproject.toml
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    pip-compile --output-file=requirements.txt pyproject.toml
#
asgiref==3.6.0
    # via django
django==4.1.7
    # via my-cool-django-app (pyproject.toml)
sqlparse==0.4.3
    # via django


```

--------------------------------

### Generate requirements.txt

Source: https://pip-tools.readthedocs.io/en/stable

This command generates a requirements.txt file with pinned dependencies. It uses Python 3.10 and the specified requirements.in file.

```bash
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    pip-compile requirements.in
#
asgiref==3.6.0
    # via django
django==4.1.7
    # via -r requirements.in
sqlparse==0.4.3
    # via django

```

--------------------------------

### Options Property

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.repositories.local

Returns parsed pip options. This property is part of the LocalRequirementsRepository.

```python
property options: Values¶
```

--------------------------------

### piptools.repositories Module Overview

Source: https://pip-tools.readthedocs.io/en/stable/_sources/pkg/piptools.repositories.rst.txt

Overview of the repository management modules within the pip-tools package.

```APIDOC
## piptools.repositories

### Description
The `piptools.repositories` package contains the logic for interacting with various package sources. It includes submodules for base repository definitions, local repository handling, and PyPI integration.

### Submodules
- **piptools.repositories.base**: Defines the base interface for repository interactions.
- **piptools.repositories.local**: Handles local package repository logic.
- **piptools.repositories.pypi**: Manages interactions with the Python Package Index (PyPI).
```

--------------------------------

### Generate requirements.txt with hash-checking mode

Source: https://pip-tools.readthedocs.io/en/stable

Enable hash-checking mode by using the --generate-hashes flag. This adds SHA256 hashes for each package, enhancing security.

```bash
$ pip-compile --generate-hashes requirements.in
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    pip-compile --generate-hashes requirements.in
#
asgiref==3.6.0 \
    --hash=sha256:71e68008da809b957b7ee4b43dbccff33d1b23519fb8344e33f049897077afac \
    --hash=sha256:9567dfe7bd8d3c8c892227827c41cce860b368104c3431da67a0c5a65a949506
    # via django
django==4.1.7 \
    --hash=sha256:44f714b81c5f190d9d2ddad01a532fe502fa01c4cb8faf1d081f4264ed15dcd8 \
    --hash=sha256:f2f431e75adc40039ace496ad3b9f17227022e8b11566f4b363da44c7e44761e
    # via -r requirements.in
sqlparse==0.4.3 \
    --hash=sha256:0323c0ec29cd52bceabc1b4d9d579e311f3e4961b98d174201d5622a23b85e34 \
    --hash=sha256:69ca804846bb114d2ec380e4360a8a340db83f0ccf3afceeb1404df028f57268
    # via django

```

--------------------------------

### requirements.in for Django

Source: https://pip-tools.readthedocs.io/en/stable

Declare Django as a dependency in a plain text `requirements.in` file.

```text
# requirements.in
django


```

--------------------------------

### Compile Development Requirements with Constraints

Source: https://pip-tools.readthedocs.io/en/stable

Run `pip-compile` with the development requirements file (`dev-requirements.in`) to compile it, respecting the constraints from `requirements.txt`. The output will include compatible versions of all packages.

```bash
$ pip-compile dev-requirements.in
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    pip-compile dev-requirements.in
#
django==2.1.15
    # via
    #   -c requirements.txt
    #   django-debug-toolbar
django-debug-toolbar==2.1
    # via -r dev-requirements.in
pytz==2023.3
    # via
    #   -c requirements.txt
    #   django
sqlparse==0.4.3
    # via django-debug-toolbar

```

--------------------------------

### Configure pip-compile as a pre-commit hook

Source: https://pip-tools.readthedocs.io/en/stable

Basic configuration for integrating pip-compile into a pre-commit workflow.

```yaml
repos:
  - repo: https://github.com/jazzband/pip-tools
    rev: 7.4.1
    hooks:
      - id: pip-compile
```

--------------------------------

### Output requirements to standard output

Source: https://pip-tools.readthedocs.io/en/stable

To output the pinned requirements to standard output, use --output-file=-. This allows redirecting the output to a file or piping it to another command.

```bash
$ pip-compile --output-file=-
$ pip-compile - --output-file=- < requirements.in > requirements.txt

```

--------------------------------

### Sync multiple requirement files

Source: https://pip-tools.readthedocs.io/en/stable

Pass multiple requirement files as arguments to pip-sync.

```bash
$ pip-sync dev-requirements.txt requirements.txt
```

--------------------------------

### Package Finder Property

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.repositories.local

Returns a package finder instance used to interact with the simple repository API (PEP 503). This property is part of the LocalRequirementsRepository.

```python
property finder: PackageFinder¶
```

--------------------------------

### PipTools Scripts Overview

Source: https://pip-tools.readthedocs.io/en/stable/_sources/pkg/piptools.scripts.rst.txt

This section provides an overview of the piptools.scripts package and its submodules.

```APIDOC
## PipTools Scripts Package

This package contains the command-line scripts for the pip-tools utility.

### Submodules

- `piptools.scripts._deprecations`: Handles deprecation warnings and messages.
- `piptools.scripts.compile`: Script for compiling requirements files.
- `piptools.scripts.options`: Defines common command-line options.
- `piptools.scripts.sync`: Script for synchronizing installed packages with requirements.

### Module Contents

The `piptools.scripts` module itself exposes various members, including public and private functions, and supports inheritance.
```

--------------------------------

### piptools.__main__ Module

Source: https://pip-tools.readthedocs.io/en/stable/_sources/pkg/piptools.__main__.rst.txt

This snippet provides an overview of the piptools.__main__ module, detailing its members, private members, and inheritance.

```APIDOC
## piptools.__main__ Module

### Description
This module contains the main entry point for the pip-tools package.

### Members
- **members**: Shows public members of the module.
- **private-members**: Shows private members of the module.
- **show-inheritance**: Displays inheritance information for classes within the module.
- **undoc-members**: Includes members that are not documented.
```

--------------------------------

### LocalRequirementsRepository Class Definition

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.repositories.local

Defines the LocalRequirementsRepository which proxies a real repository, checking existing pins before PyPI matches. This helps minimize updates to requirements.txt.

```python
class piptools.repositories.local.LocalRequirementsRepository(_existing_pins : Mapping[str, InstallationCandidate]_, _proxied_repository : PyPIRepository_, _reuse_hashes : bool = True_)
    
Bases: `BaseRepository`
```

--------------------------------

### Compile Production Requirements

Source: https://pip-tools.readthedocs.io/en/stable

Run `pip-compile` without arguments to compile the base `requirements.in` file into `requirements.txt`. This generates a file with specific versions of packages, like Django 2.1.15.

```bash
$ pip-compile
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    pip-compile
#
django==2.1.15
    # via -r requirements.in
pytz==2023.3
    # via django

```

--------------------------------

### LocalRequirementsRepository Class

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.repositories.local

The LocalRequirementsRepository class proxies the real repository by first checking if a requirement can be satisfied by existing pins. This helps minimize updates to the requirements.txt file.

```APIDOC
## Class: LocalRequirementsRepository

### Description
Proxies the _real_ repository by first checking if a requirement can be satisfied by existing pins (i.e. the result of a previous compile step). In effect, if a requirement can be satisfied with a version pinned in the requirements file, we prefer that version over the best match found in PyPI. This keeps updates to the requirements.txt down to a minimum.

### Methods

#### `allow_all_wheels()`
Monkey patches pip.Wheel to allow wheels from all platforms and Python versions.

#### `clear_caches()`
Should clear any caches used by the implementation.

#### `find_best_match(_ireq: InstallRequirement_, _prereleases: bool | None = None_) -> InstallationCandidate`
Returns a pinned InstallRequirement object that indicates the best match for the given InstallRequirement according to the external repository.

#### `get_dependencies(_ireq: InstallRequirement_) -> set[InstallRequirement]`
Given a pinned, URL, or editable InstallRequirement, returns a set of dependencies (also InstallRequirements, but not necessarily pinned). They indicate the secondary dependencies for the given requirement.

#### `get_hashes(_ireq: InstallRequirement_) -> set[str]`
Given a pinned InstallRequirement, returns a set of hashes that represent all of the files for a given requirement. It is not acceptable for an editable or unpinned requirement to be passed to this function.

### Properties

#### `command: InstallCommand`
Return an install command instance.

#### `finder: PackageFinder`
Returns a package finder to interact with simple repository API (PEP 503)

#### `options: Values`
Returns parsed pip options

#### `session: PipSession`
Returns a session to make requests
```

--------------------------------

### pip-sync Command Usage

Source: https://pip-tools.readthedocs.io/en/stable/cli/pip-sync

The pip-sync command synchronizes your virtual environment with the specified requirements files. It supports various options to control its behavior, including dry runs, forcing updates, and specifying index URLs.

```APIDOC
## pip-sync Command

### Description
Synchronize virtual environment with requirements.txt.

### Method
CLI Command

### Endpoint
N/A (Command-line tool)

### Parameters
#### Options
- **--version** - Show the version and exit.
- **-a, --ask** (boolean) - Show what would happen, then ask whether to continue.
- **-n, --dry-run** (boolean) - Only show what would happen, don't change anything.
- **--force** (boolean) - Proceed even if conflicts are found.
- **-f, --find-links TEXT** - Look for archives in this directory or on this HTML page; may be used more than once.
- **-i, --index-url TEXT** - Change index URL (defaults to https://pypi.org/simple).
- **--extra-index-url TEXT** - Add another index URL to search; may be used more than once.
- **--trusted-host TEXT** - Mark this host as trusted, even though it does not have valid or any HTTPS; may be used more than once.
- **--no-index** (boolean) - Ignore package index (only looking at --find-links URLs instead).
- **--python-executable TEXT** - Custom python executable path if targeting an environment other than current.
- **-v, --verbose** (boolean) - Show more output.
- **-q, --quiet** (boolean) - Give less output.
- **--user** (boolean) - Restrict attention to user directory.
- **--cert TEXT** - Path to alternate CA bundle.
- **--client-cert TEXT** - Path to SSL client certificate, a single file containing the private key and the certificate in PEM format.
- **--pip-args TEXT** - Arguments to pass directly to the pip command.
- **--config FILE** - Read configuration from TOML file. By default, looks for the following files in the given order: .pip-tools.toml, pyproject.toml.
- **--no-config** (boolean) - Do not read any config file.
- **-h, --help** (boolean) - Show this message and exit.

### Request Example
```bash
pip-sync requirements.txt --dry-run
```

### Response
#### Success Response (Exit Code 0)
- Output indicating changes made or proposed.

#### Response Example
```
Would install package_a
Would upgrade package_b
```
```

--------------------------------

### run_python_snippet Function

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools._internal._subprocess

Executes Python code by calling the specified Python executable with the '-c' option.

```APIDOC
## run_python_snippet(_python_executable : str_, _code_to_run : str_) -> str

### Description
Execute Python code by calling `python_executable` with ‘-c’ option.

### Method
N/A (This is a Python function, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (str)
- Returns the standard output of the executed Python code as a string.

#### Response Example
```
"Output from the executed Python code"
```
```

--------------------------------

### Output requirements to a specific file

Source: https://pip-tools.readthedocs.io/en/stable

Use the --output-file option to specify a different filename for the pinned requirements. This is useful for managing multiple requirement sets.

```bash
$ pip-compile --upgrade-package 'django<1.0' --output-file requirements-django0x.txt
$ pip-compile --upgrade-package 'django<2.0' --output-file requirements-django1x.txt

```

--------------------------------

### Configure multiple pip-compile hooks

Source: https://pip-tools.readthedocs.io/en/stable

Define separate hooks for different requirement files within a single configuration.

```yaml
repos:
  - repo: https://github.com/jazzband/pip-tools
    rev: 7.4.1
    hooks:
      - id: pip-compile
        name: pip-compile setup.py
        files: ^(setup\.py|requirements\.txt)$
      - id: pip-compile
        name: pip-compile requirements-dev.in
        args: [requirements-dev.in]
        files: ^requirements-dev\.(in|txt)$
      - id: pip-compile
        name: pip-compile requirements-lint.in
        args: [requirements-lint.in]
        files: ^requirements-lint\.(in|txt)$
      - id: pip-compile
        name: pip-compile requirements.in
        args: [requirements.in]
        files: ^requirements\.(in|txt)$
```

--------------------------------

### Check if Requirement Satisfied by Existing Pin

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.repositories.local

Determines if a given InstallRequirement is satisfied by a previously encountered version pin. Returns True if satisfied, False otherwise.

```python
piptools.repositories.local.ireq_satisfied_by_existing_pin(_ireq : InstallRequirement_, _existing_pin : InstallationCandidate_) → bool¶
```

--------------------------------

### Customize pip-compile hook arguments

Source: https://pip-tools.readthedocs.io/en/stable

Configure specific files and arguments for the pip-compile pre-commit hook.

```yaml
repos:
  - repo: https://github.com/jazzband/pip-tools
    rev: 7.4.1
    hooks:
      - id: pip-compile
        files: ^requirements/production\.(in|txt)$
        args: [--index-url=https://example.com, requirements/production.in]
```

--------------------------------

### piptools.sync.dependency_tree

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.sync

Calculates the dependency tree for a given package using a Depth First Search (DFS) traversal algorithm. It returns a set of all the package's dependencies.

```APIDOC
## piptools.sync.dependency_tree

### Description
Calculate the dependency tree for a package. Return a collection of all of the package’s dependencies. Uses a DFS traversal algorithm.

`installed_keys` should be a {key: requirement} mapping, e.g. {‘django’: from_line(‘django==1.8’)}

### Parameters
#### Path Parameters
- **root_key** (str) - Required - The key to return the dependency tree for.

#### Request Body
- **installed_keys** (Mapping[str, Distribution]) - Required - A mapping of installed package keys to their distribution objects.
```

--------------------------------

### Allow All Wheels Method

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.repositories.local

Monkey patches pip.Wheel to permit wheels from all platforms and Python versions. This method is part of the LocalRequirementsRepository.

```python
allow_all_wheels() → Iterator[None]¶
```

--------------------------------

### piptools.sync.diff_key_from_req

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.sync

Retrieves a unique key for a given requirement (Distribution object).

```APIDOC
## piptools.sync.diff_key_from_req

### Description
Get a unique key for the requirement.

### Parameters
#### Request Body
- **req** (Distribution) - Required - The distribution object to get a key for.
```

--------------------------------

### CLI Command: pip-compile

Source: https://pip-tools.readthedocs.io/en/stable/cli/pip-compile

The pip-compile command processes source files to generate a pinned requirements file. It supports various options for dependency resolution, output formatting, and index configuration.

```APIDOC
## CLI Command: pip-compile

### Description
Compiles a requirements.txt file from source files such as requirements.in, pyproject.toml, setup.cfg, or setup.py.

### Parameters
#### Positional Arguments
- **SRC_FILES** (list) - Optional - Source files to compile (e.g., requirements.in).

#### Options
- **--version** (flag) - Show the version and exit.
- **--color / --no-color** (flag) - Force output to be colorized or not.
- **-v, --verbose** (flag) - Show more output.
- **-q, --quiet** (flag) - Give less output.
- **-n, --dry-run** (flag) - Only show what would happen, don't change anything.
- **-p, --pre** (flag) - Allow resolving to prereleases.
- **-r, --rebuild** (flag) - Clear any caches upfront, rebuild from scratch.
- **--extra** (text) - Name of an extras_require group to install.
- **-i, --index-url** (text) - Change index URL (defaults to https://pypi.org/simple).
- **-o, --output-file** (filename) - Output file name.
- **--generate-hashes** (flag) - Generate pip 8 style hashes in the resulting requirements file.
- **--cache-dir** (directory) - Store the cache data in DIRECTORY.
```

--------------------------------

### ireq_satisfied_by_existing_pin Function

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.repositories.local

A helper function to determine if an InstallRequirement is satisfied by a previously encountered version pin.

```APIDOC
## Function: ireq_satisfied_by_existing_pin

### Description
Return `True` if the given `InstallRequirement` is satisfied by the previously encountered version pin.

### Parameters

#### `_ireq` (InstallRequirement)
- The InstallRequirement to check.

#### `_existing_pin` (InstallationCandidate)
- The existing pin to compare against.
```

--------------------------------

### piptools.sync.merge

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.sync

Merges requirements, potentially handling conflicts based on the `ignore_conflicts` flag.

```APIDOC
## piptools.sync.merge

### Description
Merges requirements.

### Parameters
#### Request Body
- **requirements** (Iterable[InstallRequirement]) - Required - An iterable of InstallRequirement objects to merge.
- **ignore_conflicts** (bool) - Required - A boolean indicating whether to ignore conflicts during merging.
```

--------------------------------

### Configure pip-tools to Generate Hashes

Source: https://pip-tools.readthedocs.io/en/stable

Set `generate-hashes` to `true` in the `[tool.pip-tools]` section of your TOML configuration file to generate pip hashes for the requirements file output.

```toml
[tool.pip-tools]
generate-hashes = true

```

```toml
[tool.pip-tools]
generate_hashes = true

```

--------------------------------

### Forward options to pip

Source: https://pip-tools.readthedocs.io/en/stable

Pass additional arguments directly to pip using the --pip-args option. This allows fine-grained control over pip's behavior, such as setting retries or timeouts.

```bash
$ pip-compile requirements.in --pip-args "--retries 10 --timeout 30"

```

--------------------------------

### piptools.resolver module

Source: https://pip-tools.readthedocs.io/en/stable/_sources/pkg/piptools.resolver.rst.txt

The resolver module handles the core logic for resolving package dependencies. It is documented via automodule directives.

```APIDOC
## piptools.resolver

### Description
The resolver module provides the primary interface for dependency resolution within the pip-tools ecosystem. It includes members, private members, and inherited functionality for managing package constraints and requirements.

### Implementation Details
- **Module**: piptools.resolver
- **Features**: Includes all public and private members, and displays class inheritance.
```

--------------------------------

### Upgrade specific packages with pip-compile

Source: https://pip-tools.readthedocs.io/en/stable

Use the --upgrade-package or -P flag to update specific packages. You can specify a package name or a package with a version constraint.

```bash
# only update the django package
$ pip-compile --upgrade-package django

# update both the django and requests packages
$ pip-compile --upgrade-package django --upgrade-package requests

# update the django package to the latest, and requests to v2.0.0
$ pip-compile --upgrade-package django --upgrade-package requests==2.0.0

```

--------------------------------

### Session Property

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.repositories.local

Returns a session object used for making requests. This property is part of the LocalRequirementsRepository.

```python
property session: PipSession¶
```

--------------------------------

### Configure pip-compile Dry-Run

Source: https://pip-tools.readthedocs.io/en/stable

To perform a dry-run by default with `pip-compile`, set `dry-run = true` under the `[tool.pip-tools.compile]` section in your TOML configuration file. This setting is specific to `pip-compile` and does not affect `pip-sync`.

```toml
[tool.pip-tools.compile]
dry-run = true

```

--------------------------------

### Clear Caches Method

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.repositories.local

Clears any caches utilized by the repository implementation. This method is part of the LocalRequirementsRepository.

```python
clear_caches() → None¶
```

--------------------------------

### _validate_python_executable

Source: https://pip-tools.readthedocs.io/en/stable/pkg/piptools.scripts.sync

Validates the provided Python executable path for CLI usage.

```APIDOC
## _validate_python_executable

### Description
Validates incoming python_executable argument passed to CLI.

### Parameters
- **_python_executable** (str) - Required

### Response
- **Returns** (None)
```

--------------------------------

### Override Compile Command with Environment Variable

Source: https://pip-tools.readthedocs.io/en/stable

Use the `CUSTOM_COMPILE_COMMAND` environment variable to override the default compile command comment in generated requirements files. This is useful when wrapping `pip-compile` in a custom script.

```bash
$ CUSTOM_COMPILE_COMMAND="./pipcompilewrapper" pip-compile requirements.in
#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    ./pipcompilewrapper
#
asgiref==3.6.0
    # via django
django==4.1.7
    # via -r requirements.in
sqlparse==0.4.3
    # via django

```
Tokens:
Raw