Éric Araujo | 823759e | 2011-06-04 18:46:25 +0200 | [diff] [blame] | 1 | .. TODO integrate this in commandref and configfile |
| 2 | |
Éric Araujo | 54bb1e6 | 2011-06-19 21:34:16 +0200 | [diff] [blame] | 3 | .. _packaging-command-hooks: |
| 4 | |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 5 | ============= |
| 6 | Command hooks |
| 7 | ============= |
| 8 | |
| 9 | Packaging provides a way of extending its commands by the use of pre- and |
Éric Araujo | 54bb1e6 | 2011-06-19 21:34:16 +0200 | [diff] [blame] | 10 | post-command hooks. Hooks are Python functions (or any callable object) that |
| 11 | take a command object as argument. They're specified in :ref:`config files |
| 12 | <packaging-config-filenames>` using their fully qualified names. After a |
| 13 | command is finalized (its options are processed), the pre-command hooks are |
| 14 | executed, then the command itself is run, and finally the post-command hooks are |
| 15 | executed. |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 16 | |
Éric Araujo | 0300b5c | 2011-06-06 01:54:54 +0200 | [diff] [blame] | 17 | See also global setup hooks in :ref:`setupcfg-spec`. |
Éric Araujo | 823759e | 2011-06-04 18:46:25 +0200 | [diff] [blame] | 18 | |
| 19 | |
Éric Araujo | 54bb1e6 | 2011-06-19 21:34:16 +0200 | [diff] [blame] | 20 | .. _packaging-finding-hooks: |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 21 | |
Éric Araujo | 54bb1e6 | 2011-06-19 21:34:16 +0200 | [diff] [blame] | 22 | Finding hooks |
| 23 | ============= |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 24 | |
Éric Araujo | 54bb1e6 | 2011-06-19 21:34:16 +0200 | [diff] [blame] | 25 | As a hook is configured with a Python dotted name, it must either be defined in |
| 26 | a module installed on the system, or in a module present in the project |
| 27 | directory, where the :file:`setup.cfg` file lives:: |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 28 | |
Éric Araujo | 54bb1e6 | 2011-06-19 21:34:16 +0200 | [diff] [blame] | 29 | # file: _setuphooks.py |
| 30 | |
| 31 | def hook(install_cmd): |
| 32 | metadata = install_cmd.dist.metadata |
| 33 | print('Hooked while installing %r %s!' % (metadata['Name'], |
| 34 | metadata['Version'])) |
| 35 | |
| 36 | Then you need to configure it in :file:`setup.cfg`:: |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 37 | |
| 38 | [install_dist] |
Éric Araujo | 54bb1e6 | 2011-06-19 21:34:16 +0200 | [diff] [blame] | 39 | pre-hook.a = _setuphooks.hook |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 40 | |
Éric Araujo | 54bb1e6 | 2011-06-19 21:34:16 +0200 | [diff] [blame] | 41 | Packaging will add the project directory to :data:`sys.path` and find the |
| 42 | ``_setuphooks`` module. |
| 43 | |
| 44 | Hooks defined in different config files (system-wide, user-wide and |
| 45 | project-wide) do not override each other as long as they are specified with |
| 46 | different aliases (additional names after the dot). The alias in the example |
| 47 | above is ``a``. |