### Example constraints.txt

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/files.md

An example of the constraints.txt file format, showing package names with version specifiers like exact versions, version ranges, and excluded versions.

```text
torch==2.3.1
pandas<2.2.2
setuptools!=72.0.0
```

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

### Example build-order.json

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/files.md

An example of the build-order.json file, which specifies the build sequence for dependencies. Each object represents a dependency with its type, requirement, version, and source URL.

```json
[
  {
    "type": "build-system",
    "req": "flit_core<4,>=3.8",
    "constraint": "",
    "dist": "flit-core",
    "version": "3.9.0",
    "prebuilt": false,
    "source_url": "https://files.pythonhosted.org/packages/c4/e6/c1ac50fe3eebb38a155155711e6e864e254ce4b6e17fe2429b4c4d5b9e80/flit_core-3.9.0.tar.gz#sha256=72ad266176c4a3fcfab5f2930d76896059851240570ce9a98733b658cb786eba",
    "source_url_type": "sdist"
  },
  {
    "type": "toplevel",
    "req": "wheel",
    "constraint": "",
    "dist": "wheel",
    "version": "0.44.0",
    "prebuilt": false,
    "source_url": "https://files.pythonhosted.org/packages/b7/a0/95e9e962c5fd9da11c1e28aa4c0d8210ab277b1ada951d2aee336b505813/wheel-0.44.0.tar.gz#sha256=a29c3f2817e95ab89aa4660681ad547c0e9547f20e75b0562fe7723c9a2a9d49",
    "source_url_type": "sdist"
  }
]
```

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

### Work Directory Structure with Example Packages

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/files.md

Provides an example of the work-dir structure after a 'bootstrap' command, showcasing subdirectories for specific packages like 'pbr', 'setuptools', and 'stevedore', each containing their build-related files.

```text
work-dir
├── build-order.json
├── constraints.txt
├── graph.json
├── logs
├── pbr-6.1.0
│   ├── build-backend-requirements.txt
│   ├── build.log
│   ├── build-meta.json
│   ├── build-sdist-requirements.txt
│   ├── build-system-requirements.txt
│   └── requirements.txt
├── setuptools-75.1.0
│   ├── build-backend-requirements.txt
│   ├── build.log
│   ├── build-meta.json
│   ├── build-sdist-requirements.txt
│   ├── build-system-requirements.txt
│   └── requirements.txt
└── stevedore-5.3.0
    ├── build-backend-requirements.txt
    ├── build.log
    ├── build-meta.json
    ├── build-sdist-requirements.txt
    ├── build-system-requirements.txt
    └── requirements.txt

```

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

### Example Constraints File

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/how-tos/bootstrap-constraints.rst

This snippet shows a basic example of a constraints file used with fromager. It specifies that the 'setuptools' package should be less than version 80.0.0.

```text
setuptools<80.0.0
```

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

### Skipping Coverage Setup

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/develop.md

Instructions on how to create a file to skip coverage setup during local development, preventing clutter from coverage files.

```bash
touch .skip-coverage
```

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

### Development Installation with Hatch

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/develop.md

Steps to install the project in editable mode for development using `hatch shell` and verify its installation.

```bash
# Spawn a shell within an environment with editable installation:
hatch shell

# Check if the project is installed and available in the PATH:
which fromager
```

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

### Example graph.json

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/files.md

An example of the graph.json file, illustrating the dependency graph for a wheel build. It maps resolved package versions to their properties and dependencies, used for repeatable builds.

```json
{
  "": {
    "download_url": "",
    "version": "0",
    "canonicalized_name": "",
    "edges": [
      {
        "key": "wheel==0.44.0",
        "req_type": "toplevel",
        "req": "wheel"
      }
    ]
  },
  "wheel==0.44.0": {
    "download_url": "",
    "version": "0.44.0",
    "canonicalized_name": "wheel",
    "edges": [
      {
        "key": "flit-core==3.9.0",
        "req_type": "build-system",
        "req": "flit_core<4,>=3.8"
      }
    ]
  },
  "flit-core==3.9.0": {
    "download_url": "",
    "version": "3.9.0",
    "canonicalized_name": "flit-core",
    "edges": []
  }
}
```

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

### Example Fromager Package Configuration (torch.yaml)

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/customization.md

