1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
|
Debian Python Policy
--------------------
Neil Schemenauer <nas@debian.org>
Matthias Klose <doko@debian.org>
Gregor Hoffleit <flight@debian.org>
version 0.3.7
-------------------------------------------------------------------------------
Abstract
--------
This document describes the packaging of Python within the Debian
GNU/Linux distribution and the policy requirements for packaged Python
programs and modules.
Copyright Notice
----------------
Copyright (C) 1999, 2001 Software in the Public Interest
This manual is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
This is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
A copy of the GNU General Public License is available as
`/usr/share/common-licences/GPL' in the Debian GNU/Linux distribution
or on the World Wide Web at The GNU Public Licence
(http://www.gnu.org/copyleft/gpl.html).
You can also obtain it by writing to the Free Software Foundation,
Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-------------------------------------------------------------------------------
Contents
--------
1. Python Packaging
1.1. Versions
1.2. Main package
1.3. Python Interpreter
1.3.1. Interpreter Name
1.3.2. Interpreter Location
1.4. Module Path
1.5. Documentation
2. Packaged Modules
2.1. Rationale: A different view
2.2. Packaging Variants
2.2.1. Support Only The Default Version
2.2.2. Support a Particular Version(s)
2.2.3. Support All/Most Versions (Including Default)
2.3. Module Package Names
2.4. Dependencies
3. Python Programs
3.1. Version Independent Programs
3.2. Version Dependent Programs
4. Programs Embedding Python
4.1. Building Embedded Programs
4.2. Embedded Python Dependencies
5. Interaction with Locally Installed Python Versions
A. Build Dependencies
B. Upgrade Procedure
-------------------------------------------------------------------------------
1. Python Packaging
-------------------
1.1. Versions
-------------
At any given time, the package `python' will represent the current
default Debian Python version.
The default Debian Python version should alway be the latest stable
upstream release that can be integrated in the distribution.
Apart from the default version, legacy versions of Python may be
included as well in the distribution, as long as they are needed by
other packages, or as long as it seems reasonable to provide them.
(Note: For the scope of this document, Python versions are synonymous
to feature releases, i.e. Python 2.0 and 2.0.1 are subminor versions
of the same Python version 2.0, but Python 2.1 and 2.2 are indeed
different versions.)
For any version, the main package must be called `python<X>.<Y>'.
Names of related packages must include the `python<X>.<Y>' part.
1.2. Main package
-----------------
For every Python version provided in the distribution, the package
`python<X>.<Y>' shall comprise a complete distribution for
_deployment_ of Python scripts and applications. The package includes
the binary `/usr/bin/python<X>.<Y>' and all modules of the upstream
Python distribution.
Excluded are any modules that depend on non-_required_ packages, they
will be provided in separate packages. Some tools and files for the
_development_ of Python modules are split off in a separate package
`python<X>.<Y>-dev'. Documentation will be provided separately as
well.
At any time, exactly one package must contain a binary
`/usr/bin/python'. That package must either be `python' or a
dependency of that package.
1.3. Python Interpreter
-----------------------
1.3.1. Interpreter Name
-----------------------
Python scripts depending on the default Python version (see Section
1.2, `Main package') or not depending on a specific Python version
should use `python' (unversioned) as the interpreter name.
Python scripts that only work with a specific Python version must
explicitely use the versioned interpreter name (`python<X>.<Y>').
1.3.2. Interpreter Location
---------------------------
The preferred specification for the Python interpreter is
`/usr/bin/python' or `/usr/bin/python<X>.<Y>'.
If a maintainer would like to provide the user with the possibility to
override the Debian Python interpreter, he may want to use
`/usr/bin/env python' or `/usr/bin/env pythonX.Y'.
1.4. Module Path
----------------
The module search path for Debian has been amended to include a
directory tree in /usr/local at the beginning of the path. By
default, sys.path is searched in the following order:
/usr/local/lib/python<X>.<Y>/site-packages
/usr/local/lib/site-python
/usr/lib/python<X>.<Y>/site-packages
/usr/lib/site-python
Note that the use of the site-python directories in Python is
depreciated. The directories might be dropped from the path in a
future version.
TODO: What about `/usr/share/python<X>.<Y>' ?
1.5. Documentation
------------------
Python documentation is split out in separate packages
`python<X>.<Y>-doc'. The package `python-doc' will always provide the
documentation for the default Debian Python version.
TODO: Policy for documentation of third party packages.
-------------------------------------------------------------------------------
2. Packaged Modules
-------------------
2.1. Rationale: A different view
--------------------------------
A package with a name `python-<foo>' will always provide the module
<foo> for the default Debian Python version of the distribution. I.e.
the package will extend the function of `/usr/bin/python' (which is
installed by the package `python').
The system of dependencies of the default packages is robust against
upgrades, but introduces a strong dependency: I.e. an upgrade of the
`python' package will be hold back as long as there are still default
modules packages left over on the system that can't be upgraded to the
new version.
The versioned packages (legacy versions) ensure that an upgrade to a
new default version can take place before without upgrading *all*
packages with dependencies on Python.
2.2. Packaging Variants
-----------------------
There is more than one way to package a Python module:
1. Support only the default Python version.
2. Support a particular version, or some but not all versions of
Python available in Debian.
3. Support all/most versions of python, including the default.
Works only for architecture independant python modules.
2.2.1. Support Only The Default Version
---------------------------------------
Name your package `python-<foo>'. This kind of package is called a
_default module package_. Install your modules into
`/usr/lib/python<X>.<Y>/site-packages/'. Make your package dependency
look like
Depends: python (>= X.Y), python (<< X.Y+1)
Note that this kind of packaging means that your package will trigger
a conflict when the default Debian Python version in the distribution
is changed, and that you will have to provide a new version as soon as
possible, since the package will block the upgrade of `python'.
You should not make a default, unversioned module package
`python-<foo>' depend on the versioned Python package `python<X>.<Y>'!
The source package must declare
Build-Depends: pythonX.Y-dev
where <X>.<Y> is the version used in the `Depends'.
TODO: Should a `python-foo' provide `python-foo<X>.<Y>', provided that
the Debian policy allows us to create such a mass of virtual packages?
2.2.2. Support a Particular Version(s)
--------------------------------------
Name your package `python<X>.<Y>-<foo>' (a _versioned module
package_). Make the dependency look like
Depends: python<X>.<Y>
It should install modules somewhere inside
`/usr/lib/python<X>.<Y>/site-packages/'. Any programs included should
use `#!/usr/bin/pythonX.Y'.
The packaged source must declare
Build-Depends: pythonX.Y-dev
where <X>.<Y> is the version used above.
TODO: Describe support for multiple particular versions
2.2.3. Support All/Most Versions (Including Default)
----------------------------------------------------
This option is only XXX available for architecture dependent and
independent packages. There are two different cases:
1. Multiple versioned packages
You have binary extensions that must be compiled against
particular versions of Python. Create multiple
`python<X>.<Y>-<foo>' packages as in Section 2.2.2, `Support a
Particular Version(s)'. Also create an empty default package
`python-<foo>' with
Depends: python (>= X.Y), python (<< X.Y+1), pythonX.Y-foo
Note that this kind of packaging means that the default package
will trigger a conflict when the default Debian Python version in
the distribution is changed, and that you will have to provide a
new version of your package as soon as possible, since the
package will block the upgrade of `python'.
The packaged sources `Build-Depends' must contain all
`python<X>.<Y>-dev' packages that the module is built for.
2. A single package for all versions (NOT YET SUPPORTED!)
You have a version independent Python module. Create a single
package `python-<foo>' that has a dependency
Depends: python
It should install modules somewhere inside
`/usr/lib/python/site-packages/' and use `#!/usr/bin/python' for
programs. The `postinst' script should create symlinks in all
`/usr/lib/pythonX.Y/site-packages/' directories that point to its
`/usr/lib/python/site-packages/' files and compile them.
NOT YET SUPPORTED: It's errorprone if the package itself supplies
these scripts. And the package cannot know when a new upstream
Python version is installed. So the `python<X>.<Y>' must provide
these scripts, which is not yet done.
The packaged source must declare `Build-Depends' on one
`python<X>.<Y>-dev' package. XXX: Or build-depend on each Python
version, so that only checked modules are uploaded?
TODO: Should policy demand that these packages must have a
dependency on `python (<= <X>.<Y+1>')?
DO WE WANT THIS: Some packages, which provide binary Python only,
package these modules together in one package (like
`python-pqueue'). They build-depend on all used
`python<X>.<Y>-dev' packages, and depend on the presence of at
least one of the used Python versions installed, e.g.
Depends: python1.5 | python2.1
Also, such a package should declare `Provides' for
`python<X>.<Y>-<foo>' for all versions provided by the package.
2.3. Module Package Names
-------------------------
Python module packages should be named for the primary module
provided. The naming convention for a module `foo' is `python-<foo>'
for the package for the default Python version (the _default module
package_). (Packages which include multiple modules may additionally
include provides for those modules using the same convention.)
Python module packages packaged for one particular version of Python
(_versioned modules packages_) should be named `python<X>.<Y>-foo'.
2.4. Dependencies
-----------------
Packaged modules available for the default Python version as described
in in Section 2.2.1, `Support Only The Default Version' must depend on
"`python (>= <X>.<Y>)', `python (<< <X>.<Y+1>)'".
Packaged modules available for one particular version of Python must
depend on the corresponding `python<X>.<Y>' package instead.
-------------------------------------------------------------------------------
3. Python Programs
------------------
3.1. Version Independent Programs
---------------------------------
Programs that can run with any version of Python should be started
with `#!/usr/bin/python'. They must also specify a dependency on
`python'. You're free to use `#!/usr/bin/env python', if you'd like
to give the user a chance to override the Debian Python package with a
local version.
3.2. Version Dependent Programs
-------------------------------
Programs which require a specific version of Python must start with
`#!/usr/bin/python<X>.<Y>'. They must also specify a dependency on
`python<X>.<Y>'. Again, if you're using `#!/usr/bin/env
python<X>.<Y>', please be aware that a user might override the Debian
Python package with a local version.
-------------------------------------------------------------------------------
4. Programs Embedding Python
----------------------------
4.1. Building Embedded Programs
-------------------------------
Programs which embed a Python interpreter must declare a
`Build-Depends' on `python<X>.<Y>-dev'.
TODO: Be more verbose. How about versions...
4.2. Embedded Python Dependencies
---------------------------------
Dependencies for programs linking against the shared Python library
will be automatically created by `dpkg-shlibdeps'.
-------------------------------------------------------------------------------
5. Interaction with Locally Installed Python Versions
-----------------------------------------------------
As long as you don't install other versions of Python in your path,
Debian's Python versions won't be affected by a new version.
If you install a different subrelease of the version of python you've
got installed, you'll need to be careful to install all the modules
you use for that version of python too.
-------------------------------------------------------------------------------
A. Build Dependencies
---------------------
Build dependencies for Python dependent packages must be declared for
every Python version, that the package is built for. To build for a
specific version, add the versioned dependencies, to build for the
default version, add the unversioned dependency. Architecture
dependent packages must depend on the `-dev' package; for architecture
independent packages, it may be sufficient to depend on the `python'
or `python<X>.<Y>' package.
Build-Depend on at least:
Build-Depends: python1.5
Build-Depends: python2 (>= 2.0.1-1.2)
Build-Depends: python2.1
Build-Depends: python2.2 (>= 2.1.99-2)
Build-Depends: python1.5-dev (>= 1.5.2-18.6)
Build-Depends: python1.5-distutils
Build-Depends: python2-dev (>= 2.0.1-1.2)
Build-Depends: python2.1-dev (>= 2.1.1-1.4)
Build-Depends: python2.2-dev (>= 2.1.99-2)
-------------------------------------------------------------------------------
B. Upgrade Procedure
--------------------
This section describes the procedure for the upgrade from the current
`python-<XXX> (1.5)' packages to the `python1.5-<XXX>' packages, the
removal of the `python2-<XXX>' packages and the upgrade to the recent
`python2.1-<XXX>' packages:
1. The Debian Python maintainer decides for the default Debian
Python version. In the following we assume that `python2.1' will
be the default (hint, hint ...).
Serious issues with the python-policy should be resolved, the
policy should be submitted to debian-policy.
2. Upload python core packages `python-<module> (2.1)' & Co
depending on `python2.1-<module>'.
The new packages will conflict with every Python dependent
package, that does depend on `python', `python-base', without
depending on `python (<< 1.6)' or `python-base (<< 2.1)'.
3. At this point other python modules/packages can be made, which
follow the proposed policy. Notify the maintainers of packages,
that the new packages conflict with.
We propose to make more than one source package for support of
more than one python version. Build 2.1 (and probably 2.2)
dependent packages from one source packages, and 1.5 and 2.0
packages from another source package (if you support these
versions at all). This makes it easy to remove the old packages
from testing/unstable.
XXX Do we allow NMUs which only fix the dependencies?
4. File bug report against packages and/or make NMU's for packages
that are not adapted by their maintainer.
5. If maintainer A (maintaining `python-foo' (depending on `python
(>= 2.1)', `python (<< 2.2))' decides for Section 2.2.1, `Support
Only The Default Version', then a maintainer B should be allowed
to repackage `python1.5-foo', if "his" package cannot be
converted to use the default Python version.
6. File reports that `python2.0' should go away, file serious
reports against all the `python2-*' the packages and
`ftp.debian.org'.
7. Hopefully release woody with `python2.1' as the default Python
version.
-------------------------------------------------------------------------------
Debian Python Policy
Neil Schemenauer <nas@debian.org>
Matthias Klose <doko@debian.org>
Gregor Hoffleit <flight@debian.org>
version 0.3.7
|
