~dkuhlman/python-training-materials/Materials

<span id="distributing-index"></span><h1>Distributing Python Modules<a class="headerlink" href="#distributing-python-modules" title="Permalink to this headline">¶</a></h1>

<tr class="field-odd field"><th class="field-name">Email:</th><td class="field-body"><a class="reference external" href="mailto:distutils-sig%40python.org">distutils-sig<span>@</span>python<span>.</span>org</a></td>

</tr>

</tbody>

</table>

<p>As a popular open source development project, Python has an active

supporting community of contributors and users that also make their software

available for other Python developers to use under open source license terms.</p>

<p>This allows Python users to share and collaborate effectively, benefiting

from the solutions others have already created to common (and sometimes

even rare!) problems, as well as potentially contributing their own

solutions to the common pool.</p>

<p>This guide covers the distribution part of the process. For a guide to

installing other Python projects, refer to the

<a class="reference internal" href="../installing/index.html#installing-index"><span>installation guide</span></a>.</p>

<p class="last">For corporate and other institutional users, be aware that many

organisations have their own policies around using and contributing to

open source software. Please take such policies into account when making

use of the distribution and installation tools provided with Python.</p>

100

</div>

101

102

<h2>Key terms<a class="headerlink" href="#key-terms" title="Permalink to this headline">¶</a></h2>

103

104

<li>the <a class="reference external" href="https://pypi.python.org/pypi">Python Packaging Index</a> is a public

105

repository of open source licensed packages made available for use by

106

other Python users</li>

107

<li>the <a class="reference external" href="https://packaging.python.org/en/latest/future.html">Python Packaging Authority</a> are the group of

108

developers and documentation authors responsible for the maintenance and

109

evolution of the standard packaging tools and the associated metadata and

110

file format standards. They maintain a variety of tools, documentation

111

and issue trackers on both <a class="reference external" href="https://github.com/pypa">GitHub</a> and

112

<a class="reference external" href="https://bitbucket.org/pypa/">BitBucket</a>.</li>

113

<li><a class="reference internal" href="../library/distutils.html#module-distutils" title="distutils: Support for building and installing Python modules into an existing Python installation."><code class="xref py py-mod docutils literal"><span class="pre">distutils</span></code></a> is the original build and distribution system first added

114

to the Python standard library in 1998. While direct use of <a class="reference internal" href="../library/distutils.html#module-distutils" title="distutils: Support for building and installing Python modules into an existing Python installation."><code class="xref py py-mod docutils literal"><span class="pre">distutils</span></code></a>

115

is being phased out, it still laid the foundation for the current packaging

116

and distribution infrastructure, and it not only remains part of the

117

standard library, but its name lives on in other ways (such as the name

118

of the mailing list used to coordinate Python packaging standards

119

development).</li>

120

<li><a class="reference external" href="https://setuptools.pypa.io/en/latest/setuptools.html">setuptools</a> is a (largely) drop-in replacement for <a class="reference internal" href="../library/distutils.html#module-distutils" title="distutils: Support for building and installing Python modules into an existing Python installation."><code class="xref py py-mod docutils literal"><span class="pre">distutils</span></code></a> first

121

published in 2004. Its most notable addition over the unmodified

122

<a class="reference internal" href="../library/distutils.html#module-distutils" title="distutils: Support for building and installing Python modules into an existing Python installation."><code class="xref py py-mod docutils literal"><span class="pre">distutils</span></code></a> tools was the ability to declare dependencies on other

123

packages. It is currently recommended as a more regularly updated

124

alternative to <a class="reference internal" href="../library/distutils.html#module-distutils" title="distutils: Support for building and installing Python modules into an existing Python installation."><code class="xref py py-mod docutils literal"><span class="pre">distutils</span></code></a> that offers consistent support for more

125

recent packaging standards across a wide range of Python versions.</li>

126

