bazelbuild
docs: document `python_zip_file`
It looks like the python_zip_file output group is not documented. Let's document it.
filegroup(
name = some_binary_zip",
srcs = [":some_binary"], # the py_binary target to make into a zip, and will be the file name
output_group = "python_zip_file",
)
That will generate bazel-bin/path/to/target/some_binary.zip which you can then execute via python some_binary.zip. You need a system python to extract, but the zip does bundle its own interpreter (so your system python can be a different version) and is otherwise fully hermetic.
which you can then execute via
python some_binary.zip
It should actually have a shebang line so that it can be executed directly as ./some_binary.zip. See https://github.com/bazelbuild/bazel/issues/17629, which should also be transferred to this repo.
AIUI filegroup(..., output_group = "python_zip_file") creates a zipapp which is ever so slightly different than an executable zip file, and zipapps do require a system python interpreter.
And the build CLI option --build_python_zip creates a "a python3 script executable (binary data)".
AIUI filegroup(..., output_group = "python_zip_file") creates a zipapp
It's the same thing, and should support a shebang line. See https://peps.python.org/pep-0441/
Ah, upon further reading of the zipapp docs https://docs.python.org/3/library/zipapp.html#the-python-zip-application-archive-format:
Formally, the Python zip application format is therefore:
- An optional shebang line, containing the characters
b'#!'followed by an interpreter name, and then a newline (b'\n') character. The interpreter name can be anything acceptable to the OS “shebang” processing, or the Python launcher on Windows. The interpreter should be encoded in UTF-8 on Windows, and in sys.getfilesystemencoding() on POSIX.
That said, a system python is still required.
Shebang is optional. That pep uses "can" not "must" (emphasis mine):
Python Zip applications can be prefixed with a
#!line
Note that I'm not saying we shouldn't add the shebang. I'm just saying that the argument "the docs say it should have one" is invalid.
I was just pointing out that OP documents the current (incorrect) behavior, not in reference to the Python standards but in relation to the fact that the output group was intended to replace --build_python_zip and give the same output. That is to say that https://github.com/bazelbuild/bazel/issues/17629 should have been transferred to this repo.
the output group was intended to replace the flag
It was? I don't recall that. Reference?
It was? I don't recall that. Reference?
https://github.com/bazelbuild/bazel/issues/3530
Note that nobody argued that https://github.com/bazelbuild/bazel/issues/17629 was not a bug, only that it no longer belonged in the bazel repo after the rules were moved to rules_python.
Thanks for the reference! This is good to know. The two being slightly difference didn't make much sense to me. It sounds like either the output group was only partially implemented, or the two drifted over time. In any case, yeah, it'd be good to unify the two.
Looks like https://github.com/bazel-contrib/rules_python/blob/1.6.3/python/private/py_executable.bzl#L402-L406 tests for --build_python_zip explicitly and only creates the executable zip file if it's set.
Also see https://github.com/bazel-contrib/rules_python/issues/2586