An example YAML configuration file for a package named 'torch'. It specifies download source URL and filename, resolver distribution settings (preferring wheels), git options (enabling submodules), build directory, environment variables, and variant-specific configurations for 'cpu' and 'gaudi'.

```yaml
# overrides/settings/torch.yaml
download_source:
    url: "https://github.com/pytorch/pytorch/releases/download/v${version}/pytorch-v${version}.tar.gz"
    destination_filename: "${canonicalized_name}-${version}.tar.gz"
resolver_dist:
    sdist_server_url: "https://pypi.org/simple"
    include_wheels: true
    include_sdists: false
git_options:
    submodules: true  # Clone all submodules for git+https:// URLs
build_dir: directory name relative to sdist directory, defaults to an empty string, which means to use the sdist directory
env:
    USE_FFMPEG: "0"
    USE_LEVELDB: "0"
    USE_LMDB: "1"
variants:
    cpu:
        env:
            OPENBLAS_NUM_THREADS: "1"
    gaudi:
        # use pre-built binary wheels from a custom index for this variant
        pre_built: true
        wheel_server_url: https://internal.pypi.example/simple
```

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

### Post Build Hook Implementation Example

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/customization.md

Provides a Python function signature and example implementation for a `post_build` hook. The hook receives context, requirement details, distribution information, and filenames for sdist and wheel.

```python
def post_build(
    ctx: context.WorkContext,
    req: Requirement,
    dist_name: str,
    dist_version: str,
    sdist_filename: pathlib.Path,
    wheel_filename: pathlib.Path,
):
    logger.info(
        f"{req.name}: running post build hook for {sdist_filename} and {wheel_filename}"
    )

```

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

### Fromager Bootstrap Example

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/getting-started.rst

Demonstrates the command-line usage of `fromager bootstrap` to build Python wheels from a requirements file. It shows the typical output, including dependency resolution, wheel searching, and source downloading.

```console
$ fromager bootstrap --requirements-file ./docs/example/requirements.txt

11:17:49 INFO primary settings file: overrides/settings.yaml
11:17:49 INFO per-package settings dir: overrides/settings
11:17:49 INFO variant: cpu
11:17:49 INFO patches dir: overrides/patches
11:17:49 INFO maximum concurrent jobs: None
11:17:49 INFO constraints file: None
11:17:49 INFO network isolation: False
11:17:49 INFO cache wheel server url: None
11:17:49 INFO bootstrapping 'cpu' variant of [<Requirement('pydantic-core==2.18.4')>]
11:17:49 INFO no previous bootstrap data
11:17:49 INFO build all missing wheels
0%|                                                                                                                                                  | 0/2 [00:00<?, ?pkg/s]11:17:50 INFO resolving top-level dependencies before building
11:17:50 INFO pydantic-core: looking for candidates for <Requirement('pydantic-core==2.18.4')>
11:17:51 INFO pydantic-core: selecting <pydantic-core==2.18.4>
11:17:51 INFO pydantic-core: successfully resolved <Requirement('pydantic-core==2.18.4')>
11:17:51 INFO pydantic-core: pydantic-core==2.18.4 resolves to 2.18.4
11:17:51 INFO pydantic-core: looking for candidates for <Requirement('pydantic-core==2.18.4')>
11:17:52 INFO pydantic-core: selecting <pydantic-core==2.18.4>
11:17:52 INFO pydantic-core: successfully resolved <Requirement('pydantic-core==2.18.4')>
11:17:52 INFO pydantic-core: new toplevel dependency pydantic-core==2.18.4 resolves to 2.18.4
11:17:52 INFO pydantic-core: looking for existing wheel for version 2.18.4 with build tag () in ./wheels-repo/build
11:17:52 INFO pydantic-core: looking for existing wheel for version 2.18.4 with build tag () in ./wheels-repo/downloads
11:17:52 INFO pydantic-core: checking if wheel was already uploaded to http://localhost:55873/simple/
11:17:52 INFO pydantic-core: looking for candidates for <Requirement('pydantic-core==2.18.4')>
11:17:52 INFO pydantic-core: did not find wheel for 2.18.4 in http://localhost:55873/simple/
11:17:52 INFO pydantic-core: downloading source for pydantic-core==2.18.4
11:17:52 INFO pydantic-core: saved ./sdists-repo/downloads/pydantic_core-2.18.4.tar.gz
11:17:52 INFO pydantic-core: preparing source for pydantic-core==2.18.4 from ./sdists-repo/downloads/pydantic_core-2.18.4.tar.gz
11:17:52 INFO pydantic-core: updating vendored rust dependencies in ./work-dir/pydantic_core-2.18.4/pydantic_core-2.18.4
11:17:54 INFO pydantic-core: prepared source for pydantic-core==2.18.4 at ./work-dir/pydantic_core-2.18.4/pydantic_core-2.18.4
11:17:54 INFO pydantic-core: created build environment in ./work-dir/pydantic_core-2.18.4/build-3.11.13
11:17:54 INFO pydantic-core: getting build system dependencies for pydantic-core==2.18.4 in ./work-dir/pydantic_core-2.18.4/pydantic_core-2.18.4
11:17:54 INFO maturin: looking for candidates for <Requirement('maturin<2,>=1')>
11:17:54 INFO maturin: selecting <maturin==1.9.0>

...
```

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

