Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Improve documentation of packaging hooks

This commit is contained in:
Éric Araujo 2011-06-19 21:34:16 +02:00
parent 3e425ac64b
commit 54bb1e6aaf
2 changed files with 36 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
Doc/packaging/commandhooks.rst
View File

@ -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:
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 ::
Finding hooks
=============
# file: myhooks.py
def my_install_hook(install_cmd):
print "Oh la la! Someone is installing my project!"
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::
Then, you need to point to it in your `setup.cfg` file, under the appropriate
command section ::
# file: _setuphooks.py
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
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``.
Packaging will add the project directory to :data:`sys.path` and find the
``_setuphooks`` module.
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``.

9
Doc/packaging/setupcfg.rst
View File

@ -178,17 +178,20 @@ compilers
setup_hooks
Defines a list of callables to be called right after the :file:`setup.cfg`
file is read, before any other processing. The callables are executed in the
file is read, before any other processing. Each value is a Python dotted
name to an object, which has to be defined in a module present in the project
directory alonside :file:`setup.cfg` or on Python's :data:`sys.path` (see
:ref:`packaging-finding-hooks`). The callables are executed in the
order they're found in the file; if one of them cannot be found, tools should
not stop, but for example produce a warning and continue with the next line.
Each callable receives the configuration as a dictionary (keys are
:file:`setup.cfg` sections, values are dictionaries of fields) and can make
any changes to it. *optional*, *multi*
any change to it. *optional*, *multi*
Example::
[global]
setup_hooks = package.setup.customize_dist
setup_hooks = _setuphooks.customize_config
Metadata