S3Method

S3Method is an interface to implement method handlers for the S3 RESTful API. Method handlers are used to perform requested actions on S3Resources, and produce the output for the view.

Implementing Methods

In general, method handlers must be callable objects, i.e. they can be instances of classes which implement the __call__ method, lambdas or normal functions.

In any case, they must take the S3Request instance (representing the HTTP request) and a variable list of named arguments as parameters:

Function:

def my_method_handler(r, **attr):
    return dict()

Lambda:

my_method_handler = lambda r, **attr: dict()

Class and instance:

class MyMethodHandler:
    def __call__(r, **attr):
        return dict()

my_method_handler = MyMethodHandler()

The returned dict will be passed to the view, so it would usually contain the output data.

Configuring Methods

Methods of the RESTful API can be configured:

1. using s3db.set_method for explicit URL methods
2. using S3Resource.set_handler for a particular S3Resource instance

where a overrides b.

The methods create, read, update and delete are pre-defined for all resources (=fallback to S3CRUD), however, they can be customized by set_handler.

S3Method Interface

The S3Method class implements the __call__(r, **attr) method, and adds some attributes and methods which are commonly needed in most method handlers:

Attributes:

• self.manager: the S3ResourceController instance
• self.session: the session store
• self.request: the web2py Request instance
• self.response: the web2py Response instance
• self.T: the global translator object
• self.db: the global DAL instance (database)
• self.download_url: the default download-URL
• self.method: string containing the requested method

Resource:

• self.resource: the S3Resource instance for the requested resource
• self.prefix: the application prefix ("Module" prefix)
• self.name: the name of the requested resource (without prefix)
• self.table: the corresponding database table
• self.tablename: the database table name
• self.record: the record ID specified in the URL

Note that, other than in S3Request instances, the resource attributes here refer to the target resource of the request, meaning, this would be the component if a component has been requested. To get at the parent resource, use self.resource.parent.

Methods:

• self.permit: check authorization (shortcut for auth.shn_has_permission)
• self._config: gets a CRUD setting of the target table
• self._view: finds the pathname of a custom view template

Hooks:

• self.next: URL to redirect to after the current request has been completed, typically set by the method handler (Note: this redirection does never happen after GET)

To implement a method handler as S3Method, you would typically subclass S3Method and implement the apply_method method:

class MyMethodHandler(S3Method):

    def apply_method(r, **attr):
        return dict()

For examples see modules/s3/s3crud.py or modules/s3/s3search.py.