### Git URL Example in Requirements

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/customization.md

Illustrates how to specify Git URLs for packages in a requirements file, including version tags.

```text
my-package @ git+https://github.com/example/repo.git@v1.2.3
```

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

### Project Build using the 'build' Module

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/develop.md

Alternative method to build the project using the standard `build` module, including installing necessary dependencies.

```bash
# Install build dependencies:
pip install build twine

# Build the project:
python -m build
```

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

### Fromager Settings Directory Example

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/customization.md

Demonstrates how to specify a custom directory for Fromager settings files using the `--settings-dir` command-line option.

```shell
fromager --settings-dir=overrides/settings ...
```

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

### Fromager Production Build Process

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/using.md

Details the steps involved in a production build using the 'fromager build' command. This process includes version resolution, source acquisition, source preparation, build environment setup, source distribution creation, wheel building, and post-build processing for a single package.

```python
# The build command takes as input the distribution name and version to build, the variant, and the URL where it is acceptable to download source distributions.
# The server URL is usually a simple index URL for an internal package index.
# The outputs are one patched source distribution and one built wheel.

# Example conceptual usage (actual command might vary based on fromager implementation):
# fromager build --distribution <name> --version <version> --variant <variant> --source-url <url>
```

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

### Canonicalize Command Example

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/customization.md

Demonstrates the usage of the `canonicalize` command provided by Fromager to convert package names into their standardized format, replacing hyphens with underscores.

```console
$ tox -e cli -- canonicalize flit-core
flit_core
```

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

### Pydantic-core Wheel Build Process

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/getting-started.rst

This snippet details the build process for the pydantic-core Python package, including dependency installation, source distribution building, and wheel creation. It highlights the specific version of pydantic-core and the target architecture.

```log
11:19:11 INFO pydantic-core: installed dependencies {<Requirement('maturin<2,>=1')>, <Requirement('typing-extensions!=4.7.0,>=4.6.0')>} into build environment in ./work-dir/pydantic_core-2.18.4/build-3.11.13
11:19:11 INFO pydantic-core: getting build backend dependencies for pydantic-core==2.18.4 in ./work-dir/pydantic_core-2.18.4/pydantic_core-2.18.4
11:19:11 INFO pydantic-core: getting build sdist dependencies for pydantic-core==2.18.4 in ./work-dir/pydantic_core-2.18.4/pydantic_core-2.18.4
11:19:11 INFO pydantic-core: building cpu source distribution for pydantic-core==2.18.4 in ./work-dir/pydantic_core-2.18.4/pydantic_core-2.18.4
11:19:14 INFO pydantic-core: built source distribution ./sdists-repo/builds/pydantic-core-2.18.4.tar.gz
11:19:14 INFO pydantic-core: starting build of toplevel dependency pydantic-core==2.18.4 (2.18.4) for cpu
11:19:14 INFO pydantic-core: building cpu wheel for pydantic-core==2.18.4 in ./work-dir/pydantic_core-2.18.4/pydantic_core-2.18.4 writing to ./wheels-repo/build
11:19:56 INFO pydantic-core: added extra metadata and build tag (0, ''), wheel renamed from pydantic_core-2.18.4-cp311-cp311-macosx_11_0_arm64.whl to pydantic_core-2.18.4-0-cp311-cp311-macosx_11_0_arm64.whl
11:19:56 INFO pydantic-core: adding pydantic_core-2.18.4-0-cp311-cp311-macosx_11_0_arm64.whl to local wheel server
11:19:56 INFO pydantic-core: built wheel for version 2.18.4: ./wheels-repo/downloads/pydantic_core-2.18.4-0-cp311-cp311-macosx_11_0_arm64.whl
11:19:56 INFO pydantic-core: getting installation dependencies from ./wheels-repo/downloads/pydantic_core-2.18.4-0-cp311-cp311-macosx_11_0_arm64.whl
11:19:56 INFO pydantic-core: adding ('pydantic-core', '2.18.4') to build order
```

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

