### Initial Pycross WORKSPACE Setup

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Initializes Pycross dependencies and registers toolchains. This example shows the basic setup for PDM lock model.

```bazel
# WORKSPACE
load("@rules_pycross//pycross:repositories.bzl", "rules_pycross_dependencies")
load(
    "@rules_pycross//pycross:workspace.bzl",
    "lock_repo_model_pdm",
    "lock_repo_model_poetry",
    "package_annotation",
    "pycross_lock_repo",
    "pycross_register_for_python_toolchains",
)

rules_pycross_dependencies(
    python_interpreter_target = "@python_3_12_host//:python",
)

pycross_register_for_python_toolchains(
    name                  = "pycross_toolchains",
    python_toolchains_repo = "@python",
    platforms = [
        "aarch64-apple-darwin",
        "aarch64-unknown-linux-gnu",
        "x86_64-unknown-linux-gnu",
    ],
    glibc_version = "2.28",
    macos_version = "14.0",
)

load("@pycross_toolchains//:defs.bzl", "environments")

pycross_lock_repo(
    name = "pdm",
    lock_model = lock_repo_model_pdm(
        project_file = "@//:pyproject.toml",
        lock_file    = "@//:pdm.lock",
    ),
    target_environments = environments,
    annotations = {
        "grpclib": package_annotation(
            always_build       = True,
            build_dependencies = ["setuptools", "wheel"],
        ),
        "matplotlib": package_annotation(
            post_install_patches = ["@my_workspace//:matplotlib.patch"],
        ),
    },
)

load("@pdm//:defs.bzl", "install_deps")
install_deps()
```

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

### Psycopg2 Wheel Filename Example

Source: https://github.com/jvolkman/rules_pycross/blob/main/examples/external_linking/deps/psycopg2/README.md

This is an example of the actual wheel filename generated for psycopg2, including version and platform tags.

```text
psycopg2-2.9.5-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
```

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

### Install Pre-commit Hook

Source: https://github.com/jvolkman/rules_pycross/blob/main/CONTRIBUTING.md

Automate code formatting and linting by installing the pre-commit hook. This ensures consistency across the project.

```shell
pre-commit install
```

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

### Inspect Wheel Information with a Custom Rule

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

This example demonstrates how to create a custom Bazel rule that inspects a Python wheel using the `PycrossWheelInfo` provider. It accesses the wheel file and its name.

```bazel
# custom_rule.bzl
load("@rules_pycross//pycross:defs.bzl", "PycrossWheelInfo")

def _my_wheel_inspector_impl(ctx):
    wheel_info = ctx.attr.wheel[PycrossWheelInfo]
    # wheel_info.wheel_file  → the .whl File object
    # wheel_info.name_file   → a File containing the canonical wheel name string
    wheel_file = wheel_info.wheel_file
    name_file  = wheel_info.name_file
    return [DefaultInfo(files = depset([wheel_file, name_file]))]

my_wheel_inspector = rule(
    implementation = _my_wheel_inspector_impl,
    attrs = {
        "wheel": attr.label(providers = [PycrossWheelInfo]),
    },
)

# BUILD.bazel
load(":custom_rule.bzl", "my_wheel_inspector")

my_wheel_inspector(
    name  = "inspect_numpy",
    wheel = "@pdm_deps//:numpy__wheel",
)
```

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

### Install Python Wheel using pycross_wheel_library

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Extracts a Python wheel into a `py_library`-compatible Bazel target. Can install pre-built wheels or wheels produced by `pycross_wheel_build`. Supports excluding files and applying post-install patches.

```bazel
# BUILD.bazel
load("@rules_pycross//pycross:defs.bzl", "pycross_wheel_library")

# Install a pre-downloaded wheel
pycross_wheel_library(
    name  = "requests",
    wheel = "@pypi_requests_wheel//file",
    deps  = [
        ":certifi",
        ":charset-normalizer",
        ":idna",
        ":urllib3",
    ],

    # Exclude test and documentation files from the installed library
    install_exclude_globs = [
        "tests/**",
        "*.dist-info/RECORD",
    ],

    # Apply patches to installed files (e.g. fix import paths)
    post_install_patches = ["//:patches/requests_fix.patch"],

    # Required for packages using PEP 420 implicit namespace packages
    enable_implicit_namespace_pkgs = True,

    # Constrain to Python 3 only
    python_version = "PY3",
)
```

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

### Per-Package Override: Post-Install Patches

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Applies patch files to a package after its installation is complete.

```python
lock_import.package(
    name                = "matplotlib",
    repo                = "pdm_deps",
    post_install_patches = ["@@//:matplotlib.patch"],
)
```

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

### Consume Target from Instantiated Lock File Repo

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Consumes a dependency from a repository instantiated from a lock file. This example shows adding 'requests' to a `py_binary` target.

```python
# BUILD.bazel — consuming a target from the instantiated lock file repo
load("@rules_python//python:defs.bzl", "py_binary")

py_binary(
    name = "my_app",
    srcs = ["main.py"],
    deps = ["@poetry_lock_file//deps:requests"],
)
```

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

### import_uv

Source: https://github.com/jvolkman/rules_pycross/blob/main/docs/ext_lock_import.md

