Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 1 | .. _distributing-index: |
| 2 | |
| 3 | ############################### |
| 4 | Distributing Python Modules |
| 5 | ############################### |
| 6 | |
| 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 | .. 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 | |
| 31 | Key terms |
| 32 | ========= |
| 33 | |
Nick Coghlan | 5c4fbd5 | 2014-10-04 21:11:25 +1000 | [diff] [blame] | 34 | * the `Python Packaging Index <https://pypi.python.org/pypi>`__ is a public |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 35 | repository of open source licensed packages made available for use by |
| 36 | other Python users |
| 37 | * the `Python Packaging Authority |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame] | 38 | <https://www.pypa.io/>`__ are the group of |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 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/>`__. |
Nick Coghlan | 3894ae2 | 2014-10-26 00:00:04 +1000 | [diff] [blame] | 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 |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 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). |
Nick Coghlan | 3894ae2 | 2014-10-26 00:00:04 +1000 | [diff] [blame] | 51 | * `setuptools`_ is a (largely) drop-in replacement for :mod:`distutils` first |
Zachary Ware | 66f305b | 2014-06-05 13:41:06 -0500 | [diff] [blame] | 52 | published in 2004. Its most notable addition over the unmodified |
Nick Coghlan | 3894ae2 | 2014-10-26 00:00:04 +1000 | [diff] [blame] | 53 | :mod:`distutils` tools was the ability to declare dependencies on other |
Nick Coghlan | e1d54e5 | 2014-05-26 00:50:11 +1000 | [diff] [blame] | 54 | packages. It is currently recommended as a more regularly updated |
Nick Coghlan | 3894ae2 | 2014-10-26 00:00:04 +1000 | [diff] [blame] | 55 | alternative to :mod:`distutils` that offers consistent support for more |
Nick Coghlan | e1d54e5 | 2014-05-26 00:50:11 +1000 | [diff] [blame] | 56 | recent packaging standards across a wide range of Python versions. |
Nick Coghlan | 3894ae2 | 2014-10-26 00:00:04 +1000 | [diff] [blame] | 57 | * `wheel`_ (in this context) is a project that adds the ``bdist_wheel`` |
| 58 | command to :mod:`distutils`/`setuptools`_. This produces a cross platform |
Nick Coghlan | e1d54e5 | 2014-05-26 00:50:11 +1000 | [diff] [blame] | 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. |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 63 | |
Ned Deily | 8f5798e | 2016-06-05 17:38:48 -0700 | [diff] [blame] | 64 | .. _setuptools: https://setuptools.readthedocs.io/en/latest/ |
Sanyam Khurana | 338cd83 | 2018-01-20 05:55:37 +0530 | [diff] [blame^] | 65 | .. _wheel: https://wheel.readthedocs.io/ |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 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 |
Nick Coghlan | 1d52096 | 2014-09-06 20:38:23 +1000 | [diff] [blame] | 98 | by invoking the ``pip`` module at the command line:: |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 99 | |
Nick Coghlan | 1d52096 | 2014-09-06 20:38:23 +1000 | [diff] [blame] | 100 | python -m pip install setuptools wheel twine |
| 101 | |
| 102 | .. note:: |
| 103 | |
| 104 | For POSIX users (including Mac OS X 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. |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 110 | |
Nick Coghlan | e1d54e5 | 2014-05-26 00:50:11 +1000 | [diff] [blame] | 111 | The Python Packaging User Guide includes more details on the `currently |
| 112 | recommended tools`_. |
| 113 | |
Sanyam Khurana | 338cd83 | 2018-01-20 05:55:37 +0530 | [diff] [blame^] | 114 | .. _currently recommended tools: https://packaging.python.org/guides/tool-recommendations/#packaging-tool-recommendations |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 115 | |
| 116 | Reading the guide |
| 117 | ================= |
| 118 | |
| 119 | The Python Packaging User Guide covers the various key steps and elements |
Nick Coghlan | e1d54e5 | 2014-05-26 00:50:11 +1000 | [diff] [blame] | 120 | involved in creating a project: |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 121 | |
| 122 | * `Project structure`_ |
| 123 | * `Building and packaging the project`_ |
Nick Coghlan | 5c4fbd5 | 2014-10-04 21:11:25 +1000 | [diff] [blame] | 124 | * `Uploading the project to the Python Packaging Index`_ |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 125 | |
| 126 | .. _Project structure: \ |
Sanyam Khurana | 338cd83 | 2018-01-20 05:55:37 +0530 | [diff] [blame^] | 127 | https://packaging.python.org/tutorials/distributing-packages/ |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 128 | .. _Building and packaging the project: \ |
Sanyam Khurana | 338cd83 | 2018-01-20 05:55:37 +0530 | [diff] [blame^] | 129 | https://packaging.python.org/tutorials/distributing-packages/#packaging-your-project |
Nick Coghlan | 5c4fbd5 | 2014-10-04 21:11:25 +1000 | [diff] [blame] | 130 | .. _Uploading the project to the Python Packaging Index: \ |
Sanyam Khurana | 338cd83 | 2018-01-20 05:55:37 +0530 | [diff] [blame^] | 131 | https://packaging.python.org/tutorials/distributing-packages/#uploading-your-project-to-pypi |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 132 | |
| 133 | |
| 134 | How do I...? |
| 135 | ============ |
| 136 | |
| 137 | These are quick answers or links for some common tasks. |
| 138 | |
| 139 | ... choose a name for my project? |
| 140 | --------------------------------- |
| 141 | |
| 142 | This isn't an easy topic, but here are a few tips: |
| 143 | |
Nick Coghlan | 5c4fbd5 | 2014-10-04 21:11:25 +1000 | [diff] [blame] | 144 | * check the Python Packaging Index to see if the name is already in use |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 145 | * check popular hosting sites like GitHub, BitBucket, etc to see if there |
| 146 | is already a project with that name |
| 147 | * check what comes up in a web search for the name you're considering |
| 148 | * avoid particularly common words, especially ones with multiple meanings, |
| 149 | as they can make it difficult for users to find your software when |
| 150 | searching for it |
| 151 | |
| 152 | |
| 153 | ... create and distribute binary extensions? |
| 154 | -------------------------------------------- |
| 155 | |
| 156 | This is actually quite a complex topic, with a variety of alternatives |
| 157 | available depending on exactly what you're aiming to achieve. See the |
| 158 | Python Packaging User Guide for more information and recommendations. |
| 159 | |
| 160 | .. seealso:: |
| 161 | |
| 162 | `Python Packaging User Guide: Binary Extensions |
Sanyam Khurana | 338cd83 | 2018-01-20 05:55:37 +0530 | [diff] [blame^] | 163 | <https://packaging.python.org/guides/packaging-binary-extensions/>`__ |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 164 | |
| 165 | .. other topics: |
| 166 | |
| 167 | Once the Development & Deployment part of PPUG is fleshed out, some of |
| 168 | those sections should be linked from new questions here (most notably, |
| 169 | we should have a question about avoiding depending on PyPI that links to |
Georg Brandl | 5d94134 | 2016-02-26 19:37:12 +0100 | [diff] [blame] | 170 | https://packaging.python.org/en/latest/mirrors/) |