README.md

Python pex rules for Bazel

Overview

Rules

• pex_binary
• pex_library
• pex_test

Macros

• pex_pytest
• pex_repositories

---

Overview

Setup

Add something like this to your WORKSPACE file:

git_repository(
    name = "io_bazel_rules_pex",
    remote = "https://github.com/benley/bazel_rules_pex.git",
    tag = "0.3.0",
)
load("@io_bazel_rules_pex//pex:pex_rules.bzl", "pex_repositories")
pex_repositories()

In a BUILD file where you want to use these rules, or in your tools/build_rules/prelude_bazel file if you want them present repo-wide, add:

load(
    "@io_bazel_rules_pex//pex:pex_rules.bzl",
    "pex_binary",
    "pex_library",
    "pex_test",
    "pex_pytest",
)

Lastly, make sure that tools/build_rules/BUILD exists, even if it is empty, so that Bazel can find your prelude_bazel file.

pex_pytest

pex_pytest(name, srcs, deps, eggs, data, args, flaky, local, size, timeout, tags)

A variant of pex_test that uses py.test to run one or more sets of tests.

This produces two things:

1. A pex_binary (<name>_runner) containing all your code and its dependencies, plus py.test, and the entrypoint set to the py.test runner.
2. A small shell script to launch the <name>_runner executable with each of the srcs enumerated as commandline arguments. This is the actual test entrypoint for bazel.

Almost all of the attributes that can be used with pex_test work identically here, including those not specifically mentioned in this docstring. Exceptions are main and entrypoint, which cannot be used with this macro.

Attributes

name	Name; Required A unique name for this rule.
srcs	Unknown; Required List of files containing tests that should be run.
deps	List of strings; Optional </td> </tr> <tr id="pex_pytest.eggs"> <td><code>eggs</code></td> <td> <p><code>List of strings; Optional</code></p> </td> </tr> <tr id="pex_pytest.data"> <td><code>data</code></td> <td> <p><code>List of strings; Optional</code></p> </td> </tr> <tr id="pex_pytest.args"> <td><code>args</code></td> <td> <p><code>List of strings; Optional</code></p> </td> </tr> <tr id="pex_pytest.flaky"> <td><code>flaky</code></td> <td> <p><code>Unknown; Optional</code></p> </td> </tr> <tr id="pex_pytest.local"> <td><code>local</code></td> <td> <p><code>Unknown; Optional</code></p> </td> </tr> <tr id="pex_pytest.size"> <td><code>size</code></td> <td> <p><code>Unknown; Optional</code></p> </td> </tr> <tr id="pex_pytest.timeout"> <td><code>timeout</code></td> <td> <p><code>Unknown; Optional</code></p> </td> </tr> <tr id="pex_pytest.tags"> <td><code>tags</code></td> <td> <p><code>List of strings; Optional</code></p> </td> </tr>

## pex_repositories

pex_repositories()

Rules to be invoked from WORKSPACE for remote dependencies.

pex_binary

pex_binary(name, deps, data, srcs, disable_cache, eggs, entrypoint, interpreter, main, no_index, pex_use_wheels, pex_verbosity, repos, req_files, reqs, zip_safe)

Build a deployable pex executable.

Attributes

name	Name; Required A unique name for this rule.
deps	List of labels; Optional; Default is [] Python module dependencies. pex_library and py_library rules should work here.
data	List of labels; Optional; Default is [] Files to include as resources in the final pex binary. Putting other rules here will cause the outputs of those rules to be embedded in this one. Files will be included as-is. Paths in the archive will be relative to the workspace root.
srcs	List of labels; Optional; Default is [] </td> </tr> <tr id="pex_binary.disable_cache"> <td><code>disable_cache</code></td> <td> <p><code>Boolean; Optional; Default is False</code></p> <p>Disable caching in the pex tool entirely. Default: False</p> </td> </tr> <tr id="pex_binary.eggs"> <td><code>eggs</code></td> <td> <p><code>List of <a href="https://bazel.build/docs/build-ref.html#labels">labels</a>; Optional; Default is []</code></p> <p><code>.egg</code> and <code>.whl</code> files to include as python packages.</p> </td> </tr> <tr id="pex_binary.entrypoint"> <td><code>entrypoint</code></td> <td> <p><code>String; Optional; Default is ''</code></p> <p>Name of a python module to use as the entrypoint.</p> e.g. your.project.main If unspecified, the main attribute will be used. It is an error to specify both main and entrypoint.
interpreter	String; Optional; Default is '' Path to the python interpreter the pex should to use in its shebang line.
main	Label; Optional File to use as the entrypoint. If unspecified, the first file from the srcs attribute will be used.
no_index	Boolean; Optional; Default is False If True, don't use pypi to resolve dependencies for reqs and req_files; Default: False
pex_use_wheels	Boolean; Optional; Default is True </td> </tr> <tr id="pex_binary.pex_verbosity"> <td><code>pex_verbosity</code></td> <td> <p><code>Integer; Optional; Default is 0</code></p> </td> </tr> <tr id="pex_binary.repos"> <td><code>repos</code></td> <td> <p><code>List of <a href="https://bazel.build/docs/build-ref.html#labels">labels</a>; Optional; Default is []</code></p> <p>Additional repository labels (filegroups of wheel/egg files) to look for requirements.</p> </td> </tr> <tr id="pex_binary.req_files"> <td><code>req_files</code></td> <td> <p><code>List of <a href="https://bazel.build/docs/build-ref.html#labels">labels</a>; Optional; Default is []</code></p> <p>Add requirements from the given requirements files. Must be provided as labels.</p> This feature will reduce build determinism! It tells pex to resolve all the transitive python dependencies and fetch them from pypi. It is recommended that you use eggs or specify no_index instead where possible.
reqs	List of strings; Optional; Default is [] External requirements to retrieve from pypi, in requirements.txt format. This feature will reduce build determinism! It tells pex to resolve all the transitive python dependencies and fetch them from pypi. It is recommended that you use eggs instead where possible.
zip_safe	Boolean; Optional; Default is True </td> </tr>

