Mercurial > cpython-lru_cache-weakref

annotate Doc/packaging/tutorial.rst @ 70817:dd775b1561ba

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix markup.
author Georg Brandl <georg@python.org>
date Tue, 14 Jun 2011 21:09:55 +0200
parents 1f7297534424
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
70594
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
1 ==================
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
2 Packaging tutorial
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
3 ==================
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
4
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
5 Welcome to the Packaging tutorial! We will learn how to use Packaging
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
6 to package your project.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
7
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
8 .. TODO merge with introduction.rst
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
9
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
10
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
11 Getting started
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
12 ---------------
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
13
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
14 Packaging works with the *setup.cfg* file. It contains all the metadata for
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
15 your project, as defined in PEP 345, but also declare what your project
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
16 contains.
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
17
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
18 Let's say you have a project called *CLVault* containing one package called
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
19 *clvault*, and a few scripts inside. You can use the *pysetup* script to create
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
20 a *setup.cfg* file for the project. The script will ask you a few questions::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
21
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
22 $ mkdir CLVault
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
23 $ cd CLVault
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
24 $ pysetup create
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
25 Project name [CLVault]:
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
26 Current version number: 0.1
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
27 Package description:
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
28 >Command-line utility to store and retrieve passwords
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
29 Author name: Tarek Ziade
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
30 Author e-mail address: tarek@ziade.org
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
31 Project Home Page: http://bitbucket.org/tarek/clvault
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
32 Do you want to add a package ? (y/n): y
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
33 Package name: clvault
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
34 Do you want to add a package ? (y/n): n
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
35 Do you want to set Trove classifiers? (y/n): y
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
36 Please select the project status:
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
37
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
38 1 - Planning
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
39 2 - Pre-Alpha
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
40 3 - Alpha
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
41 4 - Beta
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
42 5 - Production/Stable
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
43 6 - Mature
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
44 7 - Inactive
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
45
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
46 Status: 3
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
47 What license do you use: GPL
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
48 Matching licenses:
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
49
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
50 1) License :: OSI Approved :: GNU General Public License (GPL)
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
51 2) License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
52
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
53 Type the number of the license you wish to use or ? to try again:: 1
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
54 Do you want to set other trove identifiers (y/n) [n]: n
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
55 Wrote "setup.cfg".
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
56
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
57
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
58 A setup.cfg file is created, containing the metadata of your project and the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
59 list of the packages it contains::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
60
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
61 $ cat setup.cfg
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
62 [metadata]
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
63 name = CLVault
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
64 version = 0.1
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
65 author = Tarek Ziade
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
66 author_email = tarek@ziade.org
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
67 description = Command-line utility to store and retrieve passwords
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
68 home_page = http://bitbucket.org/tarek/clvault
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
69
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
70 classifier = Development Status :: 3 - Alpha
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
71 License :: OSI Approved :: GNU General Public License (GPL)
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
72
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
73 [files]
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
74 packages = clvault
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
75
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
76
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
77 Our project will depend on the *keyring* project. Let's add it in the
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
78 [metadata] section::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
79
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
80 [metadata]
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
81 ...
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
82 requires_dist =
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
83 keyring
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
84
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
85
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
86 Running commands
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
87 ----------------
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
88
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
89 You can run useful commands on your project once the setup.cfg file is ready:
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
90
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
91 - sdist: creates a source distribution
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
92 - register: register your project to PyPI
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
93 - upload: upload the distribution to PyPI
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
94 - install_dist: install it
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
95
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
96 All commands are run using the run script::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
97
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
98 $ pysetup run install_dist
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
99 $ pysetup run sdist
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
100 $ pysetup run upload
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
101
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
102 If you want to push a source distribution of your project to PyPI, do::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
103
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
104 $ pysetup run sdist register upload
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
105
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
106
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
107 Installing the project
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
108 ----------------------
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
109
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
110 The project can be installed by manually running the packaging install command::
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
111
1f7297534424 Add documentation for the packaging module.
Éric Araujo <merwok@netwok.org>
parents:
diff changeset
112 $ pysetup run install_dist