|
| 1 | +:orphan: |
| 2 | + |
| 3 | +.. This page is retained solely for existing links to /distributing/index.html. |
| 4 | + Direct readers to the PPUG instead. |
| 5 | +
|
1 | 6 | .. _distributing-index: |
2 | 7 |
|
3 | 8 | ############################### |
4 | 9 | Distributing Python Modules |
5 | 10 | ############################### |
6 | 11 |
|
7 | | -:Email: distutils-sig@python.org |
8 | | - |
9 | | - |
10 | | -As a popular open source development project, Python has an active |
11 | | -supporting community of contributors and users that also make their software |
12 | | -available for other Python developers to use under open source license terms. |
13 | | - |
14 | | -This allows Python users to share and collaborate effectively, benefiting |
15 | | -from the solutions others have already created to common (and sometimes |
16 | | -even rare!) problems, as well as potentially contributing their own |
17 | | -solutions to the common pool. |
18 | | - |
19 | | -This guide covers the distribution part of the process. For a guide to |
20 | | -installing other Python projects, refer to the |
21 | | -:ref:`installation guide <installing-index>`. |
22 | | - |
23 | 12 | .. note:: |
24 | 13 |
|
25 | | - For corporate and other institutional users, be aware that many |
26 | | - organisations have their own policies around using and contributing to |
27 | | - open source software. Please take such policies into account when making |
28 | | - use of the distribution and installation tools provided with Python. |
29 | | - |
30 | | - |
31 | | -Key terms |
32 | | -========= |
33 | | - |
34 | | -* the `Python Package Index <https://pypi.org>`__ is a public |
35 | | - repository of open source licensed packages made available for use by |
36 | | - other Python users |
37 | | -* the `Python Packaging Authority |
38 | | - <https://www.pypa.io/>`__ are the group of |
39 | | - developers and documentation authors responsible for the maintenance and |
40 | | - evolution of the standard packaging tools and the associated metadata and |
41 | | - file format standards. They maintain a variety of tools, documentation |
42 | | - and issue trackers on `GitHub <https://github.com/pypa>`__. |
43 | | -* ``distutils`` is the original build and distribution system first added |
44 | | - to the Python standard library in 1998. While direct use of ``distutils`` |
45 | | - is being phased out, it still laid the foundation for the current packaging |
46 | | - and distribution infrastructure, and it not only remains part of the |
47 | | - standard library, but its name lives on in other ways (such as the name |
48 | | - of the mailing list used to coordinate Python packaging standards |
49 | | - development). |
50 | | -* `setuptools`_ is a (largely) drop-in replacement for ``distutils`` first |
51 | | - published in 2004. Its most notable addition over the unmodified |
52 | | - ``distutils`` tools was the ability to declare dependencies on other |
53 | | - packages. It is currently recommended as a more regularly updated |
54 | | - alternative to ``distutils`` that offers consistent support for more |
55 | | - recent packaging standards across a wide range of Python versions. |
56 | | -* `wheel`_ (in this context) is a project that adds the ``bdist_wheel`` |
57 | | - command to ``distutils``/`setuptools`_. This produces a cross platform |
58 | | - binary packaging format (called "wheels" or "wheel files" and defined in |
59 | | - :pep:`427`) that allows Python libraries, even those including binary |
60 | | - extensions, to be installed on a system without needing to be built |
61 | | - locally. |
62 | | - |
63 | | -.. _setuptools: https://setuptools.readthedocs.io/en/latest/ |
64 | | -.. _wheel: https://wheel.readthedocs.io/ |
65 | | - |
66 | | -Open source licensing and collaboration |
67 | | -======================================= |
68 | | - |
69 | | -In most parts of the world, software is automatically covered by copyright. |
70 | | -This means that other developers require explicit permission to copy, use, |
71 | | -modify and redistribute the software. |
72 | | - |
73 | | -Open source licensing is a way of explicitly granting such permission in a |
74 | | -relatively consistent way, allowing developers to share and collaborate |
75 | | -efficiently by making common solutions to various problems freely available. |
76 | | -This leaves many developers free to spend more time focusing on the problems |
77 | | -that are relatively unique to their specific situation. |
78 | | - |
79 | | -The distribution tools provided with Python are designed to make it |
80 | | -reasonably straightforward for developers to make their own contributions |
81 | | -back to that common pool of software if they choose to do so. |
82 | | - |
83 | | -The same distribution tools can also be used to distribute software within |
84 | | -an organisation, regardless of whether that software is published as open |
85 | | -source software or not. |
86 | | - |
87 | | - |
88 | | -Installing the tools |
89 | | -==================== |
90 | | - |
91 | | -The standard library does not include build tools that support modern |
92 | | -Python packaging standards, as the core development team has found that it |
93 | | -is important to have standard tools that work consistently, even on older |
94 | | -versions of Python. |
95 | | - |
96 | | -The currently recommended build and distribution tools can be installed |
97 | | -by invoking the ``pip`` module at the command line:: |
98 | | - |
99 | | - python -m pip install setuptools wheel twine |
100 | | - |
101 | | -.. note:: |
102 | | - |
103 | | - For POSIX users (including macOS and Linux users), these instructions |
104 | | - assume the use of a :term:`virtual environment`. |
105 | | - |
106 | | - For Windows users, these instructions assume that the option to |
107 | | - adjust the system PATH environment variable was selected when installing |
108 | | - Python. |
109 | | - |
110 | | -The Python Packaging User Guide includes more details on the `currently |
111 | | -recommended tools`_. |
112 | | - |
113 | | -.. _currently recommended tools: https://packaging.python.org/guides/tool-recommendations/#packaging-tool-recommendations |
114 | | - |
115 | | -.. index:: |
116 | | - single: Python Package Index (PyPI) |
117 | | - single: PyPI; (see Python Package Index (PyPI)) |
118 | | - |
119 | | -.. _publishing-python-packages: |
120 | | - |
121 | | -Reading the Python Packaging User Guide |
122 | | -======================================= |
123 | | - |
124 | | -The Python Packaging User Guide covers the various key steps and elements |
125 | | -involved in creating and publishing a project: |
126 | | - |
127 | | -* `Project structure`_ |
128 | | -* `Building and packaging the project`_ |
129 | | -* `Uploading the project to the Python Package Index`_ |
130 | | -* `The .pypirc file`_ |
131 | | - |
132 | | -.. _Project structure: https://packaging.python.org/tutorials/packaging-projects/#packaging-python-projects |
133 | | -.. _Building and packaging the project: https://packaging.python.org/tutorials/packaging-projects/#creating-the-package-files |
134 | | -.. _Uploading the project to the Python Package Index: https://packaging.python.org/tutorials/packaging-projects/#uploading-the-distribution-archives |
135 | | -.. _The .pypirc file: https://packaging.python.org/specifications/pypirc/ |
136 | | - |
137 | | - |
138 | | -How do I...? |
139 | | -============ |
140 | | - |
141 | | -These are quick answers or links for some common tasks. |
142 | | - |
143 | | -... choose a name for my project? |
144 | | ---------------------------------- |
145 | | - |
146 | | -This isn't an easy topic, but here are a few tips: |
147 | | - |
148 | | -* check the Python Package Index to see if the name is already in use |
149 | | -* check popular hosting sites like GitHub, Bitbucket, etc to see if there |
150 | | - is already a project with that name |
151 | | -* check what comes up in a web search for the name you're considering |
152 | | -* avoid particularly common words, especially ones with multiple meanings, |
153 | | - as they can make it difficult for users to find your software when |
154 | | - searching for it |
155 | | - |
156 | | - |
157 | | -... create and distribute binary extensions? |
158 | | --------------------------------------------- |
159 | | - |
160 | | -This is actually quite a complex topic, with a variety of alternatives |
161 | | -available depending on exactly what you're aiming to achieve. See the |
162 | | -Python Packaging User Guide for more information and recommendations. |
163 | | - |
164 | | -.. seealso:: |
165 | | - |
166 | | - `Python Packaging User Guide: Binary Extensions |
167 | | - <https://packaging.python.org/guides/packaging-binary-extensions/>`__ |
168 | | - |
169 | | -.. other topics: |
| 14 | + Information and guidance on distributing Python modules and packages |
| 15 | + has been moved to the `Python Packaging User Guide`_, |
| 16 | + and the tutorial on `packaging Python projects`_. |
170 | 17 |
|
171 | | - Once the Development & Deployment part of PPUG is fleshed out, some of |
172 | | - those sections should be linked from new questions here (most notably, |
173 | | - we should have a question about avoiding depending on PyPI that links to |
174 | | - https://packaging.python.org/en/latest/mirrors/) |
| 18 | + .. _Python Packaging User Guide: https://packaging.python.org/ |
| 19 | + .. _packaging Python projects: https://packaging.python.org/en/latest/tutorials/packaging-projects/ |
0 commit comments