storlets/doc/source/writing_and_deploying_python_storlets.rst

Python Storlet Writing and Deployment Guideline

This is the Python specific storlet writing and deploying guide. This guide complements the more general guide for writing and deploying storlets which should be read first.

A python module implementing a storlet looks like this:

class <Class name>(object):
    def __init__(self, logger):
        self.logger = logger

    def __call__(self, in_files, out_files, params):
        """
        The function called for storlet invocation
        :param in_files: a list of StorletInputFile
        :param out_files: a list of StorletOutputFile
        :param params: a dict of request parameters
        """

Below is a class diagram illustrating the classes behind the in_files, out_files, and logger. The diagram lists only the methods that the storlet writer is expected to work with.

1. The StorletInputFile is used to stream object's data into the storlet. StorletInputFile has the same read methods as python FileObject. Trying to write to a StorletInputFile yields NotImplemented error. Whenever a storlet is invoked, an instance of this class is provided. To consume the metadata call the StorletInputFile.get_metadata method.
2. The StorleOutputFile is used for writing the storlet output. StorletOutputFile has the same write methods as python FileObject. Trying to read from a StorletOutputFile yields NotImplemented error. Whenever a storlet is invoked, an instance of this class is provided. Use the StorletInputFile.set_metadata method to set the Object's metadata. Note that the storlet must call the StorletInputFile set_metadata method. Moreowver, StorletInputFile.set_metadata must be called before writing the data.
3. StorletLogger. The StorletLogger class implements the same log methods as the Python logger.

When invoked via the Swift REST API the __call__ method will be called as follows:

1. The in_files list would include one or more element(s) of type StorleInputFile representing the object appearing in the request's URI (and possibly extra resources).
2. The out_files would include a single element of type StorleOutputFile representing the response returned to the user.
3. The parameters is a dictionary with the execution parameters sent. These parameters can be specified in the storlet execution request.
4. A StorletLogger instance.

Deploying a Python Storlet

Below are specific guidelines for deploying a Python storlet:

1. The object name of the python module containing the storlet class implemetation must end with .py
2. Any python modules that the class implementation is dependent on should be uploaded as separate .py(s).
3. The 'X-Object-Meta-Storlet-Main' metadata key shold be of the form: <module_name>.<class_name>. For example, if the storlet name is SimpleStorlet and it resides in simple_storlet.py, then the 'X-Object-Meta-Storlet-Main' metadata key shold be "simple_storlet.SimpleStorlet"

Deploying a Python Dependency

1. Currently, there is no limitation as to what is being uploaded as a dependency.