Import a uv lock file. This function allows for the installation of dependencies based on a lock file, with various options to control which dependencies are installed.

```APIDOC
## import_uv

### Description
Import a uv lock file. This function allows for the installation of dependencies based on a lock file, with various options to control which dependencies are installed.

### Parameters
#### Path Parameters
- **lock_file** (Label) - Required - The lock file.
- **project_file** (Label) - Required - The pyproject.toml file.
- **repo** (String) - Required - The repository name

#### Query Parameters
- **all_development_groups** (Boolean) - Optional - Install all dev dependencies. Default: `False`
- **all_optional_groups** (Boolean) - Optional - Install all optional dependencies. Default: `False`
- **default** (Boolean) - Optional - Whether to install dependencies from the default group. Default: `True`
- **default_alias_single_version** (Boolean) - Optional - Generate aliases for all packages that have a single version in the lock file. Default: `False`
- **default_build_dependencies** (List of strings) - Optional - A list of package keys (name or name@version) that will be used as default build dependencies. Default: `[]`
- **development_groups** (List of strings) - Optional - List of development dependency groups to install. Default: `[]`
- **disallow_builds** (Boolean) - Optional - If True, only pre-built wheels are allowed. Default: `False`
- **local_wheels** (List of labels) - Optional - A list of local .whl files to consider when processing lock files. Default: `[]`
- **optional_groups** (List of strings) - Optional - List of optional dependency groups to install. Default: `[]`
- **require_static_urls** (Boolean) - Optional - Require that the lock file is created with --static-urls. Default: `True`
- **target_environments** (List of labels) - Optional - A list of target environment descriptors. Default: `["@pycross_environments//:environments"]`
```

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

### Per-Package Override: Exclude Install Files

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Excludes specific files or directories from a package's installation using glob patterns.

```python
lock_import.package(
    name                 = "amqp-mock",
    repo                 = "pdm_deps",
    install_exclude_globs = ["tests/**"],
)
```

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

### Get Actual Wheel Filename

Source: https://github.com/jvolkman/rules_pycross/blob/main/examples/external_linking/deps/psycopg2/README.md

After building, the actual wheel filename is not directly predictable by Bazel. Use this command to retrieve the correct filename from a generated .name file.

```bash
cat bazel-bin/deps/psycopg2/psycopg2/psycopg2-2.9.5.whl.name
```

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

### Instantiate Lock File Repository

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Instantiates a Bazel repository from a pre-generated Pycross `.bzl` lock file. Useful when the lock file is checked into the repo and updated in CI.

```python
lock_file = use_extension("@rules_pycross//pycross/extensions:lock_file.bzl", "lock_file")

lock_file.instantiate(
    name      = "poetry_lock_file",
    lock_file = "//:poetry.lock.bzl",   # checked-in generated lock file
)

use_repo(lock_file, "poetry_lock_file")
```

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

### Declare and Create Pycross Repos

Source: https://github.com/jvolkman/rules_pycross/blob/main/docs/ext_lock_repos.md

Use this snippet to declare the lock_repos extension and then create the necessary Pycross repositories. The `pypi_index` attribute is optional and specifies the PyPI index to use.

```python
lock_repos = use_extension("@rules_pycross//pycross/extensions:lock_repos.bzl", "lock_repos")
lock_repos.create(pypi_index = "")
```

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

### Import UV Lock File (Experimental)

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Imports dependencies from a UV lock file. Requires static URLs.

```python
lock_import.import_uv(
    project_file       = "//:pyproject.toml",
    lock_file          = "//:uv.lock",
    repo               = "uv_deps",
    require_static_urls = True,
)
```

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

### Per-Package Override: Ignore Dependencies

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Ignores a specified transitive dependency, preventing it from being included in the installation.

```python
lock_import.package(
    name                = "grpcio",
    repo                = "pdm_deps",
    ignore_dependencies = ["googleapis-common-protos"],
)
```

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

### Instantiate Dependencies from Pycross Lock File

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Sets up a Bazel repository rule to load dependencies from a Pycross-generated `.bzl` lock file. This is analogous to `lock_file.instantiate` in Bzlmod.

```bazel
# WORKSPACE
load("@rules_pycross//pycross:workspace.bzl", "pycross_lock_file_repo")

pycross_lock_file_repo(
    name      = "my_deps",
    lock_file = "@//:my_generated_lock.bzl",  # generated by pycross_lock_file
)

load("@my_deps//:defs.bzl", "install_deps")
install_deps()

# BUILD.bazel
load("@rules_python//python:defs.bzl", "py_binary")

py_binary(
    name = "app",
    srcs = ["app.py"],
    deps = ["@my_deps//deps:flask"],
)
```

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

### pycross_poetry_lock_model

Source: https://github.com/jvolkman/rules_pycross/blob/main/docs/rules.md

Generates a lock model for Poetry projects. It supports specifying optional dependency groups and default installation.

```APIDOC
## pycross_poetry_lock_model

### Description
Generates a lock model for Poetry projects. It supports specifying optional dependency groups and default installation.

### Parameters
#### Required Parameters
- **name** (Name): A unique name for this target.
- **lock_file** (Label): The poetry.lock file.
- **project_file** (Label): The pyproject.toml file.

#### Optional Parameters
- **all_optional_groups** (Boolean): Install all optional dependencies. Default: `False`.
- **default** (Boolean): Whether to install dependencies from the default group. Default: `True`.
- **optional_groups** (List of strings): List of optional dependency groups to install. Default: `[]`.
```

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

