← Back to branch summary

~dkuhlman/python-training-materials/Materials

« back to all changes in this revision

Viewing changes to python-2.7.11-docs-html/_sources/distutils/examples.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-2.7.11-docs-html/_sources/distutils/examples.txt
1
 
.. _examples:
2
 
 
3
 
********
4
 
Examples
5
 
********
6
 
 
7
 
This chapter provides a number of basic examples to help get started with
8
 
distutils.  Additional information about using distutils can be found in the
9
 
Distutils Cookbook.
10
 
 
11
 
 
12
 
.. seealso::
13
 
 
14
 
   `Distutils Cookbook <https://wiki.python.org/moin/Distutils/Cookbook>`_
15
 
      Collection of recipes showing how to achieve more control over distutils.
16
 
 
17
 
 
18
 
.. _pure-mod:
19
 
 
20
 
Pure Python distribution (by module)
21
 
====================================
22
 
 
23
 
If you're just distributing a couple of modules, especially if they don't live
24
 
in a particular package, you can specify them individually using the
25
 
``py_modules`` option in the setup script.
26
 
 
27
 
In the simplest case, you'll have two files to worry about: a setup script and
28
 
the single module you're distributing, :file:`foo.py` in this example::
29
 
 
30
 
   <root>/
31
 
           setup.py
32
 
           foo.py
33
 
 
34
 
(In all diagrams in this section, *<root>* will refer to the distribution root
35
 
directory.)  A minimal setup script to describe this situation would be::
36
 
 
37
 
   from distutils.core import setup
38
 
   setup(name='foo',
39
 
         version='1.0',
40
 
         py_modules=['foo'],
41
 
         )
42
 
 
43
 
Note that the name of the distribution is specified independently with the
44
 
``name`` option, and there's no rule that says it has to be the same as
45
 
the name of the sole module in the distribution (although that's probably a good
46
 
convention to follow).  However, the distribution name is used to generate
47
 
filenames, so you should stick to letters, digits, underscores, and hyphens.
48
 
 
49
 
Since ``py_modules`` is a list, you can of course specify multiple
50
 
modules, eg. if you're distributing modules :mod:`foo` and :mod:`bar`, your
51
 
setup might look like this::
52
 
 
53
 
   <root>/
54
 
           setup.py
55
 
           foo.py
56
 
           bar.py
57
 
 
58
 
and the setup script might be  ::
59
 
 
60
 
   from distutils.core import setup
61
 
   setup(name='foobar',
62
 
         version='1.0',
63
 
         py_modules=['foo', 'bar'],
64
 
         )
65
 
 
66
 
You can put module source files into another directory, but if you have enough
67
 
modules to do that, it's probably easier to specify modules by package rather
68
 
than listing them individually.
69
 
 
70
 
 
71
 
.. _pure-pkg:
72
 
 
73
 
Pure Python distribution (by package)
74
 
=====================================
75
 
 
76
 
If you have more than a couple of modules to distribute, especially if they are
77
 
in multiple packages, it's probably easier to specify whole packages rather than
78
 
individual modules.  This works even if your modules are not in a package; you
79
 
can just tell the Distutils to process modules from the root package, and that
80
 
works the same as any other package (except that you don't have to have an
81
 
:file:`__init__.py` file).
82
 
 
83
 
The setup script from the last example could also be written as  ::
84
 
 
85
 
   from distutils.core import setup
86
 
   setup(name='foobar',
87
 
         version='1.0',
88
 
         packages=[''],
89
 
         )
90
 
 
91
 
(The empty string stands for the root package.)
92
 
 
93
 
If those two files are moved into a subdirectory, but remain in the root
94
 
package, e.g.::
95
 
 
96
 
   <root>/
97
 
           setup.py
98
 
           src/      foo.py
99
 
                     bar.py
100
 
 
101
 
then you would still specify the root package, but you have to tell the
102
 
Distutils where source files in the root package live::
103
 
 
104
 
   from distutils.core import setup
105
 
   setup(name='foobar',
106
 
         version='1.0',
107
 
         package_dir={'': 'src'},
108
 
         packages=[''],
109
 
         )
110
 
 
111
 
More typically, though, you will want to distribute multiple modules in the same
112
 
package (or in sub-packages).  For example, if the :mod:`foo`  and :mod:`bar`
113
 
