← Back to branch summary

~dkuhlman/python-training-materials/Materials

« back to all changes in this revision

Viewing changes to python-3.5.1-docs-html/_sources/distributing/index.txt

  • Committer: Dave Kuhlman
  • Date: 2017-04-15 16:24:56 UTC
  • Revision ID: dkuhlman@davekuhlman.org-20170415162456-iav9vozzg4iwqwv3
Updated docs

Show diffs side-by-side

added added

removed removed

Lines of Context:
python-3.5.1-docs-html/_sources/distributing/index.txt
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
 
 
34
 
* the `Python Packaging Index <https://pypi.python.org/pypi>`__ 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://packaging.python.org/en/latest/future.html>`__ 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.pypa.io/en/latest/setuptools.html
65
 
.. _wheel: http://wheel.readthedocs.org
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 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.
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/en/latest/current.html#packaging-tool-recommendations
115
 
 
116
 
Reading the guide
117
 
=================
118
 
 
119
 
The Python Packaging User Guide covers the various key steps and elements
120
 
involved in creating a project:
121
 
 
122
 
* `Project structure`_
123
 
* `Building and packaging the project`_
124
 
* `Uploading the project to the Python Packaging Index`_
125
 
 
126
 
.. _Project structure: \
127
 
   https://packaging.python.org/en/latest/distributing.html#creating-your-own-project
128
 
.. _Building and packaging the project: \
129
 
   https://packaging.python.org/en/latest/distributing.html#packaging-your-project
130
 
.. _Uploading the project to the Python Packaging Index: \
131
 
   https://packaging.python.org/en/latest/distributing.html#uploading-your-project-to-pypi
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
 
 
144
 
* check the Python Packaging Index to see if the name is already in use
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
163
 
   <https://packaging.python.org/en/latest/extensions.html>`__
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
170
 
   https://packaging.python.org/en/latest/deployment.html#pypi-mirrors-and-caches)