Python Rules

Rules

py_binary 

py_binary(name, deps, srcs, data, args, compatible_with, default_python_version, deprecation, distribs, features, imports, legacy_create_init, licenses, main, output_licenses, python_version, restricted_to, srcs_version, stamp, tags, testonly, toolchains, visibility)

A py_binary is an executable Python program consisting of a collection of .py source files (possibly belonging to other py_library rules), a *.runfiles directory tree containing all the code and data needed by the program at run-time, and a stub script that starts up the program with the correct initial environment and data.

Examples

py_binary(
    name = "foo",
    srcs = ["foo.py"],
    data = [":transform"],  # a cc_binary which we invoke at run time
    deps = [
        "//pyglib",
        ":foolib",  # a py_library
    ],
)

If you want to run a py_binary from within another binary or test (for example, running a python binary to set up some mock resource from within a java_test) then the correct approach is to make the other binary or test depend on the py_binary in its data section. The other binary can then locate the py_binary relative to the source directory. 

py_binary(
    name = "test_main",
    srcs = ["test_main.py"],
    deps = [":testlib"],
)

java_library(
    name = "testing",
    srcs = glob(["*.java"]),
    data = [":test_main"]
)

Arguments

Attributes
name

Name; required

A unique name for this target.


If main is unspecified, this should be the same as the name of the source file that is the main entry point of the application, minus the extension. For example, if your entry point is called main.py, then your name should be main.
deps

List of labels; optional

The list of other libraries to be linked in to the binary target. See general comments about deps at Attributes common to all build rules. These are generally py_library rules.
srcs

List of labels; required

The list of source (.py) files that are processed to create the target. This includes all your checked-in code and any generated source files. Library targets belong in deps instead, while other binary files needed at runtime belong in data.
default_python_version

String; optional; nonconfigurable; default is "_INTERNAL_SENTINEL"

A deprecated alias for python_version; use that instead. This attribute is disabled under --incompatible_remove_old_python_version_api. For migration purposes, if python_version is given then the value of default_python_version is ignored.
imports

List of strings; optional

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.

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.

legacy_create_init

Boolean; optional; default is True

Whether to implicitly create empty __init__.py files in the runfiles tree. These are created in every directory containing Python source code or shared libraries, and every parent directory of those directories, excluding the repo root directory. The default is true for backward compatibility. If false, the user is responsible for creating (possibly empty) __init__.py files and adding them to the srcs of Python targets as required.
main

Label; optional

The name of the source file that is the main entry point of the application. This file must also be listed in srcs. If left unspecified, name is used instead (see above). If name does not match any filename in srcs, main must be specified.
python_version

String; optional; nonconfigurable; default is "_INTERNAL_SENTINEL"

Whether to build this target (and its transitive deps) for Python 2 or Python 3. Valid values are "PY2" (the default) and "PY3".

Under the old semantics (--incompatible_allow_python_version_transitions=false), the Python version generally cannot be changed once set. This means that the --python_version flag overrides this attribute, and other Python binaries in the data deps of this target are forced to use the same version as this target.

Under the new semantics (--incompatible_allow_python_version_transitions=true), the Python version is always set (possibly by default) to whatever version is specified by this attribute, regardless of the version specified on the command line or by other targets that depend on this one.

If you want to select() on the current Python version, you can inspect the value of @bazel_tools//tools/python:python_version. See here for more information.

Bug warning: This attribute sets the version for which Bazel builds your target, but due to #4815, the resulting stub script may still invoke the wrong interpreter version at runtime. See this workaround, which involves defining a py_runtime target that points to either Python version as needed, and activating this py_runtime by setting --python_top.

srcs_version

String; optional; default is "PY2AND3"

This attribute declares the target's srcs to be compatible with either Python 2, Python 3, or both. To actually set the Python runtime version, use the python_version attribute of an executable Python rule (py_binary or py_test).

Allowed values are: "PY2AND3", "PY2", and "PY3". The values "PY2ONLY" and "PY3ONLY" are also allowed for historic reasons, but they are essentially the same as "PY2" and "PY3" and should be avoided.

Under the old semantics (--incompatible_allow_python_version_transitions=false), it is an error to build any Python target for a version disallowed by its srcs_version attribute. Under the new semantics (--incompatible_allow_python_version_transitions=true), this check is deferred to the executable rule: You can build a srcs_version = "PY3" py_library target for Python 2, but you cannot actually depend on it via deps from a Python 3 py_binary.

