Python 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 can be py_binary rules, py_library rules.
srcs

List of labels; required

The list of source files that are processed to create the target. This includes all your checked-in code and any generated source files. The line between srcs and deps is loose. The .py files probably belong in srcs and library targets probably belong in deps, but don't worry about it too much.
data

List of labels; optional

The list of files needed by this binary at runtime. See general comments about data at Attributes common to all build rules. Also see the data argument of the py_library rule for details.
default_python_version

String; optional; nonconfigurable; default is "PY2"

A string specifying the default Python major version to use when building this binary and all of its deps. Valid values are "PY2" (default) or "PY3". Python 3 support is experimental.

If both this attribute and python_version are supplied, default_python_version will be 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. Default is true for backward compatibility. If false, the user is responsible for creating __init__.py files (empty or not) and adding them to `srcs` or `deps` 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 "PY2"

An experimental replacement for default_python_version. Only available when --experimental_better_python_version_mixing is enabled. If both this and default_python_version are supplied, the latter will be ignored.
srcs_version

String; optional; default is "PY2AND3"

The value set here is for documentation purpose, and it will NOT determine which version of python interpreter to use. Starting with 0.5.3 this attribute has been deprecated and no longer has effect. A string specifying the Python major version(s) that the .py source files listed in the srcs of this rule are compatible with. Please reference to py_runtime rules for determining the python version. Valid values are:
"PY2ONLY" - Python 2 code that is not suitable for 2to3 conversion.
"PY2" - Python 2 code that is expected to work when run through 2to3.
"PY2AND3" - Code that is compatible with both Python 2 and 3 without 2to3 conversion.
"PY3ONLY" - Python 3 code that will not run on Python 2.
"PY3" - A synonym for PY3ONLY.

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 library target. See general comments about deps at Attributes common to all build rules. In practice, these arguments are treated like those in srcs; you may move items between these lists willy-nilly. It's probably more readable to keep your .py files in your srcs.
srcs

List of labels; optional

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

List of labels; optional

The list of files needed by this library at runtime. See general comments about data at Attributes common to all build rules.
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"

The value set here is for documentation purpose, and it will NOT determine which version of python interpreter to use. Starting with 0.5.3 this attribute has been deprecated and no longer has effect. A string specifying the Python major version(s) that the .py source files listed in the srcs of this rule are compatible with. Please reference to py_runtime rules for determining the python version. Valid values are:
"PY2ONLY" - Python 2 code that is not suitable for 2to3 conversion.
"PY2" - Python 2 code that is expected to work when run through 2to3.
"PY2AND3" - Code that is compatible with both Python 2 and 3 without 2to3 conversion.
"PY3ONLY" - Python 3 code that will not run on Python 2.
"PY3" - A synonym for PY3ONLY.

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 can be py_binary rules, py_library rules.
srcs

List of labels; required

The list of source files that are processed to create the target. This includes all your checked-in code and any generated source files. The line between srcs and deps is loose. The .py files probably belong in srcs and library targets probably belong in deps, but don't worry about it too much.
data

List of labels; optional

The list of files needed by this binary at runtime. See general comments about data at Attributes common to all build rules. Also see the data argument of the py_library rule for details.
default_python_version

String; optional; nonconfigurable; default is "PY2"

A string specifying the default Python major version to use when building this binary and all of its deps. Valid values are "PY2" (default) or "PY3". Python 3 support is experimental.

If both this attribute and python_version are supplied, default_python_version will be 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. Default is true for backward compatibility. If false, the user is responsible for creating __init__.py files (empty or not) and adding them to `srcs` or `deps` 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 "PY2"

An experimental replacement for default_python_version. Only available when --experimental_better_python_version_mixing is enabled. If both this and default_python_version are supplied, the latter will be ignored.
srcs_version

String; optional; default is "PY2AND3"

The value set here is for documentation purpose, and it will NOT determine which version of python interpreter to use. Starting with 0.5.3 this attribute has been deprecated and no longer has effect. A string specifying the Python major version(s) that the .py source files listed in the srcs of this rule are compatible with. Please reference to py_runtime rules for determining the python version. Valid values are:
"PY2ONLY" - Python 2 code that is not suitable for 2to3 conversion.
"PY2" - Python 2 code that is expected to work when run through 2to3.
"PY2AND3" - Code that is compatible with both Python 2 and 3 without 2to3 conversion.
"PY3ONLY" - Python 3 code that will not run on Python 2.
"PY3" - A synonym for PY3ONLY.

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, restricted_to, tags, testonly, visibility)

Specifies the configuration for a Python runtime. This rule can either describe a Python runtime in the source tree or one at a well-known absolute path.

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",
    files = [],
    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; required

The set of files comprising this Python runtime.
interpreter

Label; optional

The Python interpreter used in this runtime. Binary rules will be executed using this binary.
interpreter_path

String; optional

The absolute path of a Python interpreter. This attribute and interpreter attribute cannot be set at the same time.