### Create Lock Repos with Custom PyPI Index

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Materializes repositories and optionally configures a custom PyPI index URL for dependency resolution.

```python
lock_repos = use_extension("@rules_pycross//pycross/extensions:lock_repos.bzl", "lock_repos")

# Optionally use a private/mirror PyPI index
lock_repos.create(
    pypi_index = "https://my-private-pypi.example.com",
)

use_repo(lock_repos, "pdm_deps", "poetry_deps")
```

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

### Create Repository from Lock File (pycross_lock_file_repo)

Source: https://github.com/jvolkman/rules_pycross/blob/main/docs/workspace_rules.md

Use `pycross_lock_file_repo` to create a Bazel repository directly from a generated `.bzl` lock file. This rule requires a name and the label of the lock file. It also supports an optional `repo_mapping` attribute for controlling dependency resolution in WORKSPACE contexts.

```bazel
load("@rules_pycross//pycross:workspace.bzl", "pycross_lock_file_repo")

pycross_lock_file_repo(name, lock_file, repo_mapping)
```

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

### import_poetry

Source: https://github.com/jvolkman/rules_pycross/blob/main/docs/ext_lock_import.md

Import a Poetry lock file. This function allows for flexible installation of dependencies based on various configurations.

```APIDOC
## import_poetry

### Description
Import a Poetry lock file. This function allows for flexible installation of dependencies based on various configurations.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Attributes
- **all_optional_groups** (Boolean) - Optional - Install all optional dependencies. Default: `False`
- **default** (Boolean) - Optional - Whether to install dependencies from the default group. Default: `True`
- **default_alias_single_version** (Boolean) - Optional - Generate aliases for all packages that have a single version in the lock file. Default: `False`
- **default_build_dependencies** (List of strings) - Optional - A list of package keys (name or name@version) that will be used as default build dependencies. Default: `[]`
- **disallow_builds** (Boolean) - Optional - If True, only pre-built wheels are allowed. Default: `False`
- **local_wheels** (List of labels) - Optional - A list of local .whl files to consider when processing lock files. Default: `[]`
- **lock_file** (Label) - Required - The poetry.lock file.
- **optional_groups** (List of strings) - Optional - List of optional dependency groups to install. Default: `[]`
- **project_file** (Label) - Required - The pyproject.toml file.
- **repo** (String) - Required - The repository name
- **target_environments** (List of labels) - Optional - A list of target environment descriptors. Default: `["@pycross_environments//:environments"]`
```

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

### Create Repository from Lock File (pycross_lock_repo)

Source: https://github.com/jvolkman/rules_pycross/blob/main/docs/workspace_rules.md

Use `pycross_lock_repo` to create a Bazel repository populated with packages defined in an imported lock file. This rule requires a name, a lock model (e.g., from PDM or Poetry), and accepts additional keyword arguments.

```bazel
load("@rules_pycross//pycross:workspace.bzl", "pycross_lock_repo")

pycross_lock_repo(name, lock_model, kwargs)
```

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

### import_pdm

Source: https://github.com/jvolkman/rules_pycross/blob/main/docs/ext_lock_import.md

Import a PDM lock file. This function allows for flexible installation of dependencies based on various configurations.

```APIDOC
## import_pdm

### Description
Import a PDM lock file. This function allows for flexible installation of dependencies based on various configurations.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Attributes
- **all_development_groups** (Boolean) - Optional - Install all dev dependencies. Default: `False`
- **all_optional_groups** (Boolean) - Optional - Install all optional dependencies. Default: `False`
- **default** (Boolean) - Optional - Whether to install dependencies from the default group. Default: `True`
- **default_alias_single_version** (Boolean) - Optional - Generate aliases for all packages that have a single version in the lock file. Default: `False`
- **default_build_dependencies** (List of strings) - Optional - A list of package keys (name or name@version) that will be used as default build dependencies. Default: `[]`
- **development_groups** (List of strings) - Optional - List of development dependency groups to install. Default: `[]`
- **disallow_builds** (Boolean) - Optional - If True, only pre-built wheels are allowed. Default: `False`
- **local_wheels** (List of labels) - Optional - A list of local .whl files to consider when processing lock files. Default: `[]`
- **lock_file** (Label) - Required - The lock file.
- **optional_groups** (List of strings) - Optional - List of optional dependency groups to install. Default: `[]`
- **project_file** (Label) - Required - The pyproject.toml file.
- **repo** (String) - Required - The repository name
- **require_static_urls** (Boolean) - Optional - Require that the lock file is created with --static-urls. Default: `True`
- **target_environments** (List of labels) - Optional - A list of target environment descriptors. Default: `["@pycross_environments//:environments"]`
```

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

### Create a Dependency Repository from a Lock Model

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

The `pycross_lock_repo` WORKSPACE macro resolves dependencies from a lock model (PDM, Poetry, or UV) and sets up the full dependency repository in a single step.

