From 145410f81c144a46cf5ce0324ff4454fa9f54ad0 Mon Sep 17 00:00:00 2001 From: "Erik M. Bray" Date: Tue, 20 Dec 2016 12:58:47 +0100 Subject: doc: Fix typos and clarify some aspects of the part-handler The existing documentation referred to a handle_type method when it really should be handle_part. It also referred to 'methods' when it really should say 'functions' to be clear (while it's true the built-in handlers are classes with methods of these names, in this context we mean module-level functions). Also clarified that a part-handler should come before the parts that it handles, and can override built-in handlers. --- doc/rtd/topics/format.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'doc/rtd') diff --git a/doc/rtd/topics/format.rst b/doc/rtd/topics/format.rst index ed87d3ed..436eb00f 100644 --- a/doc/rtd/topics/format.rst +++ b/doc/rtd/topics/format.rst @@ -127,11 +127,11 @@ Begins with: ``#cloud-boothook`` or ``Content-Type: text/cloud-boothook`` when u Part Handler ============ -This is a ``part-handler``. It will be written to a file in ``/var/lib/cloud/data`` based on its filename (which is generated). -This must be python code that contains a ``list_types`` method and a ``handle_type`` method. -Once the section is read the ``list_types`` method will be called. It must return a list of mime-types that this part-handler handles. +This is a ``part-handler``: It contains custom code for either supporting new mime-types in multi-part user data, or overriding the existing handlers for supported mime-types. It will be written to a file in ``/var/lib/cloud/data`` based on its filename (which is generated). +This must be python code that contains a ``list_types`` function and a ``handle_part`` function. +Once the section is read the ``list_types`` method will be called. It must return a list of mime-types that this part-handler handles. Because mime parts are processed in order, a ``part-handler`` part must precede any parts with mime-types it is expected to handle in the same user data. -The ``handle_type`` method must be like: +The ``handle_part`` function must be defined like: .. code-block:: python @@ -141,8 +141,9 @@ The ``handle_type`` method must be like: # filename = the filename of the part (or a generated filename if none is present in mime data) # payload = the parts' content -Cloud-init will then call the ``handle_type`` method once at begin, once per part received, and once at end. -The ``begin`` and ``end`` calls are to allow the part handler to do initialization or teardown. +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. +The ``'__begin__'`` and ``'__end__'`` sentinels allow the part handler to do initialization or teardown before or after +receiving any parts. Begins with: ``#part-handler`` or ``Content-Type: text/part-handler`` when using a MIME archive. -- cgit v1.2.3