[Python-checkins] peps: PEP-427 (wheel) edits
daniel.holth
python-checkins at python.org
Sat Feb 9 04:32:43 CET 2013
http://hg.python.org/peps/rev/d9d42d5c1b41
changeset: 4720:d9d42d5c1b41
user: Daniel Holth <dholth at fastmail.fm>
date: Fri Feb 08 22:32:34 2013 -0500
summary:
PEP-427 (wheel) edits
files:
pep-0427.txt | 69 ++++++++++++++++++++-------------------
1 files changed, 36 insertions(+), 33 deletions(-)
diff --git a/pep-0427.txt b/pep-0427.txt
--- a/pep-0427.txt
+++ b/pep-0427.txt
@@ -17,13 +17,13 @@
This PEP describes a built-package format for Python called "wheel".
-A wheel is a ZIP-format archive with a specially formatted file name
-and the ``.whl`` extension. It contains a single distribution nearly
-as it would be installed according to PEP 376 with a particular
-installation scheme. A wheel file may be installed by simply
-unpacking into site-packages with the standard 'unzip' tool, while
-preserving enough information to spread its contents out onto their
-final paths at any later time.
+A wheel is a ZIP-format archive with a specially formatted file name and
+the ``.whl`` extension. It contains a single distribution nearly as it
+would be installed according to PEP 376 with a particular installation
+scheme. Although a specialized installer is recommended, a wheel file
+may be installed by simply unpacking into site-packages with the standard
+'unzip' tool while preserving enough information to spread its contents
+out onto their final paths at any later time.
Note
@@ -147,7 +147,7 @@
File contents
'''''''''''''
-The conents of a wheel file, where {distribution} is replaced with the
+The contents of a wheel file, where {distribution} is replaced with the
name of the package, e.g. ``beaglevote`` and {version} is replaced with
its version, e.g. ``1.0.0``, consist of:
@@ -163,8 +163,8 @@
``b'#!python'`` in order to enjoy script wrapper generation and
``#!python`` rewriting at install time. They may have any or no
extension.
-#. ``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.3
- (PEP 426) or greater format metadata.
+#. ``{distribution}-{version}.dist-info/METADATA`` is Metadata version 1.2
+ (PEP 345) or greater format metadata.
#. ``{distribution}-{version}.dist-info/WHEEL`` is metadata about the archive
itself::
@@ -195,20 +195,21 @@
#. Wheel .dist-info directories include at a minimum METADATA, WHEEL,
and RECORD.
-#. METADATA is the PEP 426 metadata (Metadata version 1.3 or greater)
-#. WHEEL is the wheel metadata, specific to a build of the package.
+#. METADATA is the package metadata, the same format as PKG-INFO as
+ found at the root of sdists.
+#. WHEEL is the wheel metadata specific to a build of the package.
#. RECORD is a list of (almost) all the files in the wheel and their
secure hashes. Unlike PEP 376, every file except RECORD, which
cannot contain a hash of itself, must include its hash. The hash
algorithm must be sha256 or better; specifically, md5 and sha1 are
not permitted, as signed wheel files rely on the strong hashes in
RECORD to validate the integrity of the archive.
-#. INSTALLER and REQUESTED are not included in the archive.
+#. PEP 376's INSTALLER and REQUESTED are not included in the archive.
#. RECORD.jws is used for digital signatures. It is not mentioned in
RECORD.
#. RECORD.p7s is allowed as a courtesy to anyone who would prefer to
- use s/mime signatures to secure their wheel files. It is not
- mentioned in RECORD and it is ignored by the official tools.
+ use S/MIME signatures to secure their wheel files. It is not
+ mentioned in RECORD.
#. During extraction, wheel installers verify all the hashes in RECORD
against the file contents. Apart from RECORD and its signatures,
installation will fail if any file in the archive is not both
@@ -239,29 +240,31 @@
``digestname=urlsafe_b64encode_nopad(digest)`` (urlsafe base64
encoding with no trailing = characters) as the second column instead
of an md5sum. All possible entries are hashed, including any
-generated files such as .pyc files, but not RECORD. For example::
+generated files such as .pyc files, but not RECORD which cannot contain its
+own hash. For example::
file.py,sha256=AVTFPZpEKzuHr7OvQZmhaU3LvwKz06AJw8mT\_pNh2yI,3144
distribution-1.0.dist-info/RECORD,,
The signature file(s) RECORD.jws and RECORD.p7s are not mentioned in
RECORD at all since they can only be added after RECORD is generated.
-Every other file in the archive must have a correct hash in RECORD,
+Every other file in the archive must have a correct hash in RECORD
or the installation will fail.
If JSON web signatures are used, one or more JSON Web Signature JSON
-Serialization (JWS-JS) signatures may be stored in a file RECORD.jws
-adjacent to RECORD. JWS is used to sign RECORD by including the SHA-256
-hash of RECORD as the JWS payload::
+Serialization (JWS-JS) signatures is stored in a file RECORD.jws adjacent
+to RECORD. JWS is used to sign RECORD by including the SHA-256 hash of
+RECORD as the signature's JSON payload::
{ "hash": "sha256=ADD-r2urObZHcxBW3Cr-vDCu5RJwT4CaRTHiFmbcIYY" }
-If RECORD.p7s is used, it must contain a PKCS#7 format signature of
-RECORD.
+If RECORD.p7s is used, it must contain a detached S/MIME format signature
+of RECORD.
-A wheel installer may assume that the signature has already been checked
-against RECORD, and only must verify the hashes in RECORD against the
-extracted file contents.
+A wheel installer is not required to understand digital signatures but
+MUST verify the hashes in RECORD against the extracted file contents.
+When the installer checks file hashes against RECORD, a separate signature
+checker only needs to establish that RECORD matches the signature.
See
@@ -313,21 +316,21 @@
Attached signatures are more convenient than detached signatures
because they travel with the archive. Since only the individual files
are signed, the archive can be recompressed without invalidating
- the signature, or individual files can be verified without having
+ the signature or individual files can be verified without having
to download the whole archive.
Why does wheel allow JWS signatures?
- The JOSE specifications including JWS are designed to be easy to
- implement, a feature that is also one of wheel's primary design goals.
+ The JOSE specifications of which JWS is a part are designed to be easy
+ to implement, a feature that is also one of wheel's primary design
+ goals. JWS yields a useful, concise pure-Python implementation.
Why does wheel also allow S/MIME signatures?
- S/MIME signatures are allowed for users who need or want to use an
+ S/MIME signatures are allowed for users who need or want to use
existing public key infrastructure with wheel.
- Signed packages are only a basic building block in a secured package
- update system. Wheel only provides the building block. A complete
- system would provide for key distribution and trust and would specify
- which signature format was required.
+ Signed packages are only a basic building block in a secure package
+ update system and many kinds of attacks are possible even when
+ packages are signed. Wheel only provides the building block.
Appendix
========
--
Repository URL: http://hg.python.org/peps
More information about the Python-checkins
mailing list