//python/private:py_info.bzl

Implementation of PyInfo provider and PyInfo-specific utilities.

provider PyInfo

Encapsulates information provided by the Python rules.

Instead of creating this object directly, use PyInfoBuilder and the PyCommonApi utilities.

PyInfo.<init>(direct_original_sources, direct_pyc_files, direct_pyi_files, has_py2_only_sources, has_py3_only_sources, imports, transitive_implicit_pyc_files, transitive_implicit_pyc_source_files, transitive_original_sources, transitive_pyc_files, transitive_pyi_files, transitive_sources, uses_shared_libraries, venv_symlinks)
PyInfo.direct_original_sources: depset[File]

The .py source files (if any) that are considered directly provided by the target. This field is intended so that static analysis tools can recover the original Python source files, regardless of any build settings (e.g. precompiling), so they can analyze source code. The values are typically the .py files in the srcs attribute (or equivalent).

Added in version 1.1.0.

PyInfo.direct_pyc_files: depset[File]

Precompiled Python files that are considered directly provided by the target and must be included.

These files usually come from, e.g., a library setting precompile=enabled to forcibly enable precompiling for itself. Downstream binaries are expected to always include these files, as the originating target expects them to exist.

PyInfo.direct_pyi_files: depset[File]

Type definition files (usually .pyi files) for the Python modules provided by this target. Usually they describe the source files listed in direct_original_sources. This field is primarily for static analysis tools.

These files are usually build-time only and not included as part of a runnable program.

Note

This may contain implementation-specific file types specific to a particular type checker.

Added in version 1.1.0.

PyInfo.has_py2_only_sources: bool

Whether any of this target’s transitive sources requires a Python 2 runtime.

PyInfo.has_py3_only_sources: bool

Whether any of this target’s transitive sources requires a Python 3 runtime.

PyInfo.imports: depset[str]

A depset of import path strings to be added to the PYTHONPATH of executable Python targets. These are accumulated from the transitive deps. The order of the depset is not guaranteed and may be changed in the future. It is recommended to use default order (the default).

PyInfo.transitive_implicit_pyc_files: depset[File]

Automatically generated pyc files that downstream binaries (or equivalent) can choose to include in their output. If not included, then transitive_implicit_pyc_source_files should be included instead.

Added in version 0.37.0.

PyInfo.transitive_implicit_pyc_source_files: depset[File]

Source .py files for transitive_implicit_pyc_files that downstream binaries (or equivalent) can choose to include in their output. If not included, then transitive_implicit_pyc_files should be included instead.

Added in version 0.37.0.

PyInfo.transitive_original_sources: depset[File]

The transitive set of .py source files (if any) that are considered the original sources for this target and its transitive dependencies. This field is intended so that static analysis tools can recover the original Python source files, regardless of any build settings (e.g. precompiling), so they can analyze source code. The values are typically the .py files in the srcs attribute (or equivalent).

This is superset of direct_original_sources.

Added in version 1.1.0.

PyInfo.transitive_pyc_files: depset[File]

The transitive set of precompiled files that must be included.

These files usually come from, e.g., a library setting precompile=enabled to forcibly enable precompiling for itself. Downstream binaries are expected to always include these files, as the originating target expects them to exist.

PyInfo.transitive_pyi_files: depset[File]

The transitive set of type definition files (usually .pyi files) for the Python modules for this target and its transitive dependencies. this target. Usually they describe the source files listed in transitive_original_sources. This field is primarily for static analysis tools.

These files are usually build-time only and not included as part of a runnable program.

Note

This may contain implementation-specific file types specific to a particular type checker.

Added in version 1.1.0.

PyInfo.transitive_sources: depset[File]

A (postorder-compatible) depset of .py files that are considered required and downstream binaries (or equivalent) must include in their outputs to have a functioning program.

Normally, these are the .py files in the appearing in the target’s srcs and the srcs of the target’s transitive deps, however, precompile settings may cause .py files to be omitted. In particular, pyc-only builds may result in this depset being empty.

Changed in version 0.37.0: The files are considered necessary for downstream binaries to function; previously they were considerd informational and largely unused.

PyInfo.uses_shared_libraries: bool

Whether any of this target’s transitive deps has a shared library file (such as a .so file).

This field is currently unused in Bazel and may go away in the future.

Warning

Experimental API. This API is still under development and may change or be removed without notice.

Added in version 1.5.0.

typedef PyInfoBuilder

Builder for PyInfo.

To create an instance, use py_common.get() and call PyInfoBuilder()

PyInfoBuilder.direct_original_sources: DepsetBuilder[File]
PyInfoBuilder.direct_pyc_files: DepsetBuilder[File]
PyInfoBuilder.direct_pyi_files: DepsetBuilder[File]
PyInfoBuilder.imports: DepsetBuilder[str]
PyInfoBuilder.transitive_implicit_pyc_files: DepsetBuilder[File]
PyInfoBuilder.transitive_implicit_pyc_source_files: DepsetBuilder[File]
PyInfoBuilder.transitive_original_sources: DepsetBuilder[File]
PyInfoBuilder.transitive_pyc_files: DepsetBuilder[File]
PyInfoBuilder.transitive_pyi_files: DepsetBuilder[File]
PyInfoBuilder.transitive_sources: DepsetBuilder[File]
venv_symlinks.build()