### Containerfile for Build Environment

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/how-tos/containers.rst

Defines the Dockerfile (Containerfile) used to create the build environment. It installs Python, Rust, and the 'fromager' package within a Universal Base Image (UBI).

```dockerfile
FROM registry.access.redhat.com/ubi9/ubi:latest

RUN yum update -y && \
    yum install -y python3 python3-pip rust && \
    pip3 install --upgrade pip && \
    pip3 install fromager

# Add any other necessary setup here

```

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

### Pyproject.toml Build Requirements Update

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/customization.md

Shows an example of an incoming `pyproject.toml` file and the resulting output after applying the `project_override` configuration to update the build requirements.

```yaml
[build-system]
requires = ["cmake", "setuptools>48.0", "torch>=2.3.0"]

```

```yaml
[build-system]
requires = ["setuptools>=68.0.0", "torch", "triton"]

```

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

### Example requirements.txt for Linting

Source: https://github.com/python-wheel-build/fromager/blob/main/e2e/validate_inputs/constraints.txt

This requirements.txt file is used for testing the lint_requirements command within the fromager project. It includes specific versions of packages to ensure consistent testing environments.

```python
gast==0.5.5
torch==2.3.1
```

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

### Apply Constraints File to Fromager

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/how-tos/pre-release-versions.rst

Shows the command-line usage of 'fromager' with the '--constraints-file' option to apply pre-release version specifications defined in a constraints file. This example demonstrates how constraints can override default stable version resolution.

```console
$ fromager --constraints-file constraints.txt bootstrap mypackage
```

```console
$ fromager --constraints-file constraints.txt bootstrap "flit-core<2.0.1"
```

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

### requirements.txt with Git Submodules

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/example/requirements-git-example.txt

Example of a requirements.txt file demonstrating how to include packages directly from Git repositories using git+https:// URLs. This format supports specifying tags, branches, or commit hashes, and can be configured with git submodule support in package settings.

```python
# Example requirements.txt with git submodules support
# This file shows how to specify git+https:// URLs in requirements.txt
# that can be configured with git submodules support

# Standard PyPI package
pydantic-core==2.18.4

# Git repository URL with tag (configure git_options in package settings)
my-package @ git+https://github.com/example/repo.git@v1.2.3

# Git repository URL with branch
dev-package @ git+https://github.com/example/dev-repo.git@main

# Git repository URL with commit hash
fixed-package @ git+https://github.com/example/fixed-repo.git@abc123def456
```

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

### Patch Directory Structure Example

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/customization.md

Illustrates the expected directory structure for patch files used by Fromager. Patches are organized by package name and version, with subdirectories for variants like 'cpu' or 'rocm'.

```console
tree overrides/patches/
overrides/patches/
├── test_pkg
│   ├── 010-unversioned.patch
│   └── cpu
│       └── 004-cpu.patch
└── test_pkg-1.0.2
    ├── 001-somepatch.patch
    ├── 002-otherpatch.patch
    ├── cpu
    │   └── 005-cpuver.patch
    └── rocm
        └── 005-rocmver.patch
```

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

### Skip Constraints Generation in Fromager

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/using.md

Demonstrates how to use the `--skip-constraints` option with the `fromager bootstrap` command to build collections with potentially conflicting package versions. This bypasses `constraints.txt` generation, allowing for flexibility in managing package dependencies, though the resulting collection might not be directly installable with pip.

```bash
fromager bootstrap --skip-constraints package1==1.0 package2==2.0
```

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

