//python/private:py_library_rule.bzl

Implementation of py_library rule.

rule py_library(name, data=[], deps=[], distribs=[], experimental_venvs_site_packages=None, imports=[], licenses=[], namespace_package_files=[], precompile='inherit', precompile_invalidation_mode='auto', precompile_optimize_level=0, precompile_source_retention='inherit', pyi_deps=[], pyi_srcs=[], srcs=[], srcs_version='')

A library of Python code that can be depended upon.

Default outputs:

  • The input Python sources

  • The precompiled artifacts from the sources.

NOTE: Precompilation affects which of the default outputs are included in the resulting runfiles. See the precompile-related attributes and flags for more information.

Changed in version 0.37.0: Source files are no longer added to the runfiles directly.

Provides:

PyCcLinkParamsInfo | PyInfo

Attributes:

  • name – (Name)

    A unique name for this target.

    mandatory

  • data – (list[label]) (default [])

    The list of files need by this library at runtime. See comments about the data attribute typically defined by rules.

    There is no py_embed_data like there is cc_embed_data and go_embed_data. This is because Python has a concept of runtime resources.

    optional

  • deps – (list[label]) (default [])

    List of additional libraries to be linked in to the target. See comments about the deps attribute typically defined by rules. These are typically py_library rules.

    Targets that only provide data files used at runtime belong in the data attribute.

    Note

    The order of this list can matter because it affects the order that information from dependencies is merged in, which can be relevant depending on the ordering mode of depsets that are merged.

    See PyInfo for more information about the ordering of its depsets and how its fields are merged.

    optional

    Required providers: PyInfo | CcInfo

  • distribs – (list[str]) (default [])

    optional

  • experimental_venvs_site_packages – (label) (default None)

    INTERNAL ATTRIBUTE. SHOULD ONLY BE SET BY rules_python-INTERNAL CODE.

    Warning

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

    A flag that decides whether the library should treat its sources as a site-packages layout.

    When the flag is yes, then the srcs files are treated as a site-packages layout that is relative to the imports attribute. The imports attribute can have only a single element. It is a repo-relative runfiles path.

    For example, in the my/pkg/BUILD.bazel file, given srcs=["site-packages/foo/bar.py"], specifying imports=["my/pkg/site-packages"] means foo/bar.py is the file path under the binary’s venv site-packages directory that should be made available (i.e. import foo.bar will work).

    __init__.py files are treated specially to provide basic support for implicit namespace packages. However, the content of the files cannot be taken into account, merely their presence or absence. Stated another way: pkgutil-style namespace packages won’t be understood as namespace packages; they’ll be seen as regular packages. This will likely lead to conflicts with other targets that contribute to the namespace.

    See also

    This attributes populates PyInfo.venv_symlinks.

    Added in version 1.4.0.

    Changed in version 1.5.0: The topological order has been removed and if 2 different versions of the same PyPI package are observed, the behaviour has no guarantees except that it is deterministic and that only one package version will be included.

    optional

  • imports – (list[str]) (default [])

    List of import directories to be added to the PYTHONPATH.

    Subject to “Make variable” substitution. These import directories will be added for this rule and all rules that depend on it (note: not the rules this rule depends on. Each directory will be added to PYTHONPATH by py_binary rules that depend on this rule. The strings are repo-runfiles-root relative,

    Absolute paths (paths that start with /) and paths that references a path above the execution root are not allowed and will result in an error.

    optional

  • licenses – (list[str]) (default [])

    optional

  • namespace_package_files – (list[label]) (default [])

    Files whose directories are namespace packages.

    When --venv_site_packages=yes is set, this helps inform which directories should be treated as namespace packages and expect files from other targets to be contributed. This allows optimizing the generation of symlinks to be cheaper at analysis time.

    Added in version 1.8.0.

    optional

  • precompile – (str) (default “inherit”)

    Whether py source files for this target should be precompiled.

    Values:

    • inherit: Allow the downstream binary decide if precompiled files are used.

    • enabled: Compile Python source files at build time.

    • disabled: Don’t compile Python source files at build time.

    See also

    • The --precompile flag, which can override this attribute in some cases and will affect all targets when building.

    • The pyc_collection attribute for transitively enabling precompiling on a per-target basis.

    • The Precompiling docs for a guide about using precompiling.

    optional

  • precompile_invalidation_mode – (str) (default “auto”)

    How precompiled files should be verified to be up-to-date with their associated source files. Possible values are:

    • auto: The effective value will be automatically determined by other build settings.

    • checked_hash: Use the pyc file if the hash of the source file matches the hash recorded in the pyc file. This is most useful when working with code that you may modify.

    • unchecked_hash: Always use the pyc file; don’t check the pyc’s hash against the source file. This is most useful when the code won’t be modified.

    For more information on pyc invalidation modes, see https://docs.python.org/3/library/py_compile.html#py_compile.PycInvalidationMode

    optional

  • precompile_optimize_level – (int) (default 0)

    The optimization level for precompiled files.

    For more information about optimization levels, see the compile() function’s optimize arg docs at https://docs.python.org/3/library/functions.html#compile

    NOTE: The value -1 means “current interpreter”, which will be the interpreter used at build time when pycs are generated, not the interpreter used at runtime when the code actually runs.

    optional

  • precompile_source_retention – (str) (default “inherit”)

    Determines, when a source file is compiled, if the source file is kept in the resulting output or not. Valid values are:

    • inherit: Inherit the value from the --precompile_source_retention flag.

    • keep_source: Include the original Python source.

    • omit_source: Don’t include the original py source.

    optional

  • pyi_deps – (list[label]) (default [])

    Dependencies providing type definitions the library needs.

    These are dependencies that satisfy imports guarded by typing.TYPE_CHECKING. These are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however).

    Added in version 1.1.0.

    optional

    Required providers: PyInfo | CcInfo

  • pyi_srcs – (list[label]) (default [])

    Type definition files for the library.

    These are typically .pyi files, but other file types for type-checker specific formats are allowed. These files are build-time only dependencies and not included as part of a runnable program (packaging rules may include them, however).

    Added in version 1.1.0.

    optional

  • srcs – (list[label]) (default [])

    The list of Python source files that are processed to create the target. This includes all your checked-in code and may include generated source files. The .py files belong in srcs and library targets belong in deps. Other binary files that may be needed at run time belong in data.

    optional

  • srcs_version – (str) (default “”)

    Defunct, unused, does nothing.

    optional