8000 Added packaging docs (#480) · tecton-ai/rules_python@eaed210 · GitHub
[go: up one dir, main page]
Skip to content

Commit eaed210

Browse files
UebelAndreUebelAndre
authored
Added packaging docs (bazel-contrib#480)
1 parent a53c0d9 commit eaed210

File tree

3 files changed

+371
-21
lines changed

3 files changed

+371
-21
lines changed

‎docs/BUILD

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,3 +88,9 @@ stardoc(
8888
out = "whl.md",
8989
input = "//python:whl.bzl",
9090
)
91+
92+
stardoc(
93+
name = "packaging-docs",
94+
out = "packaging.md",
95+
input = "//python:packaging.bzl",
96+
)

‎docs/packaging.md

Lines changed: 315 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,315 @@
1+
<!-- Generated with Stardoc: http://skydoc.bazel.build -->
2+
3+
<a name="#py_package"></a>
4+
5+
## py_package
6+
7+
<pre>
8+
py_package(<a href="#py_package-name">name</a>, <a href="#py_package-deps">deps</a>, <a href="#py_package-packages">packages</a>)
9+
</pre>
10+
11+
A rule to select all files in transitive dependencies of deps which
12+
belong to given set of Python packages.
13+
14+
This rule is intended to be used as data dependency to py_wheel rule
15+
16+
17+
### Attributes
18+
19+
<table class="params-table">
20+
<colgroup>
21+
<col class="col-param" />
22+
<col class="col-description" />
23+
</colgroup>
24+
<tbody>
25+
<tr id="py_package-name">
26+
<td><code>name</code></td>
27+
<td>
28+
<a href="https://bazel.build/docs/build-ref.html#name">Name</a>; required
29+
<p>
30+
A unique name for this target.
31+
</p>
32+
</td>
33+
</tr>
34+
<tr id="py_package-deps">
35+
<td><code>deps</code></td>
36+
<td>
37+
<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>; optional
38+
</td>
39+
</tr>
40+
<tr id="py_package-packages">
41+
<td><code>packages</code></td>
42+
<td>
43+
List of strings; optional
44+
<p>
45+
List of Python packages to include in the distribution.
46+
Sub-packages are automatically included.
47+
</p>
48+
</td>
49+
</tr>
50+
</tbody>
51+
</table>
52+
53+
54+
<a name="#py_wheel"></a>
55+
56+
## py_wheel
57+
58+
<pre>
59+
py_wheel(<a href="#py_wheel-name">name</a>, <a href="#py_wheel-abi">abi</a>, <a href="#py_wheel-author">author</a>, <a href="#py_wheel-author_email">author_email</a>, <a href="#py_wheel-classifiers">classifiers</a>, <a href="#py_wheel-console_scripts">console_scripts</a>, <a href="#py_wheel-deps">deps</a>, <a href="#py_wheel-description_file">description_file</a>, <a href="#py_wheel-distribution">distribution</a>, <a href="#py_wheel-entry_points">entry_points</a>, <a href="#py_wheel-extra_requires">extra_requires</a>, <a href="#py_wheel-homepage">homepage</a>, <a href="#py_wheel-license">license</a>, <a href="#py_wheel-platform">platform</a>, <a href="#py_wheel-python_requires">python_requires</a>, <a href="#py_wheel-python_tag">python_tag</a>, <a href="#py_wheel-requires">requires</a>, <a href="#py_wheel-strip_path_prefixes">strip_path_prefixes</a>, <a href="#py_wheel-version">version</a>)
60+
</pre>
61+
62+
63+
A rule for building Python Wheels.
64+
65+
Wheels are Python distribution format defined in https://www.python.org/dev/peps/pep-0427/.
66+
67+
This rule packages a set of targets into a single wheel.
68+
69+
Currently only pure-python wheels are supported.
70+
71+
Examples:
72+
73+
```python
74+
# Package just a specific py_libraries, without their dependencies
75+
py_wheel(
76+
name = "minimal_with_py_library",
77+
# Package data. We're building "example_minimal_library-0.0.1-py3-none-any.whl"
78+
distribution = "example_minimal_library",
79+
python_tag = "py3",
80+
version = "0.0.1",
81+
deps = [
82+
"//examples/wheel/lib:module_with_data",
83+
"//examples/wheel/lib:simple_module",
84+
],
85+
)
86+
87+
# Use py_package to collect all transitive dependencies of a target,
88+
# selecting just the files within a specific python package.
89+
py_package(
90+
name = "example_pkg",
91+
# Only include these Python packages.
92+
packages = ["examples.wheel"],
93+
deps = [":main"],
94+
)
95+
96+
py_wheel(
97+
name = "minimal_with_py_package",
98+
# Package data. We're building "example_minimal_package-0.0.1-py3-none-any.whl"
99+
distribution = "example_minimal_package",
100+
python_tag = "py3",
101+
version = "0.0.1",
102+
deps = [":example_pkg"],
103+
)
104+
```
105+
106+
107+
### Attributes
108+
109+
<table class="params-table">
110+
<colgroup>
111+
<col class="col-param" />
112+
<col class="col-description" />
113+
</colgroup>
114+
<tbody>
115+
<tr id="py_wheel-name">
116+
<td><code>name</code></td>
117+
<td>
118+
<a href="https://bazel.build/docs/build-ref.html#name">Name</a>; required
119+
<p>
120+
A unique name for this target.
121+
</p>
122+
</td>
123+
</tr>
124+
<tr id="py_wheel-abi">
125+
<td><code>abi</code></td>
126+
<td>
127+
String; optional
128+
<p>
129+
Python ABI tag. 'none' for pure-Python wheels.
130+
</p>
131+
</td>
132+
</tr>
133+
<tr id="py_wheel-author">
134+
<td><code>author</code></td>
135+
<td>
136+
String; optional
137+
<p>
138+
A string specifying the author of the package.
139+
</p>
140+
</td>
141+
</tr>
142+
<tr id="py_wheel-author_email">
143+
<td><code>author_email</code></td>
144+
<td>
145+
String; optional
146+
<p>
147+
A string specifying the email address of the package author.
148+
</p>
149+
</td>
150+
</tr>
151+
<tr id="py_wheel-classifiers">
152+
<td><code>classifiers</code></td>
153+
<td>
154+
List of strings; optional
155+
<p>
156+
A list of strings describing the categories for the package.
157+
</p>
158+
</td>
159+
</tr>
160+
<tr id="py_wheel-console_scripts">
161+
<td><code>console_scripts</code></td>
162+
<td>
163+
<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a>; optional
164+
<p>
165+
Deprecated console_script entry points, e.g. `{'main': 'examples.wheel.main:main'}`.
166+
167+
Deprecated: prefer the `entry_points` attribute, which supports `console_scripts` as well as other entry points.
168+
</p>
169+
</td>
170+
</tr>
171+
<tr id="py_wheel-deps">
172+
<td><code>deps</code></td>
173+
<td>
174+
<a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a>; optional
175+
<p>
176+
Targets to be included in the distribution.
177+
178+
The targets to package are usually `py_library` rules or filesets (for packaging data files).
179+
180+
Note it's usually better to package `py_library` targets and use
181+
`entry_points` attribute to specify `console_scripts` than to package
182+
`py_binary` rules. `py_binary` targets would wrap a executable script that
183+
tries to locate `.runfiles` directory which is not packaged in the wheel.
184+
</p>
185+
</td>
186+
</tr>
187+
<tr id="py_wheel-description_file">
188+
<td><code>description_file</code></td>
189+
<td>
190+
<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; optional
191+
<p>
192+
A file containing text describing the package in a single line.
193+
</p>
194+
</td>
195+
</tr>
196+
<tr id="py_wheel-distribution">
197+
<td><code>distribution</code></td>
198+
<td>
199+
String; required
200+
<p>
201+
Name of the distribution.
202+
203+
This should match the project name onm PyPI. It's also the name that is used to
204+
refer to the package in other packages' dependencies.
205+
</p>
206+
</td>
207+
</tr>
208+
<tr id="py_wheel-entry_points">
209+
<td><code>entry_points</code></td>
210+
<td>
211+
<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> List of strings</a>; optional
212+
<p>
213+
entry_points, e.g. `{'console_scripts': ['main = examples.wheel.main:main']}`.
214+
</p>
215+
</td>
216+
</tr>
217+
<tr id="py_wheel-extra_requires">
218+
<td><code>extra_requires</code></td>
219+
<td>
220+
<a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> List of strings</a>; optional
221+
<p>
222+
List of optional requirements for this package
223+
</p>
224+
</td>
225+
</tr>
226+
<tr id="py_wheel-homepage">
227+
<td><code>homepage</code></td>
228+
<td>
229+
String; optional
230 F438 +
<p>
231+
A string specifying the URL for the package homepage.
232+
</p>
233+
</td>
234+
</tr>
235+
<tr id="py_wheel-license">
236+
<td><code>license</code></td>
237+
<td>
238+
String; optional
239+
<p>
240+
A string specifying the license of the package.
241+
</p>
242+
</td>
243+
</tr>
244+
<tr id="py_wheel-platform">
245+
<td><code>platform</code></td>
246+
<td>
247+
String; optional
248+
<p>
249+
Supported platform. Use 'any' for pure-Python wheel.
250+
251+
If you have included platform-specific data, such as a .pyd or .so
252+
extension module, you will need to specify the platform in standard
253+
pip format. If you support multiple platforms, you can define
254+
platform constraints, then use a select() to specify the appropriate
255+
specifier, eg:
256+
257+
<code>
258+
platform = select({
259+
"//platforms:windows_x86_64": "win_amd64",
260+
"//platforms:macos_x86_64": "macosx_10_7_x86_64",
261+
"//platforms:linux_x86_64": "manylinux2014_x86_64",
262+
})
263+
</code>
264+
</p>
265+
</td>
266+
</tr>
267+
<tr id="py_wheel-python_requires">
268+
<td><code>python_requires</code></td>
269+
<td>
270+
String; optional
271+
<p>
272+
A string specifying what other distributions need to be installed when this one is. 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.
273+
</p>
274+
</td>
275+
</tr>
276+
<tr id="py_wheel-python_tag">
277+
<td><code>python_tag</code></td>
278+
<td>
279+
String; optional
280+
<p>
281+
Supported Python version(s), eg `py3`, `cp35.cp36`, etc
282+
</p>
283+
</td>
284+
</tr>
285+
<tr id="py_wheel-requires">
286+
<td><code>requires</code></td>
287+
<td>
288+
List of strings; optional
289+
<p>
290+
List of requirements for this package
291+
</p>
292+
</td>
293+
</tr>
294+
<tr id="py_wheel-strip_path_prefixes">
295+
<td><code>strip_path_prefixes</code></td>
296+
<td>
297+
List of strings; optional
298+
<p>
299+
path prefixes to strip from files added to the generated package
300+
</p>
301+
</td>
302+
</tr>
303+
<tr id="py_wheel-version">
304+
<td><code>version</code></td>
305+
<td>
306+
String; required
307+
<p>
308+
Version number of the package
309+
</p>
310+
</td>
311+
</tr>
312+
</tbody>
313+
</table>
314+
315+

0 commit comments

Comments
 (0)
0