Custom Part Handler

This must be Python code that contains a list_types function and a handle_part function.

The list_types function takes no arguments and must return a list of content types that this part handler handles. These can include custom content types or built-in content types that this handler will override.

The handle_part function takes 4 arguments and returns nothing. See the example for how exactly each argument is used.

To use this part handler, it must be included in a MIME multipart file as part of the user data. Since MIME parts are processed in order, a part handler part must precede any parts with mime-types that it is expected to handle in the same user data.

Cloud-init will then call the handle_part function once before it handles any parts, once per part received, and once after all parts have been handled. These additional calls allow for initialisation or teardown before or after receiving any parts.

Example

#part-handler

"""This is a trivial example part-handler that creates a file with the path
specified in the payload. It performs no input checking or error handling.

To use it, first save the file you are currently viewing into your current
working directory. Then run the following:
```
$ echo '/var/tmp/my_path' > part
$ cloud-init devel make-mime -a part-handler.py:part-handler -a part:x-my-path --force > user-data
```

This will create a mime file with the contents of 'part' and the
part-handler. You can now pass 'user-data' to your cloud of choice.

When run, cloud-init will have created an empty file at /var/tmp/my_path.
"""

import pathlib
from typing import Any

from cloudinit.cloud import Cloud


def list_types():
    """Return a list of mime-types that are handled by this module."""
    return ["text/x-my-path"]


def handle_part(data: Cloud, ctype: str, filename: str, payload: Any):
    """Handle a part with the given mime-type.

    This function will get called multiple times. The first time is
    to allow any initial setup needed to handle parts. It will then get
    called once for each part matching the mime-type returned by `list_types`.
    Finally, it will get called one last time to allow for any final
    teardown.

    :data: A `Cloud` instance. This will be the same instance for each call
        to handle_part.
    :ctype: '__begin__', '__end__', or the mime-type
        (for this example 'text/x-my-path') of the part
    :filename: The filename for the part as defined in the MIME archive,
        or dynamically generated part if no filename is given
    :payload: The content of the part. This will be
        `None` when `ctype` is '__begin__' or '__end__'.
    """
    if ctype == "__begin__":
        # Any custom setup needed before handling payloads
        return

    if ctype == "__end__":
        # Any custom teardown needed after handling payloads can happen here
        return

    # If we've made it here, we're dealing with a real payload, so handle
    # it appropriately
    pathlib.Path(payload.strip()).touch()