Builds into a PyInfo object.

Returns:

PyInfo

PyInfoBuilder.build_builtin_py_info()

Builds into a Bazel-builtin PyInfo object, if available.

Returns:

BuiltinPyInfo | None None is returned if Bazel’s builtin PyInfo object is disabled.

PyInfoBuilder.get_has_py2_only_sources()

Get the has_py2_only_sources value.

Returns:

bool

PyInfoBuilder.get_has_py3_only_sources()

Get the has_py3_only_sources value.

Returns:

bool

PyInfoBuilder.get_uses_shared_libraries()

Get the uses_shared_libraries value.

Returns:

bool

PyInfoBuilder.merge(direct=[], *infos)

Merge other PyInfos into this PyInfo.

Args:

  • direct – (list[PyInfo]) (default [])

    objects to merge in, but also merge their direct fields into this object’s direct fields.

  • infos – (PyInfo)

    objects to merge in, but only merge in their information into this object’s transitive fields.

Returns:

PyInfoBuilder self

PyInfoBuilder.merge_all(transitive, direct=[])

Merge other PyInfos into this PyInfo.

Args:

  • transitive – (list[PyInfo])

    objects to merge in, but only merge in their information into this object’s transitive fields.

  • direct – (list[PyInfo]) (default [])

    objects to merge in, but also merge their direct fields into this object’s direct fields.

Returns:

PyInfoBuilder self

PyInfoBuilder.merge_has_py2_only_sources(value)

Sets has_py2_only_sources based on current and incoming value.

Args:

  • value – (bool)

    Another has_py2_only_sources value. It will be merged into this builder’s state.

Returns:

PyInfoBuilder self

PyInfoBuilder.merge_has_py3_only_sources(value)

Sets has_py3_only_sources based on current and incoming value.

Args:

  • value – (bool)

    Another has_py3_only_sources value. It will be merged into this builder’s state.

Returns:

PyInfoBuilder self

PyInfoBuilder.merge_target(target)

Merge a target’s Python information in this object.

Args:

  • target – (Target)

    targets that provide PyInfo, or other relevant providers, will be merged into this object. If a target doesn’t provide any relevant providers, it is ignored.

Returns:

PyInfoBuilder self.

PyInfoBuilder.merge_targets(targets)

Merge multiple targets into this object.

Args:

  • targets – (list[Target])

    targets that provide PyInfo, or other relevant providers, will be merged into this object. If a target doesn’t provide any relevant providers, it is ignored.

Returns:

PyInfoBuilder self.

PyInfoBuilder.merge_uses_shared_libraries(value)

Sets uses_shared_libraries based on current and incoming value.

Args:

  • value – (bool)

    Another uses_shared_libraries value. It will be merged into this builder’s state.

Returns:

PyInfoBuilder self

PyInfoBuilder.new()

Creates an instance.

Returns:

PyInfoBuilder

PyInfoBuilder.set_has_py2_only_sources(value)

Sets has_py2_only_sources to value.

Args:
Returns:

PyInfoBuilder self

PyInfoBuilder.set_has_py3_only_sources(value)

Sets has_py3_only_sources to value.

Args:
Returns:

PyInfoBuilder self

PyInfoBuilder.set_uses_shared_libraries(value)

Sets uses_shared_libraries to value.

Args:
Returns:

PyInfoBuilder self

provider VenvSymlinkEntry

An entry in PyInfo.venv_symlinks

VenvSymlinkEntry.<init>(files, kind, link_to_file, link_to_path, package, venv_path, version)
VenvSymlinkEntry.files: depset[File]

Files under link_to_path.

This is only used when multiple targets have overlapping venv_path paths. e.g. if one adds files to venv_path=a/ and another adds files to venv_path=a/b/.

VenvSymlinkEntry.kind: str

One of the VenvSymlinkKind values. It represents which directory within the venv to create the path under.

A file that venv_path should point to. The file to link to should also be in files.

Added in version 1.7.0.

A runfiles-root relative path that venv_path will symlink to (if link_to_file is None). If None, it means to not create it in the venv.

VenvSymlinkEntry.package: str | None

Represents the PyPI package name that the code originates from. It is normalized according to the PEP440 with all - replaced with _, i.e. the same as the package name in the hub repository that it would come from.

VenvSymlinkEntry.venv_path: str

A path relative to the kind directory within the venv.

VenvSymlinkEntry.version: str | None

Represents the PyPI package version that the code originates from. It is normalized according to the PEP440 standard.

typedef VenvSymlinkKind

An enum of types of venv directories.

VenvSymlinkKind.BIN: object

Indicates to create paths under the directory that has binaries within the venv.

VenvSymlinkKind.LIB: object

Indicates to create paths under the venv’s site-packages directory.

VenvSymlinkKind.INCLUDE: object

Indicates to create paths under the venv’s include directory.