Installing Hooks

This guide will cover exactly how dput-ng handles hooks, and the proper way to install, distribute and tool with hooks. Remember, Hooks are your friend!

So, what exactly are hooks?

Well, it’s pretty simple, actually – a hook is a Python importable function that takes a few arguments, which are populated with internal dput-ng objects. These objects contain such things as a way to talk to the user, the processed .changes file, and the upload target.

Hooks can run either before or after an upload, and hooks that run before the upload may halt an upload by raising a dput.exceptions.HookException (or a subclass of that).

Alright, you mentioned Python-importable, what exactly does that mean?

The path given is a fully qualified path to the hook. Here’s an example:

>>> from os.path import abspath

The dput-ng style “fully qualified path” to that function (abspath) would be:

os.path.abspath

It’s really that simple.

Note

It’s also worth noting dput-ng adds a few directories to sys.path to aid with debugging and distributing trivial scripts. For each directory in dput.core.CONFIG_LOCATIONS, that directory plus “scripts” will be added to the system path, so (commonly) ~/.dput.d/scripts and /etc/dput.d/scripts are valid Python path roots to dput-ng.

OK, let’s do an example.

Let’s do a simple checker – one that fails out if Arno is the maintainer:

def check_for_arno(changes, profile, interface):
    """
    The ``arno`` checker will explode in a firey mess if
    Arno tries to upload anything to the archive.

    This checker doesn't change it's behavior given any Profile codes.
    """
    maintainer = changes['Maintainer']
    if "arno@debian.org" in maintainer:
        raise HookException("Arno's not allowed to Upload.")

I’ve saved this file to ~/.dput.d/scripts/arno.py. It should be noted that dput-ng can now import this file as arno, and the command (from inside dput-ng) from arno import check_for_arno will work.

Since we need to tell dput-ng about this hook, we need to drop it’s def into a dput hook directory. Let’s use our home directory again, even though it should be noted both /usr/share/dput-ng/ and /etc/dput.d/ will work as well.

I’ve placed arno.json into ~/.dput.d/hooks/arno.json:

{
    "description": "Blow up if Arno's maintaining this package.",
    "path": "arno.check_for_arno",
    "pre": true
}

The pre key, or the post key must be present and set to a boolean. If no key is given, it assumes it’s a pre checker. The path is the Python-importable path to the hook function, and description is for humans looking to get some information on the hook.

We can make sure it works using dirt(1):

$ dirt info --hook arno

    The ``arno`` checker will explode in a firey mess if Arno tries to upload
    anything to the archive.

    This checker doesn't change it's behavior given any Profile codes.

Remember, this pulls from the docstring, so please leave docstrings!

OK. Now that dput-ng is aware of the plugin, we can add it to a profile by adding a “plus-key” to your profile choice. Let’s add this to ftp-master, since we want to make sure Arno never uploads there.

Here’s my (user-local) ftp-master config ~/.dput.d/profiles/ftp-master.json:

{
    "+hooks": [
        "arno"
    ]
}

If you want to learn more about why this syntax works, I’d suggest checking out the Configuration File Overview documentation.

So, let’s try uploading:

$ dput [...]
[...]
running check-debs: makes sure the upload contains a binary package
running checksum: verify checksums before uploading
running suite-mismatch: check the target distribution for common errors
running arno: Blow up if Arno's maintaining this package.
Arno's not allowed to Upload.
$ echo $?
1

Nice!