//python/private:py_library_rule.bzl

Implementation of py_library rule.

rulepy_library(name,data=[],deps=[],distribs=[],experimental_venvs_site_packages=None,imports=[],licenses=[],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 theresulting runfiles. See the precompile-related attributes and flags formore 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 aboutthedata attribute typically defined by rules.

    There is nopy_embed_data like there iscc_embed_data andgo_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 aboutthedeps attribute typically defined byrules.These are typicallypy_library rules.

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

    Note

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

    SeePyInfo for more information about the ordering of its depsets andhow its fields are merged.

    optional

    Required providers:PyInfo|CcInfo

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

    optional

  • experimental_venvs_site_packages –(label)(defaultNone)

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

    Warning

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

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

    When the flag isyes, then thesrcs files are treated as a site-packageslayout that is relative to theimports attribute. Theimports attributecan have only a single element. It is a repo-relative runfiles path.

    For example, in themy/pkg/BUILD.bazel file, givensrcs=["site-packages/foo/bar.py"], specifyingimports=["my/pkg/site-packages"] meansfoo/bar.py is the file pathunder the binary’s venv site-packages directory that should be made available (i.e.importfoo.bar will work).

    __init__.py files are treated specially to provide basic support forimplicitnamespace packages.However, thecontent of the files cannot be taken into account, merely theirpresence or absence. Stated another way:pkgutil-style namespace packageswon’t be understood as namespace packages; they’ll be seen as regular packages. This willlikely lead to conflicts with other targets that contribute to the namespace.

    See also

    This attributes populatesPyInfo.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 PyPIpackage are observed, the behaviour has no guarantees except that it is deterministicand 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 addedfor this rule and all rules that depend on it (note: not the rules this ruledepends on. Each directory will be added toPYTHONPATH bypy_binary rulesthat depend on this rule. The strings are repo-runfiles-root relative,

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

    optional

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

    optional

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

    Whether py source filesfor 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 casesand will affect all targets when building.

    • Thepyc_collection attribute for transitively enabling precompiling ona per-target basis.

    • ThePrecompiling 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 associatedsource files. Possible values are:

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

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

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

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

    optional

  • precompile_optimize_level –(int)(default0)

    The optimization level for precompiled files.

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

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

    optional

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

    Determines, when a source file is compiled, if the source file is keptin 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 bytyping.TYPE_CHECKING.These are build-time only dependencies and not included as part of a runnableprogram (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 specificformats are allowed. These files are build-time only dependencies and not includedas 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. Thisincludes all your checked-in code and may include generated source files. The.py files belong insrcs and library targets belong indeps. Other binaryfiles that may be needed at run time belong indata.

    optional

  • srcs_version –(str)(default“”)

    Defunct, unused, does nothing.

    optional