packaging
Public API for for building wheels.
Rules
py_package
A rule to select all files in transitive dependencies of deps which belong to given set of Python packages.
This rule is intended to be used as data dependency to py_wheel rule.
Example usage (generated):
load("@rules_python//python:packaging.bzl", "py_package")
py_package(
# A unique name for this target.
name = "",
)
name
Required name.
A unique name for this target.
deps
Optional list of labels.
Default: []
packages
Optional list of strings.
Default: []
List of Python packages to include in the distribution. Sub-packages are automatically included.
py_wheel_dist
Prepare a dist/ folder, following Python's packaging standard practice.
See https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives which recommends a dist/ folder containing the wheel file(s), source distributions, etc.
This also has the advantage that stamping information is included in the wheel's filename.
Example usage (generated):
load("@rules_python//python:packaging.bzl", "py_wheel_dist")
py_wheel_dist(
# A unique name for this target.
name = "",
# name of the resulting directory
out = "",
)
name
Required name.
A unique name for this target.
out
Required string.
name of the resulting directory
wheel
Optional label.
Default: None
[Must provide PyWheelInfo
]
py_wheel_rule
Internal rule used by the py_wheel macro.
These intentionally have the same name to avoid sharp edges with Bazel macros.
For example, a bazel query
for a user's py_wheel
macro expands to py_wheel
targets,
in the way they expect.
Example usage (generated):
load("@rules_python//python:packaging.bzl", "py_wheel_rule")
py_wheel_rule(
# A unique name for this target.
name = "",
# Name of the distribution
distribution = "",
# Version number of the package
version = "",
)
name
Required name.
A unique name for this target.
abi
Optional string.
Default: "none"
Python ABI tag. 'none' for pure-Python wheels.
author
Optional string.
Default: ""
A string specifying the author of the package.
author_email
Optional string.
Default: ""
A string specifying the email address of the package author.
classifiers
Optional list of strings.
Default: []
A list of strings describing the categories for the package. For valid classifiers see https://pypi.org/classifiers
console_scripts
Optional dictionary: String → String.
Default: {}
Deprecated console_script entry points, e.g. {'main': 'examples.wheel.main:main'}
.
Deprecated: prefer the entry_points
attribute, which supports console_scripts
as well as other entry points.
deps
Optional list of labels.
Default: []
Targets to be included in the distribution.
The targets to package are usually py_library
rules or filesets (for packaging data files).
Note it's usually better to package py_library
targets and use
entry_points
attribute to specify console_scripts
than to package
py_binary
rules. py_binary
targets would wrap a executable script that
tries to locate .runfiles
directory which is not packaged in the wheel.
description_file
Optional label.
Default: None
A file containing text describing the package.
distribution
Required string.
Name of the distribution.
This should match the project name onm PyPI. It's also the name that is used to refer to the package in other packages' dependencies.
entry_points
Optional dictionary: String → List of strings.
Default: {}
entry_points, e.g. {'console_scripts': ['main = examples.wheel.main:main']}
.
extra_distinfo_files
Optional dictionary: Label → String.
Default: {}
Extra files to add to distinfo directory in the archive.
extra_requires
Optional dictionary: String → List of strings.
Default: {}
List of optional requirements for this package
homepage
Optional string.
Default: ""
A string specifying the URL for the package homepage.
license
Optional string.
Default: ""
A string specifying the license of the package.
platform
Optional string.
Default: "any"
Supported platform. Use 'any' for pure-Python wheel.
If you have included platform-specific data, such as a .pyd or .so extension module, you will need to specify the platform in standard pip format. If you support multiple platforms, you can define platform constraints, then use a select() to specify the appropriate specifier, eg:
platform = select({
"//platforms:windows_x86_64": "win_amd64",
"//platforms:macos_x86_64": "macosx_10_7_x86_64",
"//platforms:linux_x86_64": "manylinux2014_x86_64",
})
python_requires
Optional string.
Default: ""
Python versions required by this distribution, e.g. '>=3.5,<3.7'
python_tag
Optional string.
Default: "py3"
Supported Python version(s), eg py3
, cp35.cp36
, etc
requires
Optional list of strings.
Default: []
List of requirements for this package. See the section on Declaring required dependency for details and examples of the format of this argument.
stamp
Optional integer.
Default: -1
Whether to encode build information into the wheel. Possible values:
stamp = 1
: Always stamp the build information into the wheel, even in --nostamp builds. This setting should be avoided, since it potentially kills remote caching for the target and any downstream actions that depend on it.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 flag.
Stamped targets are not rebuilt unless their dependencies change.
strip_path_prefixes
Optional list of strings.
Default: []
path prefixes to strip from files added to the generated package
version
Required string.
Version number of the package.
Note that this attribute supports stamp format strings as well as 'make variables'. For example:
version = "1.2.3-{BUILD_TIMESTAMP}"
version = "{BUILD_EMBED_LABEL}"
version = "$(VERSION)"
Note that Bazel's output filename cannot include the stamp information, as outputs must be known during the analysis phase and the stamp data is available only during the action execution.
The py_wheel
macro produces a .dist
-suffix target which creates a
dist/
folder containing the wheel with the stamped name, suitable for publishing.
See py_wheel_dist
for more info.
Macros and Functions
py_wheel
Builds a Python Wheel.
Wheels are Python distribution format defined in https://www.python.org/dev/peps/pep-0427/.
This macro packages a set of targets into a single wheel. It wraps the py_wheel rule.
Currently only pure-python wheels are supported.
Examples:
# Package some specific py_library targets, without their dependencies
py_wheel(
name = "minimal_with_py_library",
# Package data. We're building "example_minimal_library-0.0.1-py3-none-any.whl"
distribution = "example_minimal_library",
python_tag = "py3",
version = "0.0.1",
deps = [
"//examples/wheel/lib:module_with_data",
"//examples/wheel/lib:simple_module",
],
)
# Use py_package to collect all transitive dependencies of a target,
# selecting just the files within a specific python package.
py_package(
name = "example_pkg",
# Only include these Python packages.
packages = ["examples.wheel"],
deps = [":main"],
)
py_wheel(
name = "minimal_with_py_package",
# Package data. We're building "example_minimal_package-0.0.1-py3-none-any.whl"
distribution = "example_minimal_package",
python_tag = "py3",
version = "0.0.1",
deps = [":example_pkg"],
)
Example usage (generated):
load("@rules_python//python:packaging.bzl", "py_wheel")
py_wheel(
# A unique name for this target.
name = "",
)
name
Required.
A unique name for this target.
kwargs
Optional.
other named parameters passed to the underlying py_wheel rule
Providers
PyWheelInfo
Information about a wheel produced by py_wheel