diff options
Diffstat (limited to 'Doc/packaging/commandhooks.rst')
| -rw-r--r-- | Doc/packaging/commandhooks.rst | 49 |
1 files changed, 30 insertions, 19 deletions
diff --git a/Doc/packaging/commandhooks.rst b/Doc/packaging/commandhooks.rst index 0a3d044..b261d00 100644 --- a/Doc/packaging/commandhooks.rst +++ b/Doc/packaging/commandhooks.rst @@ -1,36 +1,47 @@ .. TODO integrate this in commandref and configfile +.. _packaging-command-hooks: + ============= Command hooks ============= Packaging provides a way of extending its commands by the use of pre- and -post- command hooks. The hooks are simple Python functions (or any callable -objects) and are specified in the config file using their full qualified names. -The pre-hooks are run after the command is finalized (its options are -processed), but before it is run. The post-hooks are run after the command -itself. Both types of hooks receive an instance of the command object. +post-command hooks. Hooks are Python functions (or any callable object) that +take a command object as argument. They're specified in :ref:`config files +<packaging-config-filenames>` using their fully qualified names. After a +command is finalized (its options are processed), the pre-command hooks are +executed, then the command itself is run, and finally the post-command hooks are +executed. See also global setup hooks in :ref:`setupcfg-spec`. -Sample usage of hooks -===================== +.. _packaging-finding-hooks: + +Finding hooks +============= -Firstly, you need to make sure your hook is present in the path. This is usually -done by dropping them to the same folder where `setup.py` file lives :: +As a hook is configured with a Python dotted name, it must either be defined in +a module installed on the system, or in a module present in the project +directory, where the :file:`setup.cfg` file lives:: - # file: myhooks.py - def my_install_hook(install_cmd): - print "Oh la la! Someone is installing my project!" + # file: _setuphooks.py -Then, you need to point to it in your `setup.cfg` file, under the appropriate -command section :: + def hook(install_cmd): + metadata = install_cmd.dist.metadata + print('Hooked while installing %r %s!' % (metadata['Name'], + metadata['Version'])) + +Then you need to configure it in :file:`setup.cfg`:: [install_dist] - pre-hook.project = myhooks.my_install_hook + pre-hook.a = _setuphooks.hook + +Packaging will add the project directory to :data:`sys.path` and find the +``_setuphooks`` module. -The hooks defined in different config files (system-wide, user-wide and -package-wide) do not override each other as long as they are specified with -different aliases (additional names after the dot). The alias in the example -above is ``project``. +Hooks defined in different config files (system-wide, user-wide and +project-wide) do not override each other as long as they are specified with +different aliases (additional names after the dot). The alias in the example +above is ``a``. |