Skip to content

packaging.md

Latest commit

 

History

History
executable file
·
127 lines (91 loc) · 8.4 KB

packaging.md

File metadata and controls

executable file
·
127 lines (91 loc) · 8.4 KB

py_package

py_package(name, deps, packages)

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

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps - List of labels optional []
packages List of Python packages to include in the distribution. Sub-packages are automatically included. List of strings optional []

py_wheel

py_wheel(name, abi, author, author_email, classifiers, console_scripts, deps, description_file,
         distribution, entry_points, extra_requires, homepage, license, platform, python_requires,
         python_tag, requires, stamp, strip_path_prefixes, version)

A rule for building Python Wheels.

Wheels are Python distribution format defined in https://www.python.org/dev/peps/pep-0427/.

This rule packages a set of targets into a single wheel.

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"],
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
abi Python ABI tag. 'none' for pure-Python wheels. String optional "none"
author A string specifying the author of the package. String optional ""
author_email A string specifying the email address of the package author. String optional ""
classifiers A list of strings describing the categories for the package. For valid classifiers see https://pypi.org/classifiers List of strings optional []
console_scripts 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.		 Dictionary: String -> String optional {}
deps 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.		 List of labels optional []
description_file A file containing text describing the package in a single line. Label optional None
distribution 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.		 String required
entry_points entry_points, e.g. {'console_scripts': ['main = examples.wheel.main:main']}. Dictionary: String -> List of strings optional {}
extra_requires List of optional requirements for this package Dictionary: String -> List of strings optional {}
homepage A string specifying the URL for the package homepage. String optional ""
license A string specifying the license of the package. String optional ""
platform 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", }) 		String optional "any"
python_requires A string specifying what other distributions need to be installed when this one is. See the section on Declaring required dependency for details and examples of the format of this argument. String optional ""
python_tag Supported Python version(s), eg py3, cp35.cp36, etc String optional "py3"
requires List of requirements for this package List of strings optional []
stamp 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.		 Integer optional -1
strip_path_prefixes path prefixes to strip from files added to the generated package List of strings optional []
version Version number of the package. Note that this attribute supports stamp format strings. Eg 1.2.3-{BUILD_TIMESTAMP} String required

PyWheelInfo

PyWheelInfo(name_file, wheel)

Information about a wheel produced by py_wheel

FIELDS

Name Description
name_file File: A file containing the canonical name of the wheel (after stamping, if enabled).
wheel File: The wheel file itself.