1.. _distributing-index: 2 3############################### 4 Distributing Python Modules 5############################### 6 7:Email: distutils-sig@python.org 8 9 10As a popular open source development project, Python has an active 11supporting community of contributors and users that also make their software 12available for other Python developers to use under open source license terms. 13 14This allows Python users to share and collaborate effectively, benefiting 15from the solutions others have already created to common (and sometimes 16even rare!) problems, as well as potentially contributing their own 17solutions to the common pool. 18 19This guide covers the distribution part of the process. For a guide to 20installing other Python projects, refer to the 21:ref:`installation guide <installing-index>`. 22 23.. note:: 24 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 31Key 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 67Open source licensing and collaboration 68======================================= 69 70In most parts of the world, software is automatically covered by copyright. 71This means that other developers require explicit permission to copy, use, 72modify and redistribute the software. 73 74Open source licensing is a way of explicitly granting such permission in a 75relatively consistent way, allowing developers to share and collaborate 76efficiently by making common solutions to various problems freely available. 77This leaves many developers free to spend more time focusing on the problems 78that are relatively unique to their specific situation. 79 80The distribution tools provided with Python are designed to make it 81reasonably straightforward for developers to make their own contributions 82back to that common pool of software if they choose to do so. 83 84The same distribution tools can also be used to distribute software within 85an organisation, regardless of whether that software is published as open 86source software or not. 87 88 89Installing the tools 90==================== 91 92The standard library does not include build tools that support modern 93Python packaging standards, as the core development team has found that it 94is important to have standard tools that work consistently, even on older 95versions of Python. 96 97The currently recommended build and distribution tools can be installed 98by 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 111The Python Packaging User Guide includes more details on the `currently 112recommended 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 122Reading the Python Packaging User Guide 123======================================= 124 125The Python Packaging User Guide covers the various key steps and elements 126involved 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: \ 134 https://packaging.python.org/tutorials/packaging-projects/#packaging-python-projects 135.. _Building and packaging the project: \ 136 https://packaging.python.org/tutorials/packaging-projects/#creating-the-package-files 137.. _Uploading the project to the Python Package Index: \ 138 https://packaging.python.org/tutorials/packaging-projects/#uploading-the-distribution-archives 139.. _The .pypirc file: \ 140 https://packaging.python.org/specifications/pypirc/ 141 142 143How do I...? 144============ 145 146These are quick answers or links for some common tasks. 147 148... choose a name for my project? 149--------------------------------- 150 151This isn't an easy topic, but here are a few tips: 152 153* check the Python Package Index to see if the name is already in use 154* check popular hosting sites like GitHub, Bitbucket, etc to see if there 155 is already a project with that name 156* check what comes up in a web search for the name you're considering 157* avoid particularly common words, especially ones with multiple meanings, 158 as they can make it difficult for users to find your software when 159 searching for it 160 161 162... create and distribute binary extensions? 163-------------------------------------------- 164 165This is actually quite a complex topic, with a variety of alternatives 166available depending on exactly what you're aiming to achieve. See the 167Python Packaging User Guide for more information and recommendations. 168 169.. seealso:: 170 171 `Python Packaging User Guide: Binary Extensions 172 <https://packaging.python.org/guides/packaging-binary-extensions/>`__ 173 174.. other topics: 175 176 Once the Development & Deployment part of PPUG is fleshed out, some of 177 those sections should be linked from new questions here (most notably, 178 we should have a question about avoiding depending on PyPI that links to 179 https://packaging.python.org/en/latest/mirrors/) 180