<li><a class="reference external" href="http://wheel.readthedocs.org">wheel</a> (in this context) is a project that adds the <code class="docutils literal"><span class="pre">bdist_wheel</span></code>

127

command to <a class="reference internal" href="../library/distutils.html#module-distutils" title="distutils: Support for building and installing Python modules into an existing Python installation."><code class="xref py py-mod docutils literal"><span class="pre">distutils</span></code></a>/<a class="reference external" href="https://setuptools.pypa.io/en/latest/setuptools.html">setuptools</a>. This produces a cross platform

128

binary packaging format (called “wheels” or “wheel files” and defined in

129

<span class="target" id="index-0"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0427"><strong>PEP 427</strong></a>) that allows Python libraries, even those including binary

130

extensions, to be installed on a system without needing to be built

131

locally.</li>

132

</ul>

133

</div>

134

135

<h2>Open source licensing and collaboration<a class="headerlink" href="#open-source-licensing-and-collaboration" title="Permalink to this headline">¶</a></h2>

136

<p>In most parts of the world, software is automatically covered by copyright.

137

This means that other developers require explicit permission to copy, use,

138

modify and redistribute the software.</p>

139

<p>Open source licensing is a way of explicitly granting such permission in a

140

relatively consistent way, allowing developers to share and collaborate

141

efficiently by making common solutions to various problems freely available.

142

This leaves many developers free to spend more time focusing on the problems

143

that are relatively unique to their specific situation.</p>

144

<p>The distribution tools provided with Python are designed to make it

145

reasonably straightforward for developers to make their own contributions

146

back to that common pool of software if they choose to do so.</p>

147

<p>The same distribution tools can also be used to distribute software within

148

an organisation, regardless of whether that software is published as open

149

source software or not.</p>

150

</div>

151

152

<h2>Installing the tools<a class="headerlink" href="#installing-the-tools" title="Permalink to this headline">¶</a></h2>

153

<p>The standard library does not include build tools that support modern

154

Python packaging standards, as the core development team has found that it

155

is important to have standard tools that work consistently, even on older

156

versions of Python.</p>

157

<p>The currently recommended build and distribution tools can be installed

158

by invoking the <code class="docutils literal"><span class="pre">pip</span></code> module at the command line:</p>

159

<div class="highlight-python"><div class="highlight"><pre>python -m pip install setuptools wheel twine

160

</pre></div>

161

</div>

162

163

164

<p>For POSIX users (including Mac OS X and Linux users), these instructions

165

assume the use of a <a class="reference internal" href="../glossary.html#term-virtual-environment"><span class="xref std std-term">virtual environment</span></a>.</p>

166

<p class="last">For Windows users, these instructions assume that the option to

167

adjust the system PATH environment variable was selected when installing

168

Python.</p>

169

</div>

170

<p>The Python Packaging User Guide includes more details on the <a class="reference external" href="https://packaging.python.org/en/latest/current.html#packaging-tool-recommendations">currently

171

recommended tools</a>.</p>

172

</div>

173

174

<h2>Reading the guide<a class="headerlink" href="#reading-the-guide" title="Permalink to this headline">¶</a></h2>

175

<p>The Python Packaging User Guide covers the various key steps and elements

176

involved in creating a project:</p>

177

178

<li><a class="reference external" href="https://packaging.python.org/en/latest/distributing.html#creating-your-own-project">Project structure</a></li>

179

<li><a class="reference external" href="https://packaging.python.org/en/latest/distributing.html#packaging-your-project">Building and packaging the project</a></li>

180

<li><a class="reference external" href="https://packaging.python.org/en/latest/distributing.html#uploading-your-project-to-pypi">Uploading the project to the Python Packaging Index</a></li>

181

</ul>

182

</div>

183

184

185

<p>These are quick answers or links for some common tasks.</p>

186

187

<h3>... choose a name for my project?<a class="headerlink" href="#choose-a-name-for-my-project" title="Permalink to this headline">¶</a></h3>

188

<p>This isn’t an easy topic, but here are a few tips:</p>

189

190

<li>check the Python Packaging Index to see if the name is already in use</li>

191

<li>check popular hosting sites like GitHub, BitBucket, etc to see if there

192

is already a project with that name</li>

193

<li>check what comes up in a web search for the name you’re considering</li>

194

<li>avoid particularly common words, especially ones with multiple meanings,

195

as they can make it difficult for users to find your software when

196

searching for it</li>

197

</ul>

198

</div>

199

200

<h3>... create and distribute binary extensions?<a class="headerlink" href="#create-and-distribute-binary-extensions" title="Permalink to this headline">¶</a></h3>

201

<p>This is actually quite a complex topic, with a variety of alternatives

202

available depending on exactly what you’re aiming to achieve. See the

203

Python Packaging User Guide for more information and recommendations.</p>

204

205

206

<p class="last"><a class="reference external" href="https://packaging.python.org/en/latest/extensions.html">Python Packaging User Guide: Binary Extensions</a></p>

207

</div>

208

</div>

209

</div>

210

</div>

211

212

213

</div>

214

</div>

215

</div>

216

217

218

<h3><a href="../contents.html">Table Of Contents</a></h3>

219

<ul>

220

<li><a class="reference internal" href="#">Distributing Python Modules</a><ul>

221

<li><a class="reference internal" href="#key-terms">Key terms</a></li>

222

<li><a class="reference internal" href="#open-source-licensing-and-collaboration">Open source licensing and collaboration</a></li>

223

<li><a class="reference internal" href="#installing-the-tools">Installing the tools</a></li>

224

<li><a class="reference internal" href="#reading-the-guide">Reading the guide</a></li>

225

226

<li><a class="reference internal" href="#choose-a-name-for-my-project">... choose a name for my project?</a></li>

227

<li><a class="reference internal" href="#create-and-distribute-binary-extensions">... create and distribute binary extensions?</a></li>

228

</ul>

229

</li>

230

</ul>

231

</li>

232

</ul>

233

234

<h4>Previous topic</h4>

235

<p class="topless"><a href="../c-api/gcsupport.html"

236

title="previous chapter">Supporting Cyclic Garbage Collection</a></p>

237

<h4>Next topic</h4>

238

<p class="topless"><a href="../installing/index.html"

239

title="next chapter">Installing Python Modules</a></p>

240

241

242

<li><a href="../bugs.html">Report a Bug</a></li>

243

<li><a href="../_sources/distributing/index.txt"

244

rel="nofollow">Show Source</a></li>

245

</ul>

246

247

248

<h3>Quick search</h3>

249

250

251

252

253

254

</form>

255

256

Enter search terms or a module, class or function name.

257

</p>

258

</div>

259

260

</div>

261

</div>

262

263

</div>

264

265

<h3>Navigation</h3>

266

<ul>

267

268

<a href="../genindex.html" title="General Index"

269

>index</a></li>

270

271

<a href="../py-modindex.html" title="Python Module Index"

272

>modules</a> |</li>

273

274

<a href="../installing/index.html" title="Installing Python Modules"

275

>next</a> |</li>

276

277

<a href="../c-api/gcsupport.html" title="Supporting Cyclic Garbage Collection"

278

>previous</a> |</li>

279

<li><img src="../_static/py.png" alt=""

280

style="vertical-align: middle; margin-top: -1px"/></li>

281

<li><a href="https://www.python.org/">Python</a> »</li>

282

<li>

283

284

<a href="../index.html">Documentation</a> »

285

</li>

286

287

</ul>

288

</div>

289

290

291

<br />

292

The Python Software Foundation is a non-profit corporation.

293

<a href="https://www.python.org/psf/donations/">Please donate.</a>

294

<br />

295

Last updated on Jan 23, 2016.

296

<a href="../bugs.html">Found a bug</a>?

297

<br />

298

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.

299

</div>

300

301

</body>

302

</html>

b'\\ No newline at end of file'

Older »