## pex_library

pex_library(name, deps, data, srcs, disable_cache, eggs, no_index, repos, req_files, reqs)

Attributes

name	Name; Required A unique name for this rule.
deps	List of labels; Optional; Default is [] Python module dependencies. pex_library and py_library rules should work here.
data	List of labels; Optional; Default is [] Files to include as resources in the final pex binary. Putting other rules here will cause the outputs of those rules to be embedded in this one. Files will be included as-is. Paths in the archive will be relative to the workspace root.
srcs	List of labels; Optional; Default is [] </td> </tr> <tr id="pex_library.disable_cache"> <td><code>disable_cache</code></td> <td> <p><code>Boolean; Optional; Default is False</code></p> <p>Disable caching in the pex tool entirely. Default: False</p> </td> </tr> <tr id="pex_library.eggs"> <td><code>eggs</code></td> <td> <p><code>List of <a href="https://bazel.build/docs/build-ref.html#labels">labels</a>; Optional; Default is []</code></p> <p><code>.egg</code> and <code>.whl</code> files to include as python packages.</p> </td> </tr> <tr id="pex_library.no_index"> <td><code>no_index</code></td> <td> <p><code>Boolean; Optional; Default is False</code></p> <p>If True, don't use pypi to resolve dependencies for <code>reqs</code> and <code>req_files</code>; Default: False</p> </td> </tr> <tr id="pex_library.repos"> <td><code>repos</code></td> <td> <p><code>List of <a href="https://bazel.build/docs/build-ref.html#labels">labels</a>; Optional; Default is []</code></p> <p>Additional repository labels (filegroups of wheel/egg files) to look for requirements.</p> </td> </tr> <tr id="pex_library.req_files"> <td><code>req_files</code></td> <td> <p><code>List of <a href="https://bazel.build/docs/build-ref.html#labels">labels</a>; Optional; Default is []</code></p> <p>Add requirements from the given requirements files. Must be provided as labels.</p> This feature will reduce build determinism! It tells pex to resolve all the transitive python dependencies and fetch them from pypi. It is recommended that you use eggs or specify no_index instead where possible.
reqs	List of strings; Optional; Default is [] External requirements to retrieve from pypi, in requirements.txt format. This feature will reduce build determinism! It tells pex to resolve all the transitive python dependencies and fetch them from pypi. It is recommended that you use eggs instead where possible.

## pex_test

pex_test(name, deps, data, srcs, disable_cache, eggs, entrypoint, interpreter, main, no_index, pex_use_wheels, pex_verbosity, repos, req_files, reqs, zip_safe)

Attributes

name	Name; Required A unique name for this rule.
deps	List of labels; Optional; Default is [] Python module dependencies. pex_library and py_library rules should work here.
data	List of labels; Optional; Default is [] Files to include as resources in the final pex binary. Putting other rules here will cause the outputs of those rules to be embedded in this one. Files will be included as-is. Paths in the archive will be relative to the workspace root.
srcs	List of labels; Optional; Default is [] </td> </tr> <tr id="pex_test.disable_cache"> <td><code>disable_cache</code></td> <td> <p><code>Boolean; Optional; Default is False</code></p> <p>Disable caching in the pex tool entirely. Default: False</p> </td> </tr> <tr id="pex_test.eggs"> <td><code>eggs</code></td> <td> <p><code>List of <a href="https://bazel.build/docs/build-ref.html#labels">labels</a>; Optional; Default is []</code></p> <p><code>.egg</code> and <code>.whl</code> files to include as python packages.</p> </td> </tr> <tr id="pex_test.entrypoint"> <td><code>entrypoint</code></td> <td> <p><code>String; Optional; Default is ''</code></p> <p>Name of a python module to use as the entrypoint.</p> e.g. your.project.main If unspecified, the main attribute will be used. It is an error to specify both main and entrypoint.
interpreter	String; Optional; Default is '' Path to the python interpreter the pex should to use in its shebang line.
main	Label; Optional File to use as the entrypoint. If unspecified, the first file from the srcs attribute will be used.
no_index	Boolean; Optional; Default is False If True, don't use pypi to resolve dependencies for reqs and req_files; Default: False
pex_use_wheels	Boolean; Optional; Default is True </td> </tr> <tr id="pex_test.pex_verbosity"> <td><code>pex_verbosity</code></td> <td> <p><code>Integer; Optional; Default is 0</code></p> </td> </tr> <tr id="pex_test.repos"> <td><code>repos</code></td> <td> <p><code>List of <a href="https://bazel.build/docs/build-ref.html#labels">labels</a>; Optional; Default is []</code></p> <p>Additional repository labels (filegroups of wheel/egg files) to look for requirements.</p> </td> </tr> <tr id="pex_test.req_files"> <td><code>req_files</code></td> <td> <p><code>List of <a href="https://bazel.build/docs/build-ref.html#labels">labels</a>; Optional; Default is []</code></p> <p>Add requirements from the given requirements files. Must be provided as labels.</p> This feature will reduce build determinism! It tells pex to resolve all the transitive python dependencies and fetch them from pypi. It is recommended that you use eggs or specify no_index instead where possible.
reqs	List of strings; Optional; Default is [] External requirements to retrieve from pypi, in requirements.txt format. This feature will reduce build determinism! It tells pex to resolve all the transitive python dependencies and fetch them from pypi. It is recommended that you use eggs instead where possible.
zip_safe	Boolean; Optional; Default is True </td> </tr>