`runfiles.runfiles`

Runfiles lookup library for Bazel-built Python binaries and tests.

See @rules_python//python/runfiles/README.md for usage instructions.

Added in version 1.7.0: Support for Bazel’s --incompatible_compact_repo_mapping_manifest flag was added. This enables prefix-based repository mappings to reduce memory usage for large dependency graphs under bzlmod.

Module Contents

Classes

`Runfiles`	Returns the runtime location of runfiles.
`_DirectoryBased`	`Runfiles` strategy that appends runfiles paths to the runfiles root.
`_ManifestBased`	`Runfiles` strategy that parses a runfiles-manifest to look up runfiles.
`_RepositoryMapping`	Repository mapping for resolving apparent repository names to canonical ones.

Functions

`Create`
`CreateDirectoryBased`
`CreateManifestBased`

Data

_Runfiles

API

runfiles.runfiles.Create(env: Optional[Dict[str, str]] = None) → Optional[runfiles.runfiles.Runfiles]

runfiles.runfiles.CreateDirectoryBased(runfiles_dir_path: str) → runfiles.runfiles.Runfiles

runfiles.runfiles.CreateManifestBased(manifest_path: str) → runfiles.runfiles.Runfiles

class runfiles.runfiles.Runfiles(strategy: Union[runfiles.runfiles._ManifestBased, runfiles.runfiles._DirectoryBased])

Returns the runtime location of runfiles.

Runfiles are data-dependencies of Bazel-built binaries and tests.

static Create(env: Optional[Dict[str, str]] = None) → Optional[runfiles.runfiles.Runfiles]

Returns a new Runfiles instance.

The returned object is either:

manifest-based, meaning it looks up runfile paths from a manifest file, or
directory-based, meaning it looks up runfile paths under a given directory path

If env contains “RUNFILES_MANIFEST_FILE” with non-empty value, this method returns a manifest-based implementation. The object eagerly reads and caches the whole manifest file upon instantiation; this may be relevant for performance consideration.

Otherwise, if env contains “RUNFILES_DIR” with non-empty value (checked in this priority order), this method returns a directory-based implementation.

If neither cases apply, this method returns null.

Args: env: {string: string}; optional; the map of environment variables. If None, this function uses the environment variable map of this process. Raises: IOError: if some IO error occurs.

static CreateDirectoryBased(runfiles_dir_path: str) → runfiles.runfiles.Runfiles

static CreateManifestBased(manifest_path: str) → runfiles.runfiles.Runfiles

CurrentRepository(frame: int = 1) → str

Returns the canonical name of the caller’s Bazel repository.

For example, this function returns ‘’ (the empty string) when called from the main repository and a string of the form ‘rules_python~0.13.0` when called from code in the repository corresponding to the rules_python Bazel module.

More information about the difference between canonical repository names and the @repo part of labels is available at: https://bazel.build/build/bzlmod#repository-names

NOTE: This function inspects the callstack to determine where in the runfiles the caller is located to determine which repository it came from. This may fail or produce incorrect results depending on who the caller is, for example if it is not represented by a Python source file. Use the frame argument to control the stack lookup.

Args: frame: int; the stack frame to return the repository name for. Defaults to 1, the caller of the CurrentRepository function.

Returns: The canonical name of the Bazel repository containing the file containing the frame-th caller of this function

Raises: ValueError: if the caller cannot be determined or the caller’s file path is not contained in the Python runfiles tree

EnvVars() → Dict[str, str]

Returns environment variables for subprocesses.

The caller should set the returned key-value pairs in the environment of subprocesses in case those subprocesses are also Bazel-built binaries that need to use runfiles.

Returns: {string: string}; a dict; keys are environment variable names, values are the values for these environment variables

Rlocation(path: str, source_repo: Optional[str] = None) → Optional[str]

Returns the runtime path of a runfile.

Runfiles are data-dependencies of Bazel-built binaries and tests.

The returned path may not be valid. The caller should check the path’s validity and that the path exists.

The function may return None. In that case the caller can be sure that the rule does not know about this data-dependency.

Args: path: string; runfiles-root-relative path of the runfile source_repo: string; optional; the canonical name of the repository whose repository mapping should be used to resolve apparent to canonical repository names in path. If None (default), the repository mapping of the repository containing the caller of this method is used. Explicitly setting this parameter should only be necessary for libraries that want to wrap the runfiles library. Use CurrentRepository to obtain canonical repository names. Returns: the path to the runfile, which the caller should check for existence, or None if the method doesn’t know about this runfile Raises: TypeError: if path is not a string ValueError: if path is None or empty, or it’s absolute or not normalized

__init__(strategy: Union[runfiles.runfiles._ManifestBased, runfiles.runfiles._DirectoryBased]) → None

class runfiles.runfiles._DirectoryBased(path: str)

Runfiles strategy that appends runfiles paths to the runfiles root.

EnvVars() → Dict[str, str]

RlocationChecked(path: str) → str

_GetRunfilesDir() → str

__init__(path: str) → None

class runfiles.runfiles._ManifestBased(path: str)

Runfiles strategy that parses a runfiles-manifest to look up runfiles.

EnvVars() → Dict[str, str]

RlocationChecked(path: str) → Optional[str]: Returns the runtime path of a runfile.

_GetRunfilesDir() → str

static _LoadRunfiles(path: str) → Dict[str, str]: Loads the runfiles manifest.

__init__(path: str) → None

class runfiles.runfiles._RepositoryMapping(exact_mappings: Dict[Tuple[str, str], str], prefixed_mappings: Dict[Tuple[str, str], str])

Repository mapping for resolving apparent repository names to canonical ones.

Handles both exact mappings and prefix-based mappings introduced by the –incompatible_compact_repo_mapping_manifest flag.

__init__(exact_mappings: Dict[Tuple[str, str], str], prefixed_mappings: Dict[Tuple[str, str], str]) → None

Initialize repository mapping with exact and prefixed mappings.

Args: exact_mappings: Dict mapping (source_canonical, target_apparent) -> target_canonical prefixed_mappings: Dict mapping (source_prefix, target_apparent) -> target_canonical

static create_from_file(repo_mapping_path: Optional[str]) → runfiles.runfiles._RepositoryMapping

Create RepositoryMapping from a repository mapping manifest file.

Args: repo_mapping_path: Path to the repository mapping file, or None if not available

Returns: RepositoryMapping instance with parsed mappings

is_empty() → bool

Check if this repository mapping is empty (no exact or prefixed mappings).

Returns: True if there are no mappings, False otherwise

lookup(source_repo: Optional[str], target_apparent: str) → Optional[str]

Look up repository mapping for the given source and target.

This handles both exact mappings and prefix-based mappings introduced by the –incompatible_compact_repo_mapping_manifest flag. Exact mappings are tried first, followed by prefix-based mappings where order matters.

Args: source_repo: Source canonical repository name target_apparent: Target apparent repository name

Returns: target_canonical repository name, or None if no mapping exists

runfiles.runfiles._Runfiles = None

runfiles.runfiles