### Custom Tag Matching Function

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/hooks.rst

Provides an example of a custom tag matching function that converts specific tag formats into Version objects. It handles tags starting with 'project-' and ignores others.

```python
from packaging.version import Version

def custom_tag_match(identifier: str, item: str) -> Version | None:
    # project-1_2_3 -> 1.2.3
    if item.startswith("project-"):
        return Version(item[8:].replace("_", "."))
    # ignore other tags
    return None
```

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

### Quick Project Build with Hatch

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/develop.md

Commands to quickly build both source distributions (.tar.gz) and wheels (.whl) for the project using Hatch.

```bash
# Build both sdist and wheel:
hatch build

# Build specific formats:
hatch build -t wheel
hatch build -t sdist
```

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

### Configure post_bootstrap Hook

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/customization.md

This snippet demonstrates how to configure the 'post_bootstrap' hook in pyproject.toml. This hook executes after a package is bootstrapped and before its installation dependencies are processed.

```toml
[project.entry-points."fromager.hooks"]
post_bootstrap = "package_plugins.module:function"
```

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

### High-Level Bootstrap Process Steps

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/using.md

This outlines the key steps involved in the fromager bootstrap process for each package, including version resolution, cache checking, source preparation, dependency resolution, the build process, dependency discovery, and recursive processing.

```APIDOC
High-Level Bootstrap Process:

1. Version Resolution:
   - Determines specific version based on constraints, requirements, history, and available sources (PyPI, git, wheels).

2. Cache Checking:
   - Checks local build cache (`wheels-repo/build/`), local download cache (`wheels-repo/downloads/`), and remote wheel server cache.

3. Source Preparation (if no cached wheel):
   - Downloads source distribution or clones git repository.
   - Unpacks and applies patches via overrides.
   - Prepares source tree for building.

4. Build Dependencies Resolution:
   - Recursively processes:
     - Build System dependencies (e.g., setuptools, poetry-core).
     - Build Backend dependencies (from `get_requires_for_build_wheel()` hook).
     - Build Sdist dependencies (from `Requires-Dist` in metadata).

5. Build Process:
   - Builds source distribution (sdist) with patches.
   - Builds wheel from prepared source (unless `--sdist-only`).
   - Updates local wheel repository mirror.

6. Dependency Discovery:
   - Extracts installation dependencies from:
     - Built wheel metadata (preferred).
     - Source distribution metadata (in `--sdist-only` mode).

7. Recursive Processing:
   - Repeats the entire process for each discovered installation dependency.

8. Build Order Tracking:
   - Maintains dependency graph and build order in:
     - `build-order.json` (sequential order for production).
     - `graph.json` (complete dependency graph).
```

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

### Successful Bootstrap with Pre-built pydantic-core

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/how-tos/containers.rst

This console output illustrates a successful `bootstrap.sh` execution after marking 'pydantic-core' as pre-built. It shows that the package is now treated as pre-built, and the wheel is downloaded from PyPI, allowing the build process to complete.

```console
$ podman run -it --rm --security-opt label=disable --volume ./bootstrap-output:/work/bootstrap-output:rw,exec --volume ./bootstrap-ccache:/var/cache/ccache:rw,exec --volume ././constraints.txt:/bootstrap-inputs/constraints.txt --volume ././requirements.txt:/bootstrap-inputs/requirements.txt wheels-builder fromager --constraints-file /bootstrap-inputs/constraints.txt --log-file=bootstrap-output/bootstrap.log --sdists-repo=bootstrap-output/sdists-repo --wheels-repo=bootstrap-output/wheels-repo --work-dir=bootstrap-output/work-dir bootstrap -r /bootstrap-inputs/requirements.txt
logging debug information to bootstrap-output/bootstrap.log
primary settings file: overrides/settings.yaml
per-package settings dir: overrides/settings
variant: cpu-ubi9
patches dir: overrides/patches
maximum concurrent jobs: None
constraints file: /bootstrap-inputs/constraints.txt
wheel server url:
network isolation: True
```

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

### Dependency Resolution and Bootstrapping Times

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/getting-started.rst

This snippet shows the process of resolving and bootstrapping various Python dependencies, including their build times. It lists packages like flit-core, maturin, packaging, pydantic-core, semantic-version, setuptools-rust, setuptools, setuptools-scm, and typing-extensions, along with the time taken for each stage of their build.

