# Hookspy

## Fine-Grained Hook Generation

This is usually unnecessary for agent development. Only use these instructions if you're sure you know what you're doing. See the DEV_README if you just need to regenerate all hooks.

The `hookspy-autogen` command is used to automatically generate C source files
that implement the hooks that are required for string tracking.  In Python 3,
there are three string types that we need to hook: `unicode` (i.e. `str`),
`bytes`, and `bytearray`. To generate hooks for the `unicode` type, we run the
following command:

```bash
hookspy-autogen unicode > unicode.c
```

Similarly, we can run the same command with a different argument for `bytes`
and `bytearray`:

```bash
hookspy-autogen bytes > bytes.c
hookspy-autogen bytearray > bytearray.c
```

As a convenience, the script `generate_hooks.sh` is provided for generating the
hooks for the active version of Python.

Each minor version update to Python requires new hooks to be generated. The
`hookspy` tool must be rebuilt and installed for each version of Python that is
to be supported. The best way to manage this is using virtual environments.
Generated source files should be stored and committed to version-specific
subdirectores:

```bash
hookspy-autogen unicode > src/contrast/assess_extensions/py312/unicode.c
```

The code generated by `hookspy` makes reference to types, functions, and macros
defined in headers in `src/contrast/assess_extensions/include`. Any substantial
modification to any of these definitions will require updates to `hookspy` as
well.