To get diagnostic information about which dependencies introduce version requirements, you can run the find_requirements aspect on your target: 

          bazel build <your target> \
              --aspects=@bazel_tools//tools/python:srcs_version.bzl%find_requirements \
              --output_groups=pyversioninfo
This will build a file with the suffix -pyversioninfo.txt giving information about why your target requires one Python version or another. Note that it works even if the given target failed to build due to a version conflict.
stamp

Integer; optional; default is -1

Enable link stamping. Whether to encode build information into the binary. Possible values:
  • stamp = 1: Stamp the build information into the binary. Stamped binaries are only rebuilt when their dependencies change. Use this if there are tests that depend on the build information.
  • stamp = 0: Always replace build information by constant values. This gives good build result caching.
  • stamp = -1: Embedding of build information is controlled by the --[no]stamp Bazel flag.
toolchains

List of labels; optional

The set of toolchains that supply "Make variables" that this target can use in some of its attributes. Some rules have toolchains whose Make variables they can use by default.

py_library 

py_library(name, deps, srcs, data, compatible_with, deprecation, distribs, features, imports, licenses, restricted_to, srcs_version, tags, testonly, visibility)

Arguments

Attributes
name

Name; required

A unique name for this target.
deps

List of labels; optional

The list of other libraries to be linked in to the binary target. See general comments about deps at Attributes common to all build rules. These are generally py_library rules.
srcs

List of labels; optional

The list of source (.py) files that are processed to create the target. This includes all your checked-in code and any generated source files.
imports

List of strings; optional

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.

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.

srcs_version

String; optional; default is "PY2AND3"

This attribute declares the target's srcs to be compatible with either Python 2, Python 3, or both. To actually set the Python runtime version, use the python_version attribute of an executable Python rule (py_binary or py_test).

Allowed values are: "PY2AND3", "PY2", and "PY3". The values "PY2ONLY" and "PY3ONLY" are also allowed for historic reasons, but they are essentially the same as "PY2" and "PY3" and should be avoided.

Under the old semantics (--incompatible_allow_python_version_transitions=false), it is an error to build any Python target for a version disallowed by its srcs_version attribute. Under the new semantics (--incompatible_allow_python_version_transitions=true), this check is deferred to the executable rule: You can build a srcs_version = "PY3" py_library target for Python 2, but you cannot actually depend on it via deps from a Python 3 py_binary.

To get diagnostic information about which dependencies introduce version requirements, you can run the find_requirements aspect on your target: 

          bazel build <your target> \
              --aspects=@bazel_tools//tools/python:srcs_version.bzl%find_requirements \
              --output_groups=pyversioninfo
This will build a file with the suffix -pyversioninfo.txt giving information about why your target requires one Python version or another. Note that it works even if the given target failed to build due to a version conflict.

py_test 

py_test(name, deps, srcs, data, args, compatible_with, default_python_version, deprecation, distribs, exec_compatible_with, features, flaky, imports, legacy_create_init, licenses, local, main, python_version, restricted_to, shard_count, size, srcs_version, stamp, tags, testonly, timeout, toolchains, visibility)

A py_test() rule compiles a test. A test is a binary wrapper around some test code.

Examples

py_test(
    name = "runtest_test",
    srcs = ["runtest_test.py"],
    deps = [
        "//path/to/a/py/library",
    ],
)

It's also possible to specify a main module:

py_test(
    name = "runtest_test",
    srcs = [
        "runtest_main.py",
        "runtest_lib.py",
    ],
    main = "runtest_main.py",
)

Arguments

Attributes
name

Name; required

A unique name for this target.
deps

List of labels; optional

The list of other libraries to be linked in to the binary target. See general comments about deps at Attributes common to all build rules. These are generally py_library rules.
srcs

List of labels; required

The list of source (.py) files that are processed to create the target. This includes all your checked-in code and any generated source files. Library targets belong in deps instead, while other binary files needed at runtime belong in data.
default_python_version

String; optional; nonconfigurable; default is "_INTERNAL_SENTINEL"

A deprecated alias for python_version; use that instead. This attribute is disabled under --incompatible_remove_old_python_version_api. For migration purposes, if python_version is given then the value of default_python_version is ignored.
imports

List of strings; optional

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.

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.

legacy_create_init

Boolean; optional; default is True

Whether to implicitly create empty __init__.py files in the runfiles tree. These are created in every directory containing Python source code or shared libraries, and every parent directory of those directories, excluding the repo root directory. The default is true for backward compatibility. If false, the user is responsible for creating (possibly empty) __init__.py files and adding them to the srcs of Python targets as required.
main

Label; optional