```log
11:19:56 INFO typing-extensions: looking for candidates for <Requirement('typing-extensions!=4.7.0,>=4.6.0')>
11:19:56 INFO typing-extensions: selecting <typing-extensions==4.14.0>
11:19:56 INFO typing-extensions: successfully resolved <Requirement('typing-extensions!=4.7.0,>=4.6.0')>
11:19:56 INFO writing installation dependencies to ./work-dir/constraints.txt
11:19:56 INFO Bootstrapping flit_core==3.12.0 took 0:00:01 total, 0:00:00 to resolve source, 0:00:00 to download source, 0:00:00 to prepare source, 0:00:00 to build sdist, 0:00:00 to add extra metadata to wheels, 0:00:01 to build wheels
11:19:56 INFO Bootstrapping maturin==1.9.0 took 0:00:58 total, 0:00:00 to resolve source, 0:00:00 to download source, 0:00:08 to prepare source, 0:00:12 to build sdist, 0:00:01 to add extra metadata to wheels, 0:00:37 to build wheels
11:19:56 INFO Bootstrapping packaging==25.0 took 0:00:01 total, 0:00:00 to resolve source, 0:00:00 to download source, 0:00:00 to prepare source, 0:00:00 to build sdist, 0:00:00 to add extra metadata to wheels, 0:00:00 to build wheels
11:19:56 INFO Bootstrapping pydantic-core==2.18.4 took 0:00:49 total, 0:00:02 to resolve source, 0:00:00 to download source, 0:00:02 to prepare source, 0:00:03 to build sdist, 0:00:00 to add extra metadata to wheels, 0:00:42 to build wheels
11:19:56 INFO Bootstrapping semantic_version==2.10.0 took 0:00:01 total, 0:00:00 to resolve source, 0:00:00 to download source, 0:00:00 to prepare source, 0:00:00 to build sdist, 0:00:00 to add extra metadata to wheels, 0:00:01 to build wheels
11:19:56 INFO Bootstrapping setuptools-rust==1.11.1 took 0:00:01 total, 0:00:00 to resolve source, 0:00:00 to download source, 0:00:00 to prepare source, 0:00:00 to build sdist, 0:00:00 to add extra metadata to wheels, 0:00:01 to build wheels
11:19:56 INFO Bootstrapping setuptools==80.9.0 took 0:00:04 total, 0:00:00 to resolve source, 0:00:00 to download source, 0:00:00 to prepare source, 0:00:01 to build sdist, 0:00:00 to add extra metadata to wheels, 0:00:02 to build wheels
11:19:56 INFO Bootstrapping setuptools_scm==8.3.1 took 0:00:01 total, 0:00:00 to resolve source, 0:00:00 to download source, 0:00:00 to prepare source, 0:00:00 to build sdist, 0:00:00 to add extra metadata to wheels, 0:00:01 to build wheels
11:19:56 INFO Bootstrapping typing-extensions==4.14.0 took 0:00:01 total, 0:00:00 to resolve source, 0:00:00 to download source, 0:00:00 to prepare source, 0:00:00 to build sdist, 0:00:00 to add extra metadata to wheels, 0:00:00 to build wheels
```

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

### Hatch Testing Commands

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/develop.md

Commands for running unit tests and generating coverage reports using Hatch. Includes options for running all tests, specific files, or tests matching a pattern.

```bash
hatch run test:test
hatch run test:test tests/test_bootstrapper.py
hatch run test:test -k "test_metadata"
hatch run test:coverage-report
```

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

### Invalid Constraints File Example

Source: https://github.com/python-wheel-build/fromager/blob/main/e2e/validate_inputs/invalid-constraints.txt

This snippet shows an intentionally invalid constraints file used for testing the 'lint-requirements' command in the 'fromager' tool. It specifies a package version with an invalid format.

```python
# This constraints file is invalid on purpose to test the lint-requirements 
# command of fromager. Do not attempt to fix this file
vllm[tensorizer]==0.9.4
```

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

### Invalid Requirements File Example

Source: https://github.com/python-wheel-build/fromager/blob/main/e2e/validate_inputs/invalid-requirements.txt

