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