Merge ~erik-m-bray+ubuntu/cloud-init:doc/format/part-handler-fixes into cloud-init:master

Proposed by E. Madison Bray
Status: Merged
Merged at revision: 145410f81c144a46cf5ce0324ff4454fa9f54ad0
Proposed branch: ~erik-m-bray+ubuntu/cloud-init:doc/format/part-handler-fixes
Merge into: cloud-init:master
Diff against target: 31 lines (+7/-6)
1 file modified
doc/rtd/topics/format.rst (+7/-6)
Reviewer Review Type Date Requested Status
Scott Moser Approve
Review via email: mp+313607@code.launchpad.net

Description of the change

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.

To post a comment you must log in.
Revision history for this message
Scott Moser (smoser) wrote :

Thanks!

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
diff --git a/doc/rtd/topics/format.rst b/doc/rtd/topics/format.rst
index ed87d3e..436eb00 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
127Part Handler127Part Handler
128============128============
129129
130This is a ``part-handler``. It will be written to a file in ``/var/lib/cloud/data`` based on its filename (which is generated).130This 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).
131This must be python code that contains a ``list_types`` method and a ``handle_type`` method. 131This must be python code that contains a ``list_types`` function and a ``handle_part`` function.
132Once the section is read the ``list_types`` method will be called. It must return a list of mime-types that this part-handler handles.132Once 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.
133133
134The ``handle_type`` method must be like:134The ``handle_part`` function must be defined like:
135135
136.. code-block:: python136.. code-block:: python
137137
@@ -141,8 +141,9 @@ The ``handle_type`` method must be like:
141 # filename = the filename of the part (or a generated filename if none is present in mime data)141 # filename = the filename of the part (or a generated filename if none is present in mime data)
142 # payload = the parts' content142 # payload = the parts' content
143143
144Cloud-init will then call the ``handle_type`` method once at begin, once per part received, and once at end.144Cloud-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.
145The ``begin`` and ``end`` calls are to allow the part handler to do initialization or teardown.145The ``'__begin__'`` and ``'__end__'`` sentinels allow the part handler to do initialization or teardown before or after
146receiving any parts.
146147
147Begins with: ``#part-handler`` or ``Content-Type: text/part-handler`` when using a MIME archive.148Begins with: ``#part-handler`` or ``Content-Type: text/part-handler`` when using a MIME archive.
148149

Subscribers

People subscribed via source and target branches