This snippet demonstrates an intentionally invalid requirements file used to test the lint-requirements command in Fromager. It highlights common syntax errors that the tool is designed to detect.

```python
# This requirements file is invalid on purpose to test the lint-requirements 
# command of fromager. Do not attempt to fix this file

foo==
bar<=
```

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

### Project Override Configuration Example

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/customization.md

Demonstrates how to configure the `project_override` section in `pyproject.toml` to manage build requirements. It shows how to remove specific build requirements and update or add others with version constraints.

```yaml
project_override:
    remove_build_requires:
        - cmake
    update_build_requires:
        - setuptools>=68.0.0
        - torch
        - triton
```

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

### Fromager Configuration Files

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/getting-started.rst

Describes the essential configuration files for fromager: `requirements.txt` for top-level dependencies and `constraints.txt` for managing version conflicts across different packages.

```text
requirements.txt:
  # List of top-level dependencies
  pydantic-core==2.18.4

constraints.txt:
  # List of version constraints for common dependencies
  # Example: some-library==1.2.3
```

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

### Build Production Packages with Constraints

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/how-tos/bootstrap-constraints.rst

This console command illustrates how to use a constraints file with the 'fromager build-sequence' command to build production packages, ensuring that the specified version constraints are applied.

```console
$ fromager --constraints-file constraints.txt build-sequence ./work-dir/build-order.json
```

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

### Running fromager with --skip-constraints

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/example/skip-constraints-example.md

Command to execute the `fromager bootstrap` process, utilizing the `--skip-constraints` option to allow building packages with version conflicts. It specifies repositories for sdists and wheels, a working directory, and the requirements file.

```bash
fromager bootstrap --skip-constraints \
  --sdists-repo ./sdists-repo \
  --wheels-repo ./wheels-repo \
  --work-dir ./work-dir \
  -r requirements-conflicting.txt
```

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

### Bootstrap Package with Constraints

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/how-tos/bootstrap-constraints.rst

This console command demonstrates how to use a constraints file with the 'fromager bootstrap' command to build a package while adhering to specified version constraints.

```console
$ fromager --constraints-file constraints.txt bootstrap my-package
```

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

### Console Output: Applying Patch and Building pydantic-core

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/how-tos/containers.rst

This console output demonstrates Fromager applying a patch to pydantic-core and successfully building its wheel. It highlights the steps from handling requirements to building the final wheel.

```console
pydantic-core: * handling toplevel requirement pydantic-core==2.18.4 []
pydantic-core: new toplevel dependency pydantic-core==2.18.4 resolves to 2.18.4
pydantic-core: preparing source for pydantic-core==2.18.4 from /work/bootstrap-output/sdists-repo/downloads/pydantic_core-2.18.4.tar.gz
applying patch file overrides/patches/pydantic_core-2.18.4/0001-rust-version.patch to /work/bootstrap-output/work-dir/pydantic_core-2.18.4/pydantic_core-2.18.4
pydantic-core: updating vendored rust dependencies in /work/bootstrap-output/work-dir/pydantic_core-2.18.4/pydantic_core-2.18.4
pydantic-core: prepared source for pydantic-core==2.18.4 at /work/bootstrap-output/work-dir/pydantic_core-2.18.4/pydantic_core-2.18.4
pydantic-core: getting build system dependencies for pydantic-core==2.18.4 in /work/bootstrap-output/work-dir/pydantic_core-2.18.4/pydantic_core-2.18.4
pydantic-core: getting build backend dependencies for pydantic-core==2.18.4 in /work/bootstrap-output/work-dir/pydantic_core-2.18.4/pydantic_core-2.18.4
pydantic-core: getting build sdist dependencies for pydantic-core==2.18.4 in /work/bootstrap-output/work-dir/pydantic_core-2.18.4/pydantic_core-2.18.4
pydantic-core: adding ('pydantic-core', '2.18.4') to build order
pydantic-core: preparing to build wheel for version 2.18.4
created build environment in /work/bootstrap-output/work-dir/pydantic_core-2.18.4/build-3.11.7
installed dependencies into build environment in /work/bootstrap-output/work-dir/pydantic_core-2.18.4/build-3.11.7
pydantic-core: building source distribution in /work/bootstrap-output/work-dir/pydantic_core-2.18.4/pydantic_core-2.18.4
pydantic-core: built source distribution /work/bootstrap-output/sdists-repo/builds/pydantic_core-2.18.4.tar.gz
pydantic-core: building wheel for pydantic-core==2.18.4 in /work/bootstrap-output/work-dir/pydantic_core-2.18.4/pydantic_core-2.18.4 writing to /work/bootstrap-output/wheels-repo/build
pydantic-core: Requires libraries: libc.so.6, libgcc_s.so.1, libm.so.6
pydantic-core: added extra metadata and build tag (0, ''), wheel renamed from pydantic_core-2.18.4-cp311-cp311-linux_x86_64.whl to pydantic_core-2.18.4-0-cp311-cp311-linux_x86_64.whl
pydantic-core: built wheel '/work/bootstrap-output/wheels-repo/build/pydantic_core-2.18.4-0-cp311-cp311-linux_x86_64.whl' in 0:03:53
pydantic-core: built wheel for version 2.18.4: /work/bootstrap-output/wheels-repo/downloads/pydantic_core-2.18.4-0-cp311-cp311-linux_x86_64.whl
```

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