The name of the source file that is the main entry point of the application. This file must also be listed in srcs. If left unspecified, name is used instead (see above). If name does not match any filename in srcs, main must be specified.
python_version

String; optional; nonconfigurable; default is "_INTERNAL_SENTINEL"

Whether to build this target (and its transitive deps) for Python 2 or Python 3. Valid values are "PY2" (the default) and "PY3".

Under the old semantics (--incompatible_allow_python_version_transitions=false), the Python version generally cannot be changed once set. This means that the --python_version flag overrides this attribute, and other Python binaries in the data deps of this target are forced to use the same version as this target.

Under the new semantics (--incompatible_allow_python_version_transitions=true), the Python version is always set (possibly by default) to whatever version is specified by this attribute, regardless of the version specified on the command line or by other targets that depend on this one.

If you want to select() on the current Python version, you can inspect the value of @bazel_tools//tools/python:python_version. See here for more information.

Bug warning: This attribute sets the version for which Bazel builds your target, but due to #4815, the resulting stub script may still invoke the wrong interpreter version at runtime. See this workaround, which involves defining a py_runtime target that points to either Python version as needed, and activating this py_runtime by setting --python_top.

srcs_version

String; optional; default is "PY2AND3"

This attribute declares the target's srcs to be compatible with either Python 2, Python 3, or both. To actually set the Python runtime version, use the python_version attribute of an executable Python rule (py_binary or py_test).

Allowed values are: "PY2AND3", "PY2", and "PY3". The values "PY2ONLY" and "PY3ONLY" are also allowed for historic reasons, but they are essentially the same as "PY2" and "PY3" and should be avoided.

Under the old semantics (--incompatible_allow_python_version_transitions=false), it is an error to build any Python target for a version disallowed by its srcs_version attribute. Under the new semantics (--incompatible_allow_python_version_transitions=true), this check is deferred to the executable rule: You can build a srcs_version = "PY3" py_library target for Python 2, but you cannot actually depend on it via deps from a Python 3 py_binary.

To get diagnostic information about which dependencies introduce version requirements, you can run the find_requirements aspect on your target: 

          bazel build <your target> \
              --aspects=@bazel_tools//tools/python:srcs_version.bzl%find_requirements \
              --output_groups=pyversioninfo
This will build a file with the suffix -pyversioninfo.txt giving information about why your target requires one Python version or another. Note that it works even if the given target failed to build due to a version conflict.
stamp

Integer; optional; default is 0

See the section on py_binary() arguments, except that the stamp argument is set to 0 by default for tests.
toolchains

List of labels; optional

The set of toolchains that supply "Make variables" that this target can use in some of its attributes. Some rules have toolchains whose Make variables they can use by default.

py_runtime 

py_runtime(name, compatible_with, deprecation, distribs, features, files, interpreter, interpreter_path, licenses, python_version, restricted_to, tags, testonly, visibility)

Represents a Python runtime used to execute Python code.

A py_runtime target can represent either a platform runtime or an in-build runtime. A platform runtime accesses a system-installed interpreter at a known path, whereas an in-build runtime points to an executable target that acts as the interpreter. In both cases, an "interpreter" means any executable binary or wrapper script that is capable of running a Python script passed on the command line, following the same conventions as the standard CPython interpreter.

A platform runtime is by its nature non-hermetic. It imposes a requirement on the target platform to have an interpreter located at a specific path. An in-build runtime may or may not be hermetic, depending on whether it points to a checked-in interpreter or a wrapper script that accesses the system interpreter.

Example:

py_runtime(
    name = "python-2.7.12",
    files = glob(["python-2.7.12/**"]),
    interpreter = "python-2.7.12/bin/python",
)

py_runtime(
    name = "python-3.6.0",
    interpreter_path = "/opt/pyenv/versions/3.6.0/bin/python",
)

Arguments

Attributes
name

Name; required

A unique name for this target.
files

List of labels; optional

For an in-build runtime, this is the set of files comprising this runtime. These files will be added to the runfiles of Python binaries that use this runtime. For a platform runtime this attribute must not be set.
interpreter

Label; optional

For an in-build runtime, this is the target to invoke as the interpreter. For a platform runtime this attribute must not be set.
interpreter_path

String; optional

For a platform runtime, this is the absolute path of a Python interpreter on the target platform. For an in-build runtime this attribute must not be set.
python_version

String; optional; default is "_INTERNAL_SENTINEL"

Whether this runtime is for Python major version 2 or 3. Valid values are "PY2" and "PY3".

The default value is controlled by the --incompatible_py3_is_default flag. However, in the future this attribute will be mandatory and have no default value.