```bazel
# pycross_lock_repo (WORKSPACE)

load("@rules_pycross//pycross:defs.bzl", "pycross_lock_repo")

pycross_lock_repo(
    name = "pdm_deps",
    lock_model = pycross_pdm_lock_model(
        name = "pdm_model",
        lock_file = "//:pdm.lock",
        project_file = "//:pyproject.toml",
    ),
    target_environments = ["//envs:all"],
)
```

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

### Create a Zip-Importable Wheel Library

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Use `pycross_wheel_zipimport_library` to make a wheel available for import via zipimport without extraction. This is suitable for pure-Python wheels where extraction overhead is not desired.

```bazel
# BUILD.bazel
load("@rules_pycross//pycross:defs.bzl", "pycross_wheel_zipimport_library")

pycross_wheel_zipimport_library(
    name  = "six_zip",
    wheel = "@pypi_six_wheel//file",
    deps  = [],
)

load("@rules_python//python:defs.bzl", "py_binary")

py_binary(
    name = "compat_app",
    srcs = ["compat.py"],
    deps = [":six_zip"],
)
```

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

### Define Poetry Lock Model Target

Source: https://github.com/jvolkman/rules_pycross/blob/main/docs/rules.md

Use this rule to define a Bazel target for Poetry lock file dependency management. It requires the lock file and project file labels, and supports installing optional dependency groups.

```bazel
load("@rules_pycross//pycross:defs.bzl", "pycross_poetry_lock_model")

pycross_poetry_lock_model(
    name = "my_poetry_deps",
    lock_file = "//:poetry.lock",
    project_file = "//:pyproject.toml",
    optional_groups = ["dev", "test"],
    all_optional_groups = False,
    default = True,
)
```

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

### Configure UV Lock Model for Pycross (Experimental)

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Helper function to create a UV lock model struct for `pycross_lock_repo`. UV support is experimental. Allows specifying project and lock files.

```bazel
# WORKSPACE
load(
    "@rules_pycross//pycross:workspace.bzl",
    "lock_repo_model_uv",
    "pycross_lock_repo",
)

pycross_lock_repo(
    name = "my_uv_deps",
    lock_model = lock_repo_model_uv(
        project_file        = "@//:pyproject.toml",
        lock_file           = "@//:uv.lock",
        default             = True,
        require_static_urls = True,
    ),
    target_environments = environments,
)
```

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

### Run Gazelle BUILD file updates

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Execute Gazelle to update your BUILD files. Use `bazel run //:gazelle.update` for automatic updates or `bazel run //:gazelle.check` for a dry-run to see potential changes.

```bash
# Update BUILD files with Gazelle
bazel run //:gazelle.update

# Check what would change (dry-run)
bazel run //:gazelle.check
```

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

### Import Poetry Lock File

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Imports dependencies from a Poetry lock file. Disallows sdist builds, requiring pre-built wheels only.

```python
lock_import.import_poetry(
    project_file = "//:pyproject.toml",
    lock_file    = "//:poetry.lock",
    repo         = "poetry_deps",
    default      = True,
    optional_groups       = ["docs"],
    all_optional_groups   = False,
    disallow_builds       = True,   # require pre-built wheels only
    default_alias_single_version = False,
)
```

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

### lock_file.instantiate

Source: https://github.com/jvolkman/rules_pycross/blob/main/docs/ext_lock_file.md

Creates a repository using a Pycross-generated lock file. This is the primary function to invoke for integrating lock file information into your Bazel build.

```APIDOC
## lock_file.instantiate

### Description
Create a repo given the Pycross-generated lock file.

### Method
use_extension

### Parameters
#### Path Parameters
- **name** (Name) - Required - The repo name.
- **lock_file** (Label) - Required - The lock file created by pycross_lock_file.
```

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

### Update BUILD Files with Gazelle

Source: https://github.com/jvolkman/rules_pycross/blob/main/CONTRIBUTING.md

Run Gazelle to keep generated `bzl_library` targets in BUILD files up-to-date with source files. This command should be executed from the project root.

```shell
bazel run //:gazelle
```

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

### environments.create_for_python_toolchains

Source: https://github.com/jvolkman/rules_pycross/blob/main/docs/ext_environments.md

Creates target environments for Python toolchains, specifying compatibility with different operating systems and Python versions.

