Python Rules

Rules

py_binary
py_library
py_test
py_runtime

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.