modules belong in package :mod:`foobar`, one way to layout your source tree is
114
 
::
115
 
 
116
 
   <root>/
117
 
           setup.py
118
 
           foobar/
119
 
                    __init__.py
120
 
                    foo.py
121
 
                    bar.py
122
 
 
123
 
This is in fact the default layout expected by the Distutils, and the one that
124
 
requires the least work to describe in your setup script::
125
 
 
126
 
   from distutils.core import setup
127
 
   setup(name='foobar',
128
 
         version='1.0',
129
 
         packages=['foobar'],
130
 
         )
131
 
 
132
 
If you want to put modules in directories not named for their package, then you
133
 
need to use the ``package_dir`` option again.  For example, if the
134
 
:file:`src` directory holds modules in the :mod:`foobar` package::
135
 
 
136
 
   <root>/
137
 
           setup.py
138
 
           src/
139
 
                    __init__.py
140
 
                    foo.py
141
 
                    bar.py
142
 
 
143
 
an appropriate setup script would be  ::
144
 
 
145
 
   from distutils.core import setup
146
 
   setup(name='foobar',
147
 
         version='1.0',
148
 
         package_dir={'foobar': 'src'},
149
 
         packages=['foobar'],
150
 
         )
151
 
 
152
 
Or, you might put modules from your main package right in the distribution
153
 
root::
154
 
 
155
 
   <root>/
156
 
           setup.py
157
 
           __init__.py
158
 
           foo.py
159
 
           bar.py
160
 
 
161
 
in which case your setup script would be  ::
162
 
 
163
 
   from distutils.core import setup
164
 
   setup(name='foobar',
165
 
         version='1.0',
166
 
         package_dir={'foobar': ''},
167
 
         packages=['foobar'],
168
 
         )
169
 
 
170
 
(The empty string also stands for the current directory.)
171
 
 
172
 
If you have sub-packages, they must be explicitly listed in ``packages``,
173
 
but any entries in ``package_dir`` automatically extend to sub-packages.
174
 
(In other words, the Distutils does *not* scan your source tree, trying to
175
 
figure out which directories correspond to Python packages by looking for
176
 
:file:`__init__.py` files.)  Thus, if the default layout grows a sub-package::
177
 
 
178
 
   <root>/
179
 
           setup.py
180
 
           foobar/
181
 
                    __init__.py
182
 
                    foo.py
183
 
                    bar.py
184
 
                    subfoo/
185
 
                              __init__.py
186
 
                              blah.py
187
 
 
188
 
then the corresponding setup script would be  ::
189
 
 
190
 
   from distutils.core import setup
191
 
   setup(name='foobar',
192
 
         version='1.0',
193
 
         packages=['foobar', 'foobar.subfoo'],
194
 
         )
195
 
 
196
 
 
197
 
.. _single-ext:
198
 
 
199
 
Single extension module
200
 
=======================
201
 
 
202
 
Extension modules are specified using the ``ext_modules`` option.
203
 
``package_dir`` has no effect on where extension source files are found;
204
 
it only affects the source for pure Python modules.  The simplest  case, a
205
 
single extension module in a single C source file, is::
206
 
 
207
 
   <root>/
208
 
           setup.py
209
 
           foo.c
210
 
 
211
 
If the :mod:`foo` extension belongs in the root package, the setup script for
212
 
this could be  ::
213
 
 
214
 
   from distutils.core import setup
215
 
   from distutils.extension import Extension
216
 
   setup(name='foobar',
217
 
         version='1.0',
218
 
         ext_modules=[Extension('foo', ['foo.c'])],
219
 
         )
220
 
 
221
 
If the extension actually belongs in a package, say :mod:`foopkg`, then
222
 
 
223
 
With exactly the same source tree layout, this extension can be put in the
224
 
:mod:`foopkg` package simply by changing the name of the extension::
225
 
 
226
 
   from distutils.core import setup
227
 
   from distutils.extension import Extension
228
 
   setup(name='foobar',
229
 
         version='1.0',
230
 
         ext_modules=[Extension('foopkg.foo', ['foo.c'])],
231
 
         )
232
 
 
233
 
.. % \section{Multiple extension modules}
234
 
.. % \label{multiple-ext}
235
 
 
236
 
.. % \section{Putting it all together}
237
 
 
238