```APIDOC
## environments.create_for_python_toolchains

### Description
Creates target environments for Python toolchains.

### Method
Stardoc function call

### Endpoint
`environments.create_for_python_toolchains(name, glibc_version, macos_version, musl_version, platforms, python_versions)`

### Parameters
#### Path Parameters
- **name** (Name) - Required - The target name.

#### Query Parameters
- **glibc_version** (String) - Optional - The maximum glibc version to accept for Bazel platforms that match the @platforms//os:linux constraint. Must be in the format '2.X', and greater than 2.5. All versions from 2.5 through this version will be supported. For example, if this value is set to 2.15, wheels tagged manylinux_2_5, manylinux_2_6, ..., manylinux_2_15 will be accepted. Defaults to '2.28' if unspecified.
- **macos_version** (String) - Optional - The maximum macOS version to accept for Bazel platforms that match the @platforms//os:osx constraint. Must be in the format 'X.Y' with X >= 10. All versions from 10.4 through this version will be supported. For example, if this value is set to 12.0, wheels tagged macosx_10_4, macosx_10_5, ..., macosx_11_0, macosx_12_0 will be accepted. Defaults to '15.0' if unspecified.
- **musl_version** (String) - Optional - The musl version to accept for Bazel platforms that match the @platforms//os:linux constraint when @rules_python//python/config_settings:py_linux_libc is set to 'musl'. Defaults to '1.2' if unspecified.
- **platforms** (List of strings) - Optional - The list of Python platforms to support in by default in Pycross builds. See https://github.com/bazelbuild/rules_python/blob/main/python/versions.bzl for the list of supported platforms per Python version. By default all supported platforms for each registered version are supported.
- **python_versions** (List of strings) - Optional - The list of Python versions to support in by default in Pycross builds. These strings will be X.Y or X.Y.Z depending on how versions were registered with rules_python. By default all registered versions are supported.

### Request Example
```stardoc
environments.create_for_python_toolchains(
    name = "my_env",
    glibc_version = "2.28",
    macos_version = "12.0",
    musl_version = "1.2",
    platforms = ["linux_x86_64", "macos_x86_64"],
    python_versions = ["3.9", "3.10"]
)
```

### Response
#### Success Response (200)
This function does not return a value, it creates targets.
```

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

### Build Linux Wheel for Psycopg2

Source: https://github.com/jvolkman/rules_pycross/blob/main/examples/external_linking/deps/psycopg2/README.md

Use Bazel to build a Linux wheel for the psycopg2 package. This command specifies the target and the platform for the build.

```bash
bazel build //deps/psycopg2 --platforms @zig_sdk//platform:linux_x86_64
```

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

### lock_repos.create

Source: https://github.com/jvolkman/rules_pycross/blob/main/docs/ext_lock_repos.md

Creates declared Pycross repositories using a specified PyPI-compatible index.

```APIDOC
## lock_repos.create

### Description
Create declared Pycross repos.

### Method
N/A (Stardoc extension function)

### Parameters
#### Attributes
- **pypi_index** (String) - Optional - The PyPI-compatible index to use (must support the JSON API). Defaults to "".
```

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

### Download a Specific PyPI File

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

The `pypi_file` repository rule downloads a single file from a PyPI-compatible index. It requires package name, version, filename, and SHA-256 hash. It can be used for pinned dependencies or within generated lock files.

```bazel
# WORKSPACE  or  MODULE.bazel via use_repo_rule

load("@rules_pycross//pycross:defs.bzl", "pypi_file")

pypi_file(
    name            = "pypi_requests_wheel",
    package_name    = "requests",
    package_version = "2.31.0",
    filename        = "requests-2.31.0-py3-none-any.whl",
    sha256          = "58cd2187423839f7f29baa10f68cd0d7b7bff2ab7a4a46ce4f76a06c3bca2d71",
    index           = "https://pypi.org",   # default; override for private index
    keep_metadata   = False,                # set True to inspect pypi_metadata.json
)

# Use in BUILD.bazel:
# load("@rules_pycross//pycross:defs.bzl", "pycross_wheel_library")
# pycross_wheel_library(
#     name  = "requests",
#     wheel = "@pypi_requests_wheel//file",
# )
```

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

### pypi_file

Source: https://github.com/jvolkman/rules_pycross/blob/main/docs/rules.md

Downloads a file from a PyPI-compatible package index.

```APIDOC
## pypi_file

### Description
Downloads a file from a PyPI-compatible package index.

### Parameters
#### Path Parameters
- **name** (Name) - Required - A unique name for this repository.
- **filename** (String) - Required - The name of the file to download.
- **package_name** (String) - Required - The package name.
- **package_version** (String) - Required - The package version.
- **sha256** (String) - Required - The expected SHA-256 of the file downloaded.
#### Query Parameters
- **index** (String) - Optional - The base URL of the PyPI-compatible package index to use. Defaults to pypi.org.
- **keep_metadata** (Boolean) - Optional - Whether to store the pypi_metadata.json file for debugging. Defaults to `False`.
- **repo_mapping** (Dictionary: String -> String) - Optional - In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`).

This attribute is _not_ supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function).

```

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

### Create Environments for Python Toolchains

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Creates a named set of `pycross_target_environment` targets by introspecting `rules_python` toolchains. Used for per-platform wheel selection.

```python
environments = use_extension("@rules_pycross//pycross/extensions:environments.bzl", "environments")

environments.create_for_python_toolchains(
    name           = "pycross_environments",  # repo name; produces //:environments label
    python_versions = ["3.11.11", "3.12.5"],
    platforms      = [
        "x86_64-unknown-linux-gnu",
        "aarch64-apple-darwin",
    ],
    glibc_version  = "2.28",
    macos_version  = "14.0",
    musl_version   = "1.2",
)

use_repo(environments, "pycross_environments")

# The generated repo exposes: @pycross_environments//:environments
# Pass this to pycross_lock_file's target_environments attribute.
```

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

### Configure pycross Extension in Bzlmod

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Sets up the rules_pycross toolchain, interpreter, and default target environments. Must be called before lock_import or lock_repos.

```python
# MODULE.bazel

