//python:packaging.bzl

Public API for for building wheels.

rulepy_package(name,deps=[],packages=[])

A rule to select all files in transitive dependencies of deps whichbelong to given set of Python packages.

This rule is intended to be used as data dependency to py_wheel rule.

Attributes:

• name –(Name)

  A unique name for this target.

  mandatory

• deps –(list[label])(default[])

  optional

• packages –(list[str])(default[])

  List of Python packages to include in the distribution.Sub-packages are automatically included.

  optional

py_wheel(name,twine=None,twine_binary='@rules_python//tools/publish:twine',publish_args=[],**kwargs)

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 thepy_wheel rule.

Currently only pure-python wheels are supported.

Changed in version 1.4.0:From now on, an emptyrequires_file is treated as if it were omitted, resulting in a validMETADATA file.

Examples:

# Package some specific py_library targets, without their dependenciespy_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"],)

To publish the wheel to PyPI, the twine package is required and it is installedby default onbzlmod setups. On legacyWORKSPACE,rules_pythondoesn’t providetwine itself(see https://github.com/bazel-contrib/rules_python/issues/1016), butyou can install it withpip_parse, just like we do any other dependencies.

Once you’ve installed twine, you can pass its label to thetwineattribute of this macro, to get a “[name].publish” target.

Example:

py_wheel(name="my_wheel",twine="@publish_deps//twine",...)

Now you can run a command like the following, which publishes to https://test.pypi.org/

%TWINE_USERNAME=__token__TWINE_PASSWORD=pypi-***\bazelrun--stamp--embed_label=1.2.4--\//path/to:my_wheel.publish--repositorytestpypi

Args:

• name – A unique name for this target.

• twine –(defaultNone)

  A label of the external location of the py_library target for twine

• twine_binary –(default“@rules_python//tools/publish:twine”)

  A label of the external location of a binary target for twine.

• publish_args –(default[])

  arguments passed to twine, e.g. [”–repository-url”, “https://pypi.my.org/simple/”].These are subject to make var expansion, as with theargs attribute.Note that you can also pass additional args to the bazel run command as in the example above.

• kwargs – other named parameters passed to the underlyingpy_wheel rule

rulepy_wheel_dist(name,out,wheel=None)

Prepare a dist/ folder, following Python’s packaging standard practice.

See https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archiveswhich 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.

Attributes:

• name –(Name)

  A unique name for this target.

  mandatory

• out –(str)

  name of the resulting directory

  mandatory

• wheel –(label)(defaultNone)

  apy_wheel target

  optional

  Required providers:PyWheelInfo

rulepy_wheel_rule(name,distribution,version,abi='none',author='',author_email='',classifiers=[],compress=True,config_settings={},console_scripts={},data_files={},deps=[],description_content_type='',description_file=None,entry_points={},extra_distinfo_files={},extra_requires={},extra_requires_files={},homepage='',license='',platform='any',project_urls={},python_requires='',python_tag='py3',requires=[],requires_file=None,stamp=-1,strip_path_prefixes=[],summary='')

Internal rule used by thepy_wheel macro.

These intentionally have the same name to avoid sharp edges with Bazel macros.For example, abazelquery for a user’spy_wheel macro expands topy_wheel targets,in the way they expect.

Attributes:

• name –(Name)

  A unique name for this target.

  mandatory

• distribution –(str)

  Name of the distribution.

  This should match the project name on PyPI. It’s also the name that is used torefer to the package in other packages’ dependencies.

  Workspace status keys are expanded using{NAME} format, for example:

  • distribution="package.{CLASSIFIER}"

  • distribution="{DISTRIBUTION}"

  For the available keys, see https://bazel.build/docs/user-manual#workspace-status

  mandatory

• version –(str)

  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 knownduring the analysis phase and the stamp data is available only during the action execution.

  Thepy_wheel macro produces a.dist-suffix target which creates adist/ folder containing the wheel with the stamped name, suitable for publishing.

  Seepy_wheel_dist for more info.

  mandatory

• abi –(str)(default“none”)

  Python ABI tag. ‘none’ for pure-Python wheels.

  optional

• author –(str)(default“”)

  A string specifying the author of the package.

  optional

• author_email –(str)(default“”)

  A string specifying the email address of the package author.

  optional

• classifiers –(list[str])(default[])

  A list of strings describing the categories for the package. For valid classifiers see https://pypi.org/classifiers

  optional

• compress –(bool)(defaultTrue)

  Enable compression of the final archive.

  optional

• config_settings –(dict[label,str])(default{})

  Config settings to change for this target.

  The keys are labels for settings, and the values are strings for the new valueto use. PassLabel objects or canonical label strings for the keys to ensurethey resolve as expected (canonical labels start with@@ and can beobtained by callingstr(Label(...))).

  Most@rules_python//python/config_setting settings can be used here, whichallows, for example, making only a certainpy_binary use--boostrap_impl=script.

  Additional or custom config settings can be registered using theadd_transition_setting API. This allows, for example, forcing aparticular CPU, or defining a custom setting thatselect() uses elsewhereto pick betweenpip.parse hubs. See the [How to guide on multipleversions of a library] for a more concrete example.

  Note

  These values are transitioned on, so will affect the analysis graph and theassociated memory overhead. The more unique configurations in your overallbuild, the more memory and (often unnecessary) re-analysis and re-buildingcan occur. Seehttps://bazel.build/extending/config#memory-performance-considerations formore information about risks and considerations.

  Added in version 1.7.0.

  optional

• console_scripts –(dict[str,str])(default{})

  Deprecated console_script entry points, e.g.{'main':'examples.wheel.main:main'}.

  Deprecated: prefer theentry_points attribute, which supportsconsole_scripts as well as other entry points.

  optional

• data_files –(dict[label,str])(default{})

  Any file that is not normally installed inside site-packages goes into the .data directory, named as the .dist-info directory but with the .data/ extension. Allowed paths: (“purelib”, “platlib”, “headers”, “scripts”, “data”)

  optional

• deps –(list[label])(default[])

  Targets to be included in the distribution.

  The targets to package are usuallypy_library rules or filesets (for packaging data files).

  Note it’s usually better to packagepy_library targets and useentry_points attribute to specifyconsole_scripts than to packagepy_binary rules.py_binary targets would wrap a executable script thattries to locate.runfiles directory which is not packaged in the wheel.

  optional

• description_content_type –(str)(default“”)

  The type of contents in description_file. If not provided, the type will be inferred from the extension of description_file. Also see https://packaging.python.org/en/latest/specifications/core-metadata/#description-content-type

  optional

• description_file –(label)(defaultNone)

  A file containing text describing the package.

  optional

• entry_points –(dict[str,list[str]])(default{})

  entry_points, e.g.{'console_scripts':['main=examples.wheel.main:main']}.

  optional

• extra_distinfo_files –(dict[label,str])(default{})

  Extra files to add to distinfo directory in the archive.

  optional

• extra_requires –(dict[str,list[str]])(default{})

  A mapping ofextras options to lists of requirements (similar torequires). This attribute is mutually exclusive withextra_requires_file.

  optional

• extra_requires_files –(dict[label,str])(default{})

  A mapping of requirements files (similar torequires_file) to the name of anextras option This attribute is mutually exclusive withextra_requires.

  optional

• homepage –(str)(default“”)

  A string specifying the URL for the package homepage.

  optional

• license –(str)(default“”)

  A string specifying the license of the package.

  optional

• platform –(str)(default“any”)

  Supported platform. Use ‘any’ for pure-Python wheel.

  If you have included platform-specific data, such as a .pyd or .soextension module, you will need to specify the platform in standardpip format. If you support multiple platforms, you can defineplatform constraints, then use a select() to specify the appropriatespecifier, 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",})

  optional

• project_urls –(dict[str,str])(default{})

  A string dict specifying additional browsable URLs for the project and corresponding labels, where label is the key and url is the value. e.g{{"BugTracker":"http://bitbucket.org/tarek/distribute/issues/"}}

  optional

• python_requires –(str)(default“”)

  Python versions required by this distribution, e.g. ‘>=3.5,<3.7’

  optional

• python_tag –(str)(default“py3”)

  Supported Python version(s), egpy3,cp35.cp36, etc

  optional

• requires –(list[str])(default[])

  List of requirements for this package. See the section onDeclaring required dependency for details and examples of the format of this argument. This attribute is mutually exclusive withrequires_file.

  optional

• requires_file –(label)(defaultNone)

  A file containing a list of requirements for this package. See the section onDeclaring required dependency for details and examples of the format of this argument. This attribute is mutually exclusive withrequires.

  optional

• stamp –(int)(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.

  optional

• strip_path_prefixes –(list[str])(default[])

  Path prefixes to strip from files added to the generated package.Prefixes are checkedin order and only thefirst match will be used.

  For example:

  • ["foo","foo/bar/baz"] will strip"foo/bar/baz/file.py" to"bar/baz/file.py"

  • ["foo/bar/baz","foo"] will strip"foo/bar/baz/file.py" to"file.py" and"foo/file2.py" to"file2.py"

  optional

• summary –(str)(default“”)

  A one-line summary of what the distribution does

  optional

providerPyWheelInfo

Information about a wheel produced bypy_wheel

PyWheelInfo.<init>(name_file,wheel)

PyWheelInfo.name_file

File: A file containing the canonical name of the wheel (after stamping, if enabled).

PyWheelInfo.wheel

File: The wheel file itself.