1<!-- Generated with Stardoc: http://skydoc.bazel.build --> 2 3Public API for for building wheels. 4 5<a id="py_package"></a> 6 7## py_package 8 9<pre> 10py_package(<a href="#py_package-name">name</a>, <a href="#py_package-deps">deps</a>, <a href="#py_package-packages">packages</a>) 11</pre> 12 13A rule to select all files in transitive dependencies of deps which 14belong to given set of Python packages. 15 16This rule is intended to be used as data dependency to py_wheel rule. 17 18 19**ATTRIBUTES** 20 21 22| Name | Description | Type | Mandatory | Default | 23| :------------- | :------------- | :------------- | :------------- | :------------- | 24| <a id="py_package-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 25| <a id="py_package-deps"></a>deps | - | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 26| <a id="py_package-packages"></a>packages | List of Python packages to include in the distribution. Sub-packages are automatically included. | List of strings | optional | <code>[]</code> | 27 28 29<a id="py_wheel_dist"></a> 30 31## py_wheel_dist 32 33<pre> 34py_wheel_dist(<a href="#py_wheel_dist-name">name</a>, <a href="#py_wheel_dist-out">out</a>, <a href="#py_wheel_dist-wheel">wheel</a>) 35</pre> 36 37Prepare a dist/ folder, following Python's packaging standard practice. 38 39See https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives 40which recommends a dist/ folder containing the wheel file(s), source distributions, etc. 41 42This also has the advantage that stamping information is included in the wheel's filename. 43 44 45**ATTRIBUTES** 46 47 48| Name | Description | Type | Mandatory | Default | 49| :------------- | :------------- | :------------- | :------------- | :------------- | 50| <a id="py_wheel_dist-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 51| <a id="py_wheel_dist-out"></a>out | name of the resulting directory | String | required | | 52| <a id="py_wheel_dist-wheel"></a>wheel | a [py_wheel rule](/docs/packaging.md#py_wheel_rule) | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> | 53 54 55<a id="py_wheel_rule"></a> 56 57## py_wheel_rule 58 59<pre> 60py_wheel_rule(<a href="#py_wheel_rule-name">name</a>, <a href="#py_wheel_rule-abi">abi</a>, <a href="#py_wheel_rule-author">author</a>, <a href="#py_wheel_rule-author_email">author_email</a>, <a href="#py_wheel_rule-classifiers">classifiers</a>, <a href="#py_wheel_rule-console_scripts">console_scripts</a>, <a href="#py_wheel_rule-deps">deps</a>, 61 <a href="#py_wheel_rule-description_content_type">description_content_type</a>, <a href="#py_wheel_rule-description_file">description_file</a>, <a href="#py_wheel_rule-distribution">distribution</a>, <a href="#py_wheel_rule-entry_points">entry_points</a>, 62 <a href="#py_wheel_rule-extra_distinfo_files">extra_distinfo_files</a>, <a href="#py_wheel_rule-extra_requires">extra_requires</a>, <a href="#py_wheel_rule-homepage">homepage</a>, <a href="#py_wheel_rule-license">license</a>, <a href="#py_wheel_rule-platform">platform</a>, <a href="#py_wheel_rule-project_urls">project_urls</a>, 63 <a href="#py_wheel_rule-python_requires">python_requires</a>, <a href="#py_wheel_rule-python_tag">python_tag</a>, <a href="#py_wheel_rule-requires">requires</a>, <a href="#py_wheel_rule-stamp">stamp</a>, <a href="#py_wheel_rule-strip_path_prefixes">strip_path_prefixes</a>, <a href="#py_wheel_rule-summary">summary</a>, <a href="#py_wheel_rule-version">version</a>) 64</pre> 65 66Internal rule used by the [py_wheel macro](/docs/packaging.md#py_wheel). 67 68These intentionally have the same name to avoid sharp edges with Bazel macros. 69For example, a `bazel query` for a user's `py_wheel` macro expands to `py_wheel` targets, 70in the way they expect. 71 72 73**ATTRIBUTES** 74 75 76| Name | Description | Type | Mandatory | Default | 77| :------------- | :------------- | :------------- | :------------- | :------------- | 78| <a id="py_wheel_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 79| <a id="py_wheel_rule-abi"></a>abi | Python ABI tag. 'none' for pure-Python wheels. | String | optional | <code>"none"</code> | 80| <a id="py_wheel_rule-author"></a>author | A string specifying the author of the package. | String | optional | <code>""</code> | 81| <a id="py_wheel_rule-author_email"></a>author_email | A string specifying the email address of the package author. | String | optional | <code>""</code> | 82| <a id="py_wheel_rule-classifiers"></a>classifiers | A list of strings describing the categories for the package. For valid classifiers see https://pypi.org/classifiers | List of strings | optional | <code>[]</code> | 83| <a id="py_wheel_rule-console_scripts"></a>console_scripts | Deprecated console_script entry points, e.g. <code>{'main': 'examples.wheel.main:main'}</code>.<br><br>Deprecated: prefer the <code>entry_points</code> attribute, which supports <code>console_scripts</code> as well as other entry points. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | <code>{}</code> | 84| <a id="py_wheel_rule-deps"></a>deps | Targets to be included in the distribution.<br><br>The targets to package are usually <code>py_library</code> rules or filesets (for packaging data files).<br><br>Note it's usually better to package <code>py_library</code> targets and use <code>entry_points</code> attribute to specify <code>console_scripts</code> than to package <code>py_binary</code> rules. <code>py_binary</code> targets would wrap a executable script that tries to locate <code>.runfiles</code> directory which is not packaged in the wheel. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | <code>[]</code> | 85| <a id="py_wheel_rule-description_content_type"></a>description_content_type | 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 | String | optional | <code>""</code> | 86| <a id="py_wheel_rule-description_file"></a>description_file | A file containing text describing the package. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> | 87| <a id="py_wheel_rule-distribution"></a>distribution | Name of the distribution.<br><br>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.<br><br>Workspace status keys are expanded using <code>{NAME}</code> format, for example: - <code>distribution = "package.{CLASSIFIER}"</code> - <code>distribution = "{DISTRIBUTION}"</code><br><br>For the available keys, see https://bazel.build/docs/user-manual#workspace-status | String | required | | 88| <a id="py_wheel_rule-entry_points"></a>entry_points | entry_points, e.g. <code>{'console_scripts': ['main = examples.wheel.main:main']}</code>. | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> List of strings</a> | optional | <code>{}</code> | 89| <a id="py_wheel_rule-extra_distinfo_files"></a>extra_distinfo_files | Extra files to add to distinfo directory in the archive. | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional | <code>{}</code> | 90| <a id="py_wheel_rule-extra_requires"></a>extra_requires | List of optional requirements for this package | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> List of strings</a> | optional | <code>{}</code> | 91| <a id="py_wheel_rule-homepage"></a>homepage | A string specifying the URL for the package homepage. | String | optional | <code>""</code> | 92| <a id="py_wheel_rule-license"></a>license | A string specifying the license of the package. | String | optional | <code>""</code> | 93| <a id="py_wheel_rule-platform"></a>platform | Supported platform. Use 'any' for pure-Python wheel.<br><br>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:<br><br><code> platform = select({ "//platforms:windows_x86_64": "win_amd64", "//platforms:macos_x86_64": "macosx_10_7_x86_64", "//platforms:linux_x86_64": "manylinux2014_x86_64", }) </code> | String | optional | <code>"any"</code> | 94| <a id="py_wheel_rule-project_urls"></a>project_urls | 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 <code>{{"Bug Tracker": "http://bitbucket.org/tarek/distribute/issues/"}}</code> | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional | <code>{}</code> | 95| <a id="py_wheel_rule-python_requires"></a>python_requires | Python versions required by this distribution, e.g. '>=3.5,<3.7' | String | optional | <code>""</code> | 96| <a id="py_wheel_rule-python_tag"></a>python_tag | Supported Python version(s), eg <code>py3</code>, <code>cp35.cp36</code>, etc | String | optional | <code>"py3"</code> | 97| <a id="py_wheel_rule-requires"></a>requires | List of requirements for this package. See the section on [Declaring required dependency](https://setuptools.readthedocs.io/en/latest/userguide/dependency_management.html#declaring-dependencies) for details and examples of the format of this argument. | List of strings | optional | <code>[]</code> | 98| <a id="py_wheel_rule-stamp"></a>stamp | Whether to encode build information into the wheel. Possible values:<br><br>- <code>stamp = 1</code>: Always stamp the build information into the wheel, even in [--nostamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) builds. This setting should be avoided, since it potentially kills remote caching for the target and any downstream actions that depend on it.<br><br>- <code>stamp = 0</code>: Always replace build information by constant values. This gives good build result caching.<br><br>- <code>stamp = -1</code>: Embedding of build information is controlled by the [--[no]stamp](https://docs.bazel.build/versions/main/user-manual.html#flag--stamp) flag.<br><br>Stamped targets are not rebuilt unless their dependencies change. | Integer | optional | <code>-1</code> | 99| <a id="py_wheel_rule-strip_path_prefixes"></a>strip_path_prefixes | path prefixes to strip from files added to the generated package | List of strings | optional | <code>[]</code> | 100| <a id="py_wheel_rule-summary"></a>summary | A one-line summary of what the distribution does | String | optional | <code>""</code> | 101| <a id="py_wheel_rule-version"></a>version | Version number of the package.<br><br>Note that this attribute supports stamp format strings as well as 'make variables'. For example: - <code>version = "1.2.3-{BUILD_TIMESTAMP}"</code> - <code>version = "{BUILD_EMBED_LABEL}"</code> - <code>version = "$(VERSION)"</code><br><br>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.<br><br>The [<code>py_wheel</code>](/docs/packaging.md#py_wheel) macro produces a <code>.dist</code>-suffix target which creates a <code>dist/</code> folder containing the wheel with the stamped name, suitable for publishing.<br><br>See [<code>py_wheel_dist</code>](/docs/packaging.md#py_wheel_dist) for more info. | String | required | | 102 103 104<a id="PyWheelInfo"></a> 105 106## PyWheelInfo 107 108<pre> 109PyWheelInfo(<a href="#PyWheelInfo-name_file">name_file</a>, <a href="#PyWheelInfo-wheel">wheel</a>) 110</pre> 111 112Information about a wheel produced by `py_wheel` 113 114**FIELDS** 115 116 117| Name | Description | 118| :------------- | :------------- | 119| <a id="PyWheelInfo-name_file"></a>name_file | File: A file containing the canonical name of the wheel (after stamping, if enabled). | 120| <a id="PyWheelInfo-wheel"></a>wheel | File: The wheel file itself. | 121 122 123<a id="py_wheel"></a> 124 125## py_wheel 126 127<pre> 128py_wheel(<a href="#py_wheel-name">name</a>, <a href="#py_wheel-twine">twine</a>, <a href="#py_wheel-publish_args">publish_args</a>, <a href="#py_wheel-kwargs">kwargs</a>) 129</pre> 130 131Builds a Python Wheel. 132 133Wheels are Python distribution format defined in https://www.python.org/dev/peps/pep-0427/. 134 135This macro packages a set of targets into a single wheel. 136It wraps the [py_wheel rule](#py_wheel_rule). 137 138Currently only pure-python wheels are supported. 139 140Examples: 141 142```python 143# Package some specific py_library targets, without their dependencies 144py_wheel( 145 name = "minimal_with_py_library", 146 # Package data. We're building "example_minimal_library-0.0.1-py3-none-any.whl" 147 distribution = "example_minimal_library", 148 python_tag = "py3", 149 version = "0.0.1", 150 deps = [ 151 "//examples/wheel/lib:module_with_data", 152 "//examples/wheel/lib:simple_module", 153 ], 154) 155 156# Use py_package to collect all transitive dependencies of a target, 157# selecting just the files within a specific python package. 158py_package( 159 name = "example_pkg", 160 # Only include these Python packages. 161 packages = ["examples.wheel"], 162 deps = [":main"], 163) 164 165py_wheel( 166 name = "minimal_with_py_package", 167 # Package data. We're building "example_minimal_package-0.0.1-py3-none-any.whl" 168 distribution = "example_minimal_package", 169 python_tag = "py3", 170 version = "0.0.1", 171 deps = [":example_pkg"], 172) 173``` 174 175To publish the wheel to Pypi, the twine package is required. 176rules_python doesn't provide twine itself, see https://github.com/bazelbuild/rules_python/issues/1016 177However you can install it with pip_parse, just like we do in the WORKSPACE file in rules_python. 178 179Once you've installed twine, you can pass its label to the `twine` attribute of this macro, 180to get a "[name].publish" target. 181 182Example: 183 184```python 185py_wheel( 186 name = "my_wheel", 187 twine = "@publish_deps_twine//:pkg", 188 ... 189) 190``` 191 192Now you can run a command like the following, which publishes to https://test.pypi.org/ 193 194```sh 195% TWINE_USERNAME=__token__ TWINE_PASSWORD=pypi-*** \ 196 bazel run --stamp --embed_label=1.2.4 -- \ 197 //path/to:my_wheel.publish --repository testpypi 198``` 199 200 201**PARAMETERS** 202 203 204| Name | Description | Default Value | 205| :------------- | :------------- | :------------- | 206| <a id="py_wheel-name"></a>name | A unique name for this target. | none | 207| <a id="py_wheel-twine"></a>twine | A label of the external location of the py_library target for twine | <code>None</code> | 208| <a id="py_wheel-publish_args"></a>publish_args | arguments passed to twine, e.g. ["--repository-url", "https://pypi.my.org/simple/"]. These are subject to make var expansion, as with the <code>args</code> attribute. Note that you can also pass additional args to the bazel run command as in the example above. | <code>[]</code> | 209| <a id="py_wheel-kwargs"></a>kwargs | other named parameters passed to the underlying [py_wheel rule](#py_wheel_rule) | none | 210 211 212