bazel_dep(name = "rules_python", version = "1.1.0")
bazel_dep(name = "rules_pycross", version = "0.8.0")

# Register Python interpreter via rules_python
python = use_extension("@rules_python//python/extensions:python.bzl", "python")
python.toolchain(
    is_default = True,
    python_version = "3.11.11",
)
use_repo(python, "python_versions")

# Configure rules_pycross
pycross = use_extension("@rules_pycross//pycross/extensions:pycross.bzl", "pycross")

# Declare which platforms and Python versions to generate environments for
pycross.configure_environments(
    python_versions = ["3.11.11"],
    platforms = [
        "aarch64-apple-darwin",
        "aarch64-unknown-linux-gnu",
        "x86_64-unknown-linux-gnu",
        "x86_64-unknown-linux-musl",
    ],
    glibc_version = "2.28",   # accept manylinux_2_5 through manylinux_2_28
    macos_version  = "15.0",  # accept macosx_10_4 through macosx_15_0
    musl_version   = "1.2",
)

# Point to the hermetic Python interpreter for internal tool invocations
pycross.configure_interpreter(
    python_defs_file          = "@python_3_11_host//:defs.bzl",
    python_interpreter_target = "@python_3_11_host//:python",
)

# Register Pycross build toolchains (default True)
pycross.configure_toolchains(register_toolchains = True)

```

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

### Configure Gazelle for Pycross

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Set up Gazelle in your root BUILD.bazel file to use Pycross-style label normalization (PEP 503). This involves loading necessary rules and defining Gazelle directives.

```python
# Root BUILD.bazel
load("@gazelle//:def.bzl", "DEFAULT_LANGUAGES", "gazelle", "gazelle_binary")
load("@pip//:requirements.bzl", "all_whl_requirements")
load("@rules_python_gazelle_plugin//manifest:defs.bzl", "gazelle_python_manifest")
load("@rules_python_gazelle_plugin//modules_mapping:def.bzl", "modules_mapping")

# gazelle:python_root
# gazelle:python_label_convention :$distribution_name$
# gazelle:python_label_normalization pep503
gazelle_binary(
    name      = "gazelle_bin",
    languages = DEFAULT_LANGUAGES + ["@rules_python_gazelle_plugin//python"],
)

gazelle(
    name    = "gazelle.update",
    gazelle = ":gazelle_bin",
)

gazelle(
    name    = "gazelle.check",
    args    = ["-mode=diff"],
    gazelle = ":gazelle_bin",
)

modules_mapping(
    name   = "gazelle.metadata",
    tags   = ["manual"],
    wheels = all_whl_requirements,
)

gazelle_python_manifest(
    name                = "gazelle.mapping",
    modules_mapping     = ":gazelle.metadata",
    pip_repository_name = "pip",
    tags                = ["manual"],
)
```

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

### package_annotation

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Helper macro to serialize per-package customization options into a JSON string for `pycross_lock_file` and `pycross_lock_repo`.

```APIDOC
## package_annotation

A helper macro that serializes per-package customization options into a JSON string accepted by `pycross_lock_file`'s `annotations` dict and the WORKSPACE `pycross_lock_repo`'s `annotations` dict.

```python
# BUILD.bazel  (WORKSPACE-based usage)
load(
    "@rules_pycross//pycross:defs.bzl",
    "package_annotation",
    "pycross_lock_file",
    "pycross_pdm_lock_model",
)

pycross_pdm_lock_model(
    name         = "pdm_model",
    lock_file    = "//:pdm.lock",
    project_file = "//:pyproject.toml",
)

pycross_lock_file(
    name            = "pdm_lock",
    out             = "pdm_lock.bzl",
    lock_model_file = ":pdm_model",
    target_environments = ["//envs:all"],
    annotations = {
        # Force sdist build with extra build-time deps
        "numpy": package_annotation(
            always_build       = True,
            build_dependencies = ["setuptools", "wheel", "cython"],
        ),

        # Use a completely custom build target
        "tensorflow": package_annotation(
            build_target = "//third_party/tensorflow:build",
        ),

        # Drop an optional/circular dependency
        "sphinx": package_annotation(
            ignore_dependencies = ["docutils@0.17"],
        ),

        # Exclude large data files from installation
        "torch": package_annotation(
            install_exclude_globs = ["*.pdb", "test/**"],
        ),

        # Apply a source patch after installation
        "pillow": package_annotation(
            post_install_patches = ["//:patches/pillow_jpeg2000.patch"],
        ),
    },
)
```
```

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

### Define a Python Binary with Dependencies

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

This snippet shows how to define a Python binary target in Bazel, specifying its source files and dependencies, including a custom rule dependency.

```bazel
load("@rules_python//python:defs.bzl", "py_binary")

py_binary(
    name = "my_app",
    srcs = ["main.py"],
    deps = [":requests"],
)
```

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

### Gazelle BUILD.bazel Configuration for rules_pycross

Source: https://github.com/jvolkman/rules_pycross/blob/main/README.md

This configuration sets up Gazelle to work with rules_pycross, enabling Python name normalization and integration with the rules_python_gazelle_plugin. Ensure this is placed in your BUILD.bazel file.

```bazel
load("@gazelle//:def.bzl", "DEFAULT_LANGUAGES", "gazelle", "gazelle_binary")
load("@pip//:requirements.bzl", "all_whl_requirements")
load("@rules_python_gazelle_plugin//manifest:defs.bzl", "gazelle_python_manifest")
load("@rules_python_gazelle_plugin//modules_mapping:def.bzl", "modules_mapping")

