findig.resource — Classes for representing API resources

class findig.resource.Resource(wrapped=None, lazy=None, name=None, model=None, formatter=None, parser=None, error_handler=None)

Bases: findig.resource.AbstractResource

A concrete implementation of AbstractResource.

This accepts keyword arguments only.

Parameters:

• wrapped – A function which the resource wraps; it typically returns the data for that particular resource.
• lazy – Indicates whether the wrapped resource function returns lazy resource data; i.e. data is not retrieved when the function is called, but at some later point when the data is accessed. Setting this allows Findig to evaluate the function’s return value after all resources have been declared to determine if it returns anything useful (for example, a :class:DataRecord which can be used as a model).
• name – A name that uniquely identifies the resource. If not given, it will be randomly generated.
• model – A data-model that describes how to read and write the resource’s data. By default, a generic findig.data_model.DataModel is attached.
• formatter – A function that should be used to format the resource’s data. By default, a generic findig.content.Formatter is attached.
• parser – A function that should be used to parse request content for the resource. By default, a generic findig.content.Parser is attached.
• error_handler – A function that should be used to convert exception into Responses. By default, a findig.content.ErrorHandler is used.

model

The value that was passed for model to the constructor, or if None was given, a DataModel.

formatter

If a formatter function was given to the constructor, then that is used. Otherwise, a generic findig.content.Formatter is used.

parser

The value that was passed for parser to the constructor. If no argument for parser was given to the constructor, then a generic findig.content.Parser is used.

error_handler

The value that was passed for error_handler to the constructor, or if None was given, then a generic findig.content.ErrorHandler.

collection(wrapped=None, **args)

Create a Collection instance

Parameters:wrapped – A wrapped function for the collection. In most cases, this should be a function that returns an iterable of resource data.

The keyword arguments are passed on to the constructor for :class:Collection, except that if no name is given, it defaults to {module}.{name} of the wrapped function.

This function may also be used as a decorator factory:

@resource.collection(include_urls=True)
def mycollection(self):
    pass

The decorated function will be replaced in its namespace by a Collection that wraps it. Any keyword arguments passed to the decorator factory will be handed over to the Collection constructor. If no keyword arguments are required, then @collection may be used instead of @collection().

compose_model(wrapper_args=None)

Noindex:

Make a composite model for the resource by combining a lazy data handler (if present) and the model specified on the resource.

Parameters:wrapper_args – A set of arguments to call the wrapped function with, so that a lazy data handler can be retrieved. If none is given, then fake data values are passed to the wrapped function. In this case, the data-model returned must not be used. Returns:A data-model for the resource

This is an internal method.

get_supported_methods(model=None)

Return a set of HTTP methods supported by the resource.

Parameters:model – The data-model to use to determine what methods supported. If none is given, a composite data model is built from self.model and any data source returned by the resource’s wrapped function.

handle_request(request, wrapper_args)

Dispatch a request to a resource.

See AbstractResource.handle_request() for accepted parameters.

class findig.resource.AbstractResource

Bases: object

Represents a very low-level web resource to be handled by Findig.

Findigs apps are essentially a collection of routed resources. Each resource is expected to be responsible for handling some requests to a set of one or more URLs. When requests to such a URL is received, Findig looks-up what resource is responsible, and hands the request object over to the resource for processing.

Custom implementations of the abstract class are possible. However, this class operates at a very low level in the Findig stack, so it is recommended that they are only used for extreme cases where those low-level operations are needed.

In addition to the methods defined here, resources should have a name attribute, which is a string that uniquely identifies it within the app. Optional parser and formatter attributes corresponding to findig.content.AbstractParser and finding.content.AbstractFormatter instances respectively, will also be used if added.

build_url(values)

Build a URL for this resource.

The URL is built using the current WSGI environ, so this function must be called from inside a request context. Furthermore, the resource must have already been routed to in the current app (see: findig.dispatcher.Dispatcher.route()), and this method must be passed values for any variables in the URL rule used to route to the resource.

Parameters:values (dict) – Values for the variables in a URL rule used to route to the resource.

Example:

>>> from findig import App
>>> app = App()
>>> @app.route("/index/<int:num>")
... @app.resource
... def item(num):
...     return {}
...
>>> with app.test_context(path="/index/1"):
...     item.build_url(dict(num=4))
...
'/index/4'

This method is not abstract.

get_supported_methods()

Return a Python set of HTTP methods to be supported by the resource.

handle_request(request, url_values)

Handle a request to one of the resource URLs.

Parameters:

• request (Request, which in turn is a subclass of werkzeug.wrappers.Request) – An object encapsulating information about the request. It is the same as findig.context.request.
• url_values – A dictionary of arguments that have been parsed from the URL routes, which may help to better identify the request. For example, if a resource is set up to handle URLs matching the rule /items/<int:id> and a request is sent to /items/43, then url_values will be {'id': 43}.

Returns:

This function should return data that will be transformed into an HTTP response. This is usually a dictionary, but depending on how formatting is configured, it may be any object the output formatter configured for the resource will accept.

class findig.resource.Collection(of, include_urls=False, bindargs=None, **keywords)

Bases: findig.resource.Resource

A Resource that acts as a collection of other resources.

Parameters:

• of (Resource) – The type of resource to be collected.
• include_urls – If True, the collection will attempt to insert a url field on each of the child items that it returns. Note that this only works if the child already has enough information in its fields to build a url (i.e., if the URL for the child contains an :id fragment, then the child must have an id field, which is then used to build its URL.
• bindargs – A dictionary mapping field names to URL variables. For example: a child resource may have the URL variable :id, but have a corresponding field named user_id; the appropriate value for bindargs in this case would be {'user_id': 'id'}.