### Decorating Functions with Fromager Retry Logic

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/http-retry.md

Python example of using the `retry_on_exception` decorator from Fromager to automatically retry a function based on a list of specified exceptions, with configurable retry attempts, backoff factor, and maximum backoff time.

```python
from fromager.http_retry import retry_on_exception, RETRYABLE_EXCEPTIONS

@retry_on_exception(
    exceptions=RETRYABLE_EXCEPTIONS,
    max_attempts=3,
    backoff_factor=1.0,
    max_backoff=30.0,
)
def download_metadata(url):
    # Your download logic here
    pass
```

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

### Use Constraints File for Pre-release Versions

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/how-tos/pre-release-versions.rst

Illustrates how to use a constraints file to enable pre-release versions for package builds with 'fromager'. This method is useful for managing multiple pre-release requirements or overriding stable version preferences.

```text
mypackage==1.0rc3
```

```text
flit-core==2.0rc3
```

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

### Run Parallel Jobs with Fromager

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/how-tos/parallel.rst

Demonstrates how to use the `--jobs` option in Fromager to control the maximum number of parallel wheel build jobs. This example shows running the bootstrap command with a limit of 4 parallel jobs.

```bash
fromager --jobs 4 bootstrap torch
```

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

### Step-by-Step Build Commands

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/using.md

Provides granular control over the Python wheel build process, allowing individual steps to be scripted. These commands mirror the operations performed by the `build` and `build-sequence` commands.

```APIDOC
step download-source-archive:
  description: Finds and downloads the source distribution for a specific version of a dependency from a package index.
  parameters:
    - package_index: The package index server URL (e.g., pypi.org).
  usage:
    step download-source-archive --package-index https://pypi.org/ simple/ --dependency-name "some-package" --dependency-version "1.0.0"

step prepare-source:
  description: Unpacks the source archive and applies any patches.
  dependencies: Requires output from `step download-source-archive`.
  customization: Refer to [customization](customization.md) for patching details.
  usage:
    step prepare-source --source-archive-path "/path/to/downloaded/archive.tar.gz" --patch-dir "/path/to/patches"

step prepare-build:
  description: Creates a virtualenv with the necessary build dependencies.
  parameters:
    - wheel-server-url: URL to control where built wheels can be downloaded.
  usage:
    step prepare-build --wheel-server-url "http://localhost:8000/"

step build-sdist:
  description: Creates a new source distribution ('sdist') from the prepared source tree, including patches or vendored code.
  dependencies: Requires output from `step prepare-source`.
  usage:
    step build-sdist

step build-wheel:
  description: Creates a wheel using the build environment and prepared source, compiling extensions as needed.
  dependencies: Requires output from `step prepare-build` and `step build-sdist`.
  customization: Refer to [customization](customization.md) for override environment settings.
  usage:
    step build-wheel --override-env "CFLAGS=-O3"
```

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

### Skip Constraints Generation

Source: https://github.com/python-wheel-build/fromager/blob/main/docs/files.md

Demonstrates how to skip the generation of the constraints.txt file during the bootstrap process using the `--skip-constraints` option. This is useful for building package collections where version conflicts are acceptable.

```bash
fromager bootstrap --skip-constraints package1 package2
```