|
1 .. _extending-distutils: |
|
2 |
|
3 ******************* |
|
4 Extending Distutils |
|
5 ******************* |
|
6 |
|
7 Distutils can be extended in various ways. Most extensions take the form of new |
|
8 commands or replacements for existing commands. New commands may be written to |
|
9 support new types of platform-specific packaging, for example, while |
|
10 replacements for existing commands may be made to modify details of how the |
|
11 command operates on a package. |
|
12 |
|
13 Most extensions of the distutils are made within :file:`setup.py` scripts that |
|
14 want to modify existing commands; many simply add a few file extensions that |
|
15 should be copied into packages in addition to :file:`.py` files as a |
|
16 convenience. |
|
17 |
|
18 Most distutils command implementations are subclasses of the :class:`Command` |
|
19 class from :mod:`distutils.cmd`. New commands may directly inherit from |
|
20 :class:`Command`, while replacements often derive from :class:`Command` |
|
21 indirectly, directly subclassing the command they are replacing. Commands are |
|
22 required to derive from :class:`Command`. |
|
23 |
|
24 .. % \section{Extending existing commands} |
|
25 .. % \label{extend-existing} |
|
26 |
|
27 .. % \section{Writing new commands} |
|
28 .. % \label{new-commands} |
|
29 .. % \XXX{Would an uninstall command be a good example here?} |
|
30 |
|
31 |
|
32 Integrating new commands |
|
33 ======================== |
|
34 |
|
35 There are different ways to integrate new command implementations into |
|
36 distutils. The most difficult is to lobby for the inclusion of the new features |
|
37 in distutils itself, and wait for (and require) a version of Python that |
|
38 provides that support. This is really hard for many reasons. |
|
39 |
|
40 The most common, and possibly the most reasonable for most needs, is to include |
|
41 the new implementations with your :file:`setup.py` script, and cause the |
|
42 :func:`distutils.core.setup` function use them:: |
|
43 |
|
44 from distutils.command.build_py import build_py as _build_py |
|
45 from distutils.core import setup |
|
46 |
|
47 class build_py(_build_py): |
|
48 """Specialized Python source builder.""" |
|
49 |
|
50 # implement whatever needs to be different... |
|
51 |
|
52 setup(cmdclass={'build_py': build_py}, |
|
53 ...) |
|
54 |
|
55 This approach is most valuable if the new implementations must be used to use a |
|
56 particular package, as everyone interested in the package will need to have the |
|
57 new command implementation. |
|
58 |
|
59 Beginning with Python 2.4, a third option is available, intended to allow new |
|
60 commands to be added which can support existing :file:`setup.py` scripts without |
|
61 requiring modifications to the Python installation. This is expected to allow |
|
62 third-party extensions to provide support for additional packaging systems, but |
|
63 the commands can be used for anything distutils commands can be used for. A new |
|
64 configuration option, :option:`command_packages` (command-line option |
|
65 :option:`--command-packages`), can be used to specify additional packages to be |
|
66 searched for modules implementing commands. Like all distutils options, this |
|
67 can be specified on the command line or in a configuration file. This option |
|
68 can only be set in the ``[global]`` section of a configuration file, or before |
|
69 any commands on the command line. If set in a configuration file, it can be |
|
70 overridden from the command line; setting it to an empty string on the command |
|
71 line causes the default to be used. This should never be set in a configuration |
|
72 file provided with a package. |
|
73 |
|
74 This new option can be used to add any number of packages to the list of |
|
75 packages searched for command implementations; multiple package names should be |
|
76 separated by commas. When not specified, the search is only performed in the |
|
77 :mod:`distutils.command` package. When :file:`setup.py` is run with the option |
|
78 :option:`--command-packages` :option:`distcmds,buildcmds`, however, the packages |
|
79 :mod:`distutils.command`, :mod:`distcmds`, and :mod:`buildcmds` will be searched |
|
80 in that order. New commands are expected to be implemented in modules of the |
|
81 same name as the command by classes sharing the same name. Given the example |
|
82 command line option above, the command :command:`bdist_openpkg` could be |
|
83 implemented by the class :class:`distcmds.bdist_openpkg.bdist_openpkg` or |
|
84 :class:`buildcmds.bdist_openpkg.bdist_openpkg`. |
|
85 |
|
86 |
|
87 Adding new distribution types |
|
88 ============================= |
|
89 |
|
90 Commands that create distributions (files in the :file:`dist/` directory) need |
|
91 to add ``(command, filename)`` pairs to ``self.distribution.dist_files`` so that |
|
92 :command:`upload` can upload it to PyPI. The *filename* in the pair contains no |
|
93 path information, only the name of the file itself. In dry-run mode, pairs |
|
94 should still be added to represent what would have been created. |
|
95 |
|
96 |