DESCRIPTION.rst 7.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275
  1. Wheel
  2. =====
  3. A built-package format for Python.
  4. A wheel is a ZIP-format archive with a specially formatted filename
  5. and the .whl extension. It is designed to contain all the files for a
  6. PEP 376 compatible install in a way that is very close to the on-disk
  7. format. Many packages will be properly installed with only the "Unpack"
  8. step (simply extracting the file onto sys.path), and the unpacked archive
  9. preserves enough information to "Spread" (copy data and scripts to their
  10. final locations) at any later time.
  11. The wheel project provides a `bdist_wheel` command for setuptools
  12. (requires setuptools >= 0.8.0). Wheel files can be installed with a
  13. newer `pip` from https://github.com/pypa/pip or with wheel's own command
  14. line utility.
  15. The wheel documentation is at http://wheel.rtfd.org/. The file format
  16. is documented in PEP 427 (http://www.python.org/dev/peps/pep-0427/).
  17. The reference implementation is at https://bitbucket.org/pypa/wheel
  18. Why not egg?
  19. ------------
  20. Python's egg format predates the packaging related standards we have
  21. today, the most important being PEP 376 "Database of Installed Python
  22. Distributions" which specifies the .dist-info directory (instead of
  23. .egg-info) and PEP 426 "Metadata for Python Software Packages 2.0"
  24. which specifies how to express dependencies (instead of requires.txt
  25. in .egg-info).
  26. Wheel implements these things. It also provides a richer file naming
  27. convention that communicates the Python implementation and ABI as well
  28. as simply the language version used in a particular package.
  29. Unlike .egg, wheel will be a fully-documented standard at the binary
  30. level that is truly easy to install even if you do not want to use the
  31. reference implementation.
  32. 0.24.0
  33. ======
  34. - The python tag used for pure-python packages is now .pyN (major version
  35. only). This change actually occurred in 0.23.0 when the --python-tag
  36. option was added, but was not explicitly mentioned in the changelog then.
  37. - wininst2wheel and egg2wheel removed. Use "wheel convert [archive]"
  38. instead.
  39. - Wheel now supports setuptools style conditional requirements via the
  40. extras_require={} syntax. Separate 'extra' names from conditions using
  41. the : character. Wheel's own setup.py does this. (The empty-string
  42. extra is the same as install_requires.) These conditional requirements
  43. should work the same whether the package is installed by wheel or
  44. by setup.py.
  45. 0.23.0
  46. ======
  47. - Compatibiltiy tag flags added to the bdist_wheel command
  48. - sdist should include files necessary for tests
  49. - 'wheel convert' can now also convert unpacked eggs to wheel
  50. - Rename pydist.json to metadata.json to avoid stepping on the PEP
  51. - The --skip-scripts option has been removed, and not generating scripts is now
  52. the default. The option was a temporary approach until installers could
  53. generate scripts themselves. That is now the case with pip 1.5 and later.
  54. Note that using pip 1.4 to install a wheel without scripts will leave the
  55. installation without entry-point wrappers. The "wheel install-scripts"
  56. command can be used to generate the scripts in such cases.
  57. - Thank you contributors
  58. 0.22.0
  59. ======
  60. - Include entry_points.txt, scripts a.k.a. commands, in experimental
  61. pydist.json
  62. - Improved test_requires parsing
  63. - Python 2.6 fixes, "wheel version" command courtesy pombredanne
  64. 0.21.0
  65. ======
  66. - Pregenerated scripts are the default again.
  67. - "setup.py bdist_wheel --skip-scripts" turns them off.
  68. - setuptools is no longer a listed requirement for the 'wheel'
  69. package. It is of course still required in order for bdist_wheel
  70. to work.
  71. - "python -m wheel" avoids importing pkg_resources until it's necessary.
  72. 0.20.0
  73. ======
  74. - No longer include console_scripts in wheels. Ordinary scripts (shell files,
  75. standalone Python files) are included as usual.
  76. - Include new command "python -m wheel install-scripts [distribution
  77. [distribution ...]]" to install the console_scripts (setuptools-style
  78. scripts using pkg_resources) for a distribution.
  79. 0.19.0
  80. ======
  81. - pymeta.json becomes pydist.json
  82. 0.18.0
  83. ======
  84. - Python 3 Unicode improvements
  85. 0.17.0
  86. ======
  87. - Support latest PEP-426 "pymeta.json" (json-format metadata)
  88. 0.16.0
  89. ======
  90. - Python 2.6 compatibility bugfix (thanks John McFarlane)
  91. - Non-prerelease version number
  92. 1.0.0a2
  93. =======
  94. - Bugfix for C-extension tags for CPython 3.3 (using SOABI)
  95. 1.0.0a1
  96. =======
  97. - Bugfix for bdist_wininst converter "wheel convert"
  98. - Bugfix for dists where "is pure" is None instead of True or False
  99. 1.0.0a0
  100. =======
  101. - Update for version 1.0 of Wheel (PEP accepted).
  102. - Python 3 fix for moving Unicode Description to metadata body
  103. - Include rudimentary API documentation in Sphinx (thanks Kevin Horn)
  104. 0.15.0
  105. ======
  106. - Various improvements
  107. 0.14.0
  108. ======
  109. - Changed the signature format to better comply with the current JWS spec.
  110. Breaks all existing signatures.
  111. - Include ``wheel unsign`` command to remove RECORD.jws from an archive.
  112. - Put the description in the newly allowed payload section of PKG-INFO
  113. (METADATA) files.
  114. 0.13.0
  115. ======
  116. - Use distutils instead of sysconfig to get installation paths; can install
  117. headers.
  118. - Improve WheelFile() sort.
  119. - Allow bootstrap installs without any pkg_resources.
  120. 0.12.0
  121. ======
  122. - Unit test for wheel.tool.install
  123. 0.11.0
  124. ======
  125. - API cleanup
  126. 0.10.3
  127. ======
  128. - Scripts fixer fix
  129. 0.10.2
  130. ======
  131. - Fix keygen
  132. 0.10.1
  133. ======
  134. - Preserve attributes on install.
  135. 0.10.0
  136. ======
  137. - Include a copy of pkg_resources. Wheel can now install into a virtualenv
  138. that does not have distribute (though most packages still require
  139. pkg_resources to actually work; wheel install distribute)
  140. - Define a new setup.cfg section [wheel]. universal=1 will
  141. apply the py2.py3-none-any tag for pure python wheels.
  142. 0.9.7
  143. =====
  144. - Only import dirspec when needed. dirspec is only needed to find the
  145. configuration for keygen/signing operations.
  146. 0.9.6
  147. =====
  148. - requires-dist from setup.cfg overwrites any requirements from setup.py
  149. Care must be taken that the requirements are the same in both cases,
  150. or just always install from wheel.
  151. - drop dirspec requirement on win32
  152. - improved command line utility, adds 'wheel convert [egg or wininst]' to
  153. convert legacy binary formats to wheel
  154. 0.9.5
  155. =====
  156. - Wheel's own wheel file can be executed by Python, and can install itself:
  157. ``python wheel-0.9.5-py27-none-any/wheel install ...``
  158. - Use argparse; basic ``wheel install`` command should run with only stdlib
  159. dependencies.
  160. - Allow requires_dist in setup.cfg's [metadata] section. In addition to
  161. dependencies in setup.py, but will only be interpreted when installing
  162. from wheel, not from sdist. Can be qualified with environment markers.
  163. 0.9.4
  164. =====
  165. - Fix wheel.signatures in sdist
  166. 0.9.3
  167. =====
  168. - Integrated digital signatures support without C extensions.
  169. - Integrated "wheel install" command (single package, no dependency
  170. resolution) including compatibility check.
  171. - Support Python 3.3
  172. - Use Metadata 1.3 (PEP 426)
  173. 0.9.2
  174. =====
  175. - Automatic signing if WHEEL_TOOL points to the wheel binary
  176. - Even more Python 3 fixes
  177. 0.9.1
  178. =====
  179. - 'wheel sign' uses the keys generated by 'wheel keygen' (instead of generating
  180. a new key at random each time)
  181. - Python 2/3 encoding/decoding fixes
  182. - Run tests on Python 2.6 (without signature verification)
  183. 0.9
  184. ===
  185. - Updated digital signatures scheme
  186. - Python 3 support for digital signatures
  187. - Always verify RECORD hashes on extract
  188. - "wheel" command line tool to sign, verify, unpack wheel files
  189. 0.8
  190. ===
  191. - none/any draft pep tags update
  192. - improved wininst2wheel script
  193. - doc changes and other improvements
  194. 0.7
  195. ===
  196. - sort .dist-info at end of wheel archive
  197. - Windows & Python 3 fixes from Paul Moore
  198. - pep8
  199. - scripts to convert wininst & egg to wheel
  200. 0.6
  201. ===
  202. - require distribute >= 0.6.28
  203. - stop using verlib
  204. 0.5
  205. ===
  206. - working pretty well
  207. 0.4.2
  208. =====
  209. - hyphenated name fix
  210. 0.4
  211. ===
  212. - improve test coverage
  213. - improve Windows compatibility
  214. - include tox.ini courtesy of Marc Abramowitz
  215. - draft hmac sha-256 signing function
  216. 0.3
  217. ===
  218. - prototype egg2wheel conversion script
  219. 0.2
  220. ===
  221. - Python 3 compatibility
  222. 0.1
  223. ===
  224. - Initial version