# gazelle:python_root
# gazelle:python_label_convention :$distribution_name$
# gazelle:python_label_normalization pep503
gazelle_binary(
    name = "gazelle_bin",
    languages = DEFAULT_LANGUAGES + [
        "@rules_python_gazelle_plugin//python",
    ],
)

gazelle(
    name = "gazelle.update",
    gazelle = ":gazelle_bin",
)

gazelle(
    name = "gazelle.check",
    args = ["-mode=diff"],
    gazelle = ":gazelle_bin",
)

modules_mapping(
    name = "gazelle.metadata",
    tags = ["manual"],
    wheels = all_whl_requirements,
)

gazelle_python_manifest(
    name = "gazelle.mapping",
    modules_mapping = ":gazelle.metadata",
    pip_repository_name = "pip",
    tags = ["manual"],
)
```

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

### Configure Package Annotations for Lock Files

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

This snippet shows how to use `package_annotation` to define per-package customization options for `pycross_lock_file` and `pycross_lock_repo`. It covers forcing builds, custom build targets, ignoring dependencies, excluding files, and applying patches.

```bazel
# BUILD.bazel  (WORKSPACE-based usage)
load(
    "@rules_pycross//pycross:defs.bzl",
    "package_annotation",
    "pycross_lock_file",
    "pycross_pdm_lock_model",
)

pycross_pdm_lock_model(
    name         = "pdm_model",
    lock_file    = "//:pdm.lock",
    project_file = "//:pyproject.toml",
)

pycross_lock_file(
    name            = "pdm_lock",
    out             = "pdm_lock.bzl",
    lock_model_file = ":pdm_model",
    target_environments = ["//envs:all"],
    annotations = {
        # Force sdist build with extra build-time deps
        "numpy": package_annotation(
            always_build       = True,
            build_dependencies = ["setuptools", "wheel", "cython"],
        ),

        # Use a completely custom build target
        "tensorflow": package_annotation(
            build_target = "//third_party/tensorflow:build",
        ),

        # Drop an optional/circular dependency
        "sphinx": package_annotation(
            ignore_dependencies = ["docutils@0.17"],
        ),

        # Exclude large data files from installation
        "torch": package_annotation(
            install_exclude_globs = ["*.pdb", "test/**"],
        ),

        # Apply a source patch after installation
        "pillow": package_annotation(
            post_install_patches = ["//:patches/pillow_jpeg2000.patch"],
        ),
    },
)
```

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

### Configure Poetry Lock Model for Pycross

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Helper function to create a Poetry lock model struct for `pycross_lock_repo`. Supports specifying project and lock files, and optional groups.

```bazel
# WORKSPACE
load(
    "@rules_pycross//pycross:workspace.bzl",
    "lock_repo_model_poetry",
    "pycross_lock_repo",
)

pycross_lock_repo(
    name = "my_poetry_deps",
    lock_model = lock_repo_model_poetry(
        project_file        = "@//:pyproject.toml",
        lock_file           = "@//:poetry.lock",
        default             = True,
        optional_groups     = ["docs"],
        all_optional_groups = False,
    ),
    target_environments = environments,
)
```

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

### pycross_lock_repo

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

WORKSPACE macro to create a full dependency repository from a lock model (PDM, Poetry, or UV).

```APIDOC
## pycross_lock_repo (WORKSPACE)

WORKSPACE macro that creates a full dependency repository from a lock model (PDM, Poetry, or UV). Runs the lock resolver and package repo setup in a single call.

```python

```

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

### Import PDM Lock File

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Imports dependencies from a PDM lock file. Ensures static URLs are required and allows sdist builds by default.

```python
lock_import.import_pdm(
    project_file          = "//:pyproject.toml",
    lock_file             = "//:pdm.lock",
    repo                  = "pdm_deps",           # resulting repo name
    default               = True,                 # include default dependency group
    development_groups    = [],                   # extra dev groups, e.g. ["test"]
    all_development_groups = False,
    optional_groups       = [],
    all_optional_groups   = False,
    require_static_urls   = True,                 # requires `pdm lock --static-urls`
    disallow_builds       = False,                # False = sdist builds are allowed
    default_alias_single_version = True,          # :requests instead of :requests-2.31.0
    default_build_dependencies   = ["setuptools", "wheel"],
)
```

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

### Import Lock File with lock_import Extension

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Imports a Poetry, PDM, or UV lock file directly into Bzlmod. Per-package overrides can be specified using lock_import.package tags.

```python
# MODULE.bazel

lock_import = use_extension("@rules_pycross//pycross/extensions:lock_import.bzl", "lock_import")


```

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

### Register Python Toolchains (pycross_register_for_python_toolchains)

Source: https://github.com/jvolkman/rules_pycross/blob/main/docs/workspace_rules.md

Register target environments and toolchains for specified Python versions using `pycross_register_for_python_toolchains`. This rule requires a name and a label to the rules_python toolchain repo. It supports optional platform filtering and GLIBC/musl/macOS version constraints.

```bazel
load("@rules_pycross//pycross:workspace.bzl", "pycross_register_for_python_toolchains")

pycross_register_for_python_toolchains(name, python_toolchains_repo, platforms, glibc_version,
                                       musl_verison, macos_version)
```

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

### Per-Package Override: Force Build from Source

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Forces a specific package to be built from source (sdist) and specifies additional build-time dependencies.

```python
lock_import.package(
    name              = "ipython",
    repo              = "pdm_deps",
    always_build      = True,
    build_dependencies = ["setuptools", "wheel"],
)
```

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

### Define Target Environment with pycross_target_environment

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Declares a target platform environment, mapping Bazel platform constraints to Python PEP 425 wheel tags. Use this for manual environment configuration when the environments extension is not used.

```bazel
# BUILD.bazel
load("@rules_pycross//pycross:defs.bzl", "pycross_target_environment")

# Linux x86_64, Python 3.11, manylinux2014
pycross_target_environment(
    name           = "linux_x86_64_cp311",
    version        = "3.11",
    abis           = ["cp311", "abi3", "none"],
    platforms      = ["manylinux_2_17_x86_64", "manylinux2014_x86_64", "linux_x86_64"],
    implementation = "cp",
    python_compatible_with = [
        "@platforms//os:linux",
        "@platforms//cpu:x86_64",
    ],
    envornment_markers = {
        "platform_machine": "x86_64",
        "sys_platform":     "linux",
    },
)

# macOS arm64, Python 3.11
pycross_target_environment(
    name           = "macos_arm64_cp311",
    version        = "3.11",
    abis           = ["cp311", "abi3", "none"],
    platforms      = ["macosx_11_0_arm64", "macosx_10_9_universal2"],
    implementation = "cp",
    python_compatible_with = [
        "@platforms//os:osx",
        "@platforms//cpu:arm64",
    ],
)

# Select via flag value instead of platform constraint
pycross_target_environment(
    name          = "linux_x86_64_musl_cp311",
    version       = "3.11",
    abis          = ["cp311", "abi3", "none"],
    platforms     = ["musllinux_1_2_x86_64"],
    python_compatible_with = ["@platforms//os:linux", "@platforms//cpu:x86_64"],
    flag_values   = {
        "@rules_python//python/config_settings:py_linux_libc": "musl",
    },
)
```

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

### Parse UV Lock File with pycross_uv_lock_model

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Parses a UV `uv.lock` and `pyproject.toml` pair into a lock model. UV support is experimental. Configure `development_groups` and `optional_groups` as needed. `require_static_urls` defaults to true.

```bazel
# BUILD.bazel
load("@rules_pycross//pycross:defs.bzl", "pycross_uv_lock_model")

pycross_uv_lock_model(
    name                  = "uv_lock_model",
    lock_file             = "//:uv.lock",
    project_file          = "//:pyproject.toml",
    default               = True,
    development_groups    = ["dev"],
    all_development_groups = False,
    optional_groups       = [],
    all_optional_groups   = False,
    require_static_urls   = True,
)
```

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

### Build Python Wheel with Native Extensions using pycross_wheel_build

Source: https://context7.com/jvolkman/rules_pycross/llms.txt

Compiles a Python sdist into a wheel during a Bazel build. Supports custom C flags, native library dependencies, environment variables, PEP 517 config settings, and pre/post build hooks.

```bazel
# BUILD.bazel
load("@rules_pycross//pycross:defs.bzl", "pycross_wheel_build", "pycross_wheel_library")

# Build a wheel from an sdist with native C extensions
pycross_wheel_build(
    name              = "cryptography_wheel",
    sdist             = "@pypi_cryptography_sdist//file",  # http_file label
    target_environment = "@pycross_environments//:cp311_linux_x86_64",

    # Python build-time deps
    deps = [
        "@pdm_deps//:setuptools",
        "@pdm_deps//:cffi",
    ],

    # Native C/C++ deps (CcInfo providers)
    native_deps = ["@openssl//:ssl"],

    # Extra compiler and linker flags
    copts    = ["-O2"],
    linkopts = ["-lssl", "-lcrypto"],

    # Environment variables during build (supports Make variable expansion)
    build_env = {
        "OPENSSL_DIR":     "$(location @openssl//:headers)",
        "MAKEFLAGS":       "-j4",
    },

    # PEP 517 config settings (e.g. meson-python, scikit-build-core)
    config_settings = {
        "setup-args": ["-Dbuildtype=release"],
    },

    # Expose tools on PATH during build
    path_tools = {
        "@cmake//:cmake_bin": "cmake",
        "@ninja//:ninja":     "ninja",
    },

    # Scripts executed before/after wheel build
    pre_build_hooks  = [],
    post_build_hooks = ["//tools:repair_wheel"],  # e.g. auditwheel repair

    # Extra data files available to the build
    data = ["//config:build_config.json"],
)

# Install the built wheel as a py_library
pycross_wheel_library(
    name  = "cryptography",
    wheel = ":cryptography_wheel",
    deps  = ["@pdm_deps//:cffi"],
)
```