Reference¶

`bobo` module documentation¶

Create WSGI-based web applications.

class bobo.Application(DEFAULT=None, **config)¶

Create a WSGI application.

The DEFAULT argument, if given, is a dictionary of options. Keyword options override options given in the DEFAULT options.

Option values are strings, typically read from ConfigParser files.

The values used by bobo, bobo_resources, bobo_configure and bobo_errors, can have comments. Lines within these values are truncated at the first ‘#’ characters.

The one required option is bobo_resources:

bobo_resources

Specifies resources to be used.

This option can be used to:

Specify modules to be scanned for resources.
Include specific resources, rather than all resources in given modules.
Override the order of resources given in modules.
Override routes used for resources given in modules.

Resources are specified on separate lines. Resources take one of 4 forms:

module_name

Use the resources from the given module.

resource

Use the named resource.

The resource is of the form: modulename:expression. The object is obtained by evaluating the expression in the named module.

route -> resource

The given route, possibly with placeholders, is handled by the given resource.

The resource is of the form: modulename:expression.

The object named by the resource must meet one of the following conditions:

It was created using one of the bobo decorators: resource, post, query, or subroute.
It has bobo_reroute method that takes the given route and returns a new resource. (The bobo decorators provide this.)
It is a class, in which case it is treated as a subroute.

Newlines may be included between the”->” and the resource, allowing the specification to be split over multiple lines.

route +> resource

The given route, which may not have placeholder, is added as a prefix of the given resource’s route.

The resource is of the form: modulename:expression, or just modulename.

Newlines may be included between the”+>” and the resource, allowing the specification to be split over multiple lines.

Bobo also used the following options:

bobo_configuration

Specify one or more (whitespace-delimited) callables to be called with the configuration data passed to the application.

Each callable is of the form: module_name:global_name

bobo_errors

Specify an object to be used for generating error responses. The value must be a module name or an object name of the form: modulename:expression. The object must have the callable attributes:

not_found(request, method)

Generate a response when a resource can’t be found.

This should return a 404 response.

method_not_allowed(request, method, methods)

Generate a response when the resource found doesn’t allow the request method.

This should return a 405 response and set the Allowed response header to the list of allowed headers.

missing_form_variable(request, method, name)

Generate a response when a form variable is missing.

The proper response in this situation isn’t obvious.

exception(request, method, ex_info)

Generate a response for the exception information given by exc_info. This method is optional. Bobo’s default behavior is to simply re-raise the exception.

build_response(request, method, data)¶

Build a response object from raw data.

This method is used by bobo when an application returns data rather than a response object. It can be overridden by subclasses to support alternative request implementations. (For example, some implementations may have response objects on a request that influence how a response is generated.)

The data object has several attributes:

status: Integer HTTP status code
body: Raw body data as returned from an application
content_type: The desired content type
headers: A list of header name/value pairs.

bobo.early()¶

Return an order used for resources that should be searched early.

The function returns a larger integer each time it is called. The value is smaller than values returned by the order or late functions.

bobo.late()¶

Return an order used for resources that should be searched late.

The function returns a larger integer each time it is called. The value is larger than values returned by the order or early functions.

exception bobo.NotFound¶

A resource cannot be found.

This exception can be raised by application code.

bobo.order()¶

Return an integer that can be used to order a resource.

The function returns a larger integer each time it is called. A resource can use this to set it’s bobo_order attribute.

bobo.post(route=None, method=[, 'POST', 'PUT'], content_type='text/html; charset=UTF-8', check=None, order=None)¶

Create a resource that passes POST data as arguments

This function is used as a function decorator to define a resource.

Arguments:

route

The route to match against a request URL to determine if the decorated callable should be used to satisfy a request.

if omitted, a route will be computed using the decorated callable’s name with the content_type subtype used as an extension.

method

The HTTP request method or methods that can be used. This can be either a string giving a single method name, or a sequence of strings.

The method argument defaults to the string 'POST'.

content_type

The content_type for the response.

The content type is ignored if the callable returns a response object.

check

A check function.

If provided, the check function (or callable) will be called before the decorated function. The check function is passed an instance, a request, and the decorated function. If the resource is a method, then first argument is the instance the method was called on, otherwise it is None. If the check function returns a response, the response will be used instead of calling the decorated function.

order

The order controls how resources are searched when matching URLs. Normally, resources are searched in order of evaluation. Passing the result of calling bobo.early or bobo.late can cause resources to be searched early or late.

The function may be used as a decorator directly without calling it. For example:

@bobo.post
def example():
    ...

is equivalent to:

@bobo.post()
def example():
    ...

The callable the decorator is applied to is analyzed to determine it’s signature. When the callable is called, the request, route data and request form data are used to satisfy any named arguments in the callable’s signature. For example, in the case of:

@bobo.post('/:a')
def example(bobo_request, a, b, c=None):
    ...

when handling a request for: http://localhost/x, with a post body of b=1, the request is passed to the bobo_request argument. the route data value 'x' is passed to the argument a, and the form data 1 is passed for b.

Standard function metadata attributes func_code and func_defaults are used to determine the signature and required arguments. The method attribute, im_func is used to determine if the callable is a method, in which case the first argument found in the signature is ignored.

bobo.preroute(route, resource)¶

Create a new resource by adding a route prefix

The given route is used as a subroute that is matched before matching the given resource’s route.

The resource can be a string, in which case it should be a global name, of the form module:expression, or a module name. If a module name is given, and the module doesn’t have a bobo_response function, then a resource is computed that tries each of the resources found in the module in order.

bobo.query(route=None, method=('GET', 'POST', 'HEAD'), content_type='text/html; charset=UTF-8', check=None, order=None)¶

Create a resource that passes form data as arguments

Create a decorator that, when applied to a callable, creates a resource.

Arguments:

route

The route to match against a request URL to determine if the decorated callable should be used to satisfy a request.

if omitted, a route will be computed using the decorated callable’s name with the content_type subtype used as an extension.

method

The HTTP request method or methods that can be used. This can be either a string giving a single method name, or a sequence of strings.

The method argument defaults to the tuple ('GET', 'HEAD', 'POST').

content_type

The content_type for the response.

The content type is ignored if the callable returns a response object.

check

A check function.

If provided, the check function (or callable) will be called before the decorated function. The check function is passed an instance, a request, and the decorated function. If the resource is a method, then first argument is the instance the method was called on, otherwise it is None. If the check function returns a response, the response will be used instead of calling the decorated function.

order

The order controls how resources are searched when matching URLs. Normally, resources are searched in order of evaluation. Passing the result of calling bobo.early or bobo.late can cause resources to be searched early or late.

The function may be used as a decorator directly without calling it. For example:

@bobo.query
def example():
    ...

is equivalent to:

@bobo.query()
def example():
    ...

The callable the decorator is applied to is analyzed to determine it’s signature. When the callable is called, the request, route data and request form data are used to satisfy any named arguments in the callable’s signature. For example, in the case of:

@bobo.query('/:a')
def example(bobo_request, a, b, c=None):
    ...

when handling a request for: http://localhost/x?b=1, the request is passed to the bobo_request argument. the route data value 'x' is passed to the argument a, and the form data 1 is passed for b.

Standard function metadata attributes func_code and func_defaults are used to determine the signature and required arguments. The method attribute, im_func is used to determine if the callable is a method, in which case the first argument found in the signature is ignored.

bobo.redirect(url, status=302, body=None, content_type='text/html; charset=UTF-8')¶

Generate a response to redirect to a URL.

The optional status argument can be used to supply a status other than 302. The optional body argument can be used to specify a response body. If not specified, a default body is generated based on the URL given in the url argument.

bobo.reroute(route, resource)¶

Create a new resource from a re-routable resource.

The resource can be a string, in which case it should be a global name, of the form module:expression.

bobo.resource(route=None, method=('GET', 'POST', 'HEAD'), content_type='text/html; charset=UTF-8', check=None, order=None)¶

Create a resource

This function is used as a decorator to define a resource. It can be applied to any kind of callable, not just a function.

Arguments:

route

The route to match against a request URL to determine if the decorated callable should be used to satisfy a request.

if omitted, a route will be computed using the decorated callable’s name with the content_type subtype used as an extension.

method

The HTTP request method or methods that can be used. This can be either a string giving a single method name, or a sequence of strings.

content_type

The content_type for the response.

The content type is ignored if the callable returns a response object.

check

A check function.

If provided, the check function (or callable) will be called before the decorated callable. The check function is passed an instance, a request, and the decorated callable. If the resource is a method, then first argument is the instance the method was called on, otherwise it is None. If the check function returns a response, the response will be used instead of calling the decorated callable.

order

The order controls how resources are searched when matching URLs. Normally, resources are searched in order of evaluation. Passing the result of calling bobo.early or bobo.late can cause resources to be searched early or late.

The function may be used as a decorator directly without calling it. For example:

@bobo.resource
def example(request):
    ...

is equivalent to:

@bobo.resource()
def example(request):
    ...

The callable must take a request object as the first argument. If the route has placeholders, then the callable must accept named parameters corresponding to the placeholders. The named parameters must have defaults for any optional placeholders.

Unlike the post and query decorators, this decorator doesn’t introspect the callable it’s applied to.

bobo.resources(resources)¶

Create a resource from multiple resources

A new resource is returned that works by searching the given resources in the order they’re given.

bobo.scan_class(class_)¶

Create an instance bobo_response method for a class

Scan a class (including its base classes) for resources and generate a bobo_response method of the class that calls them.

bobo.subroute(route=None, scan=False, order=None)¶

Create a resource that matches a URL in multiple steps

If called with a route or without any arguments, subroute returns an object that should then be called with a resource factory. The resource factory will be called with a request and route data and should return a resource object. For example:

@subroute('/:employee_id', scan=True)
class EmployeeView:
    def __init__(self, request, employee_id):
        ...

If no route is supplied, the __name__ attribute of the callable is used.

The resource factory may return None to indicate that a resource can’t be found on the subroute.

The scan argument, if given, should be given as a keyword parameter. It defaults to False. If True, then the callable should be a class and a bobo_response instance method will be added to the class that calls resources found by scanning the class and its base classes. Passing a True scan argument is equivalent to calling scan_class:

@subroute('/:employee_id')
@scan_class
class EmployeeView:
    def __init__(self, request, employee_id):

subroute can be passed a callable directly, as in:

@subroute
class Employees:
    def __init__(self, request):
        ...
    def bobo_response(self, request, path, method):
        ...

Which is equivalent to calling subroute without the callable and then passing the callable to the route:

@subroute()
class Employees:
    def __init__(self, request):
        ...
    def bobo_response(self, request, path, method):
        ...

Note that in the example above, the scan argument isn’t passed and defaults to False, so the class has to provide it’s own bobo_response method (or otherwise arrange that instances have one).

The optional order parameter controls how resources are searched when matching URLs. Normally, resources are searched in order of evaluation. Passing the result of calling bobo.early or bobo.late can cause resources to be searched early or late. It is usually a good idea to use bobo.late for subroutes that match any URL.

`boboserver` module documentation¶

Create WSGI-based web applications.

class boboserver.Debug(app, default=None)¶

Post-mortem debugging middleware

This middleware catches uncaught exceptions and runs the pdb.post_mortem debugging function, helping you to debug exceptions raised by your application.

The Debug class implements the Paste Deployment filter_app_factory protocol and is exported as a paste.filter_app_factory entry point named debug.

class boboserver.Reload(app, default, modules)¶

Module-reload middleware

This middleware can only be used with bobo applications. It monitors a list of modules given by a modules keyword parameter and configuration option. When a module changes, it reloads the module and reinitializes the bobo application.

The Reload class implements the Paste Deployment filter_app_factory protocol and is exported as a paste.filter_app_factory entry point named reload.

boboserver.server(args=None, Application=<class 'bobo.Application'>)¶

Bobo development server

The server function implements the bobo development server.

It is exported as a console_script entry point named bobo.

An alternate application can be passed in to run the server with a different application implementation as long as application passed in subclasses bobo.Application.

boboserver.static(route, directory)¶: Create a resource that serves static files from a directory

The bobo server¶

The bobo server is a script that runs a development web server with a given source file or modules, and configuration options. The usage is:

bobo [options] [name=value ...]

Command-line arguments are either options, or configuration options of the form optionname=value.

Options:

`-f SOURCE, --file SOURCE`
	Specify a source file name to be published. It’ll be converted to a module named `bobo__main__` and will have its __file__ set to the original file name.
`-r RESOURCE, --resource RESOURCE`
	Specify a resource, such as a module or global, to publish.
`-D, --debug`	Provide post-mortem debugging. If an uncaught exception is raised, use `pdb.post_mortem` to debug it.
`-p PORT, --port PORT`
	Specify the port to listen on.
`-c GLOBALNAME, --configure=GLOBALNAME`
	Specify the name of a global to call with configuration data. This is shorthand for `bobo_configure=globalname`. This is normally a name of the form `modulename:expression`, however, if you supply just an expression, the module of the first resource will be used. For example, with a command like: bobo -f my.py -c config The `config` function in `my.py` will be used.

-s ROUTE=PATH, –static ROUTE=PATH

Publish static files in the directory given by PATH at the route given by ROUTE.

While there are middleware components that are better at publishing static resources for production use, this option makes it easier to get started during development.

After the options, you can give configuration options as name=value pairs. These will be passed as configuration options to bobo and to any configuration handler you specify.

Example:

bobo -f fswiki.py -c config directory=docs

In this example, we run the application in the source file fswiki.py. We pass configuration data to the application’s config function. The options include the setting of 'doc' for the directory option.

Advanced: resource interfaces¶

Most applications will use the bobo-provided decorators to implement resources. These decorators create objects that provide certain methods and attributes. Applications can implement these methods and attributes themselves to provide specialized behaviors. For example, an application can implement bobo_response to provide a specialized object-look-up mechanism that doesn’t use routes.

The most important method is bobo_response. When bobo scans a module or class for resources, it looks for objects with this method. When handling a request, it calls this method on each of the objects found until a value is returned. See IResource for more details.

The optional methods, bobo_methods, bobo_order and bobo_response are used when scanning a module or class. Resources found in a module or class are ordered within the module or class based on values of their bobo_order attribute. (If a resource doesn’t have a bobo_order attribute, a value is used that is between those returned by bobo.order() and bobo.late().

The bobo_route attribute is used to group resources within a module or class that have the same route. Resources with the same route are treated as a single resource. The route is matched and then a the first resource that accepts the request method is used.

The optional bobo_reroute() method is used by the bobo bobo.reroute() function to compute a new resource from an existing resource and a new route.

IResource¶

class boboserver.IResource¶

IResource is documented here to define an API that can be provided by application-defined resources. Bobo doesn’t actually define an IResource object.

bobo_response(request, path, method)¶

Find an object to publish at the given path.

If an object is found, call it and return the result.

If no object can be found, return None.

If a resource matches a path but doesn’t accept the request method, a 405, method not allowed, response should be returned.

If the return value isn’t a response, it should be converted to a response.

bobo_methods¶: This optional attribute specifies the HTTP request methods supported by objects found by the resource. See Advanced: resource interfaces. If present, it muse be a sequence of method names, or None. If it is None, then all methods are accepted.

bobo_order¶

This optional attribute defines the precedence order for a resource. See Advanced: resource interfaces. If present, it must be an integer. Resources with lower values for bobo_order are used before resources with higher values. If the attribute isn’t present, a very high value is assumed.

Typically, order() is called to get a value for bobo_order when a resource is defined.

bobo_route¶: This optional attribute defines the complete route for a resource. See Advanced: resource interfaces. If present, it must be an string.

bobo_reroute(route)¶: Return a new resource for the given route.

Advanced: subclassing bobo.Application¶

The bobo WSGI application, bobo.Application can be subclassed to handle alternate request implementations. This is to allow applications written for frameworks using request implementations other than Webob to be used with bobo. A subclass should override the __call__() and build_response() methods.

The __call__() method should:

Create a request.
Call self.bobo_response(request, path, method) to get a response.
Return the result of calling the response with the environ and start_response arguments passed to __call__().

The __call__() should look like:

def __call__(self, environ, start_response):
     """Handle a WSGI application request.
     """
     request = ...

     return self.bobo_response(request, request.path_info, request.method
                               )(environ, start_response)

The request should implement as much of the WebOb request API as practical. It must implement the attributes used by bobo: path_info, method, params, and POST.

The build_response() method is used to build a response when an application function returns a value that isn’t a response. See the bobo.Application for more information on this method.

New application implementations will also want to provide matching development servers. The boboserver.server() entry point accepts an alternate application object, making implementation of alternate development servers trivial.

Glossary¶

order

The order in which a resource is searched relative to other resources.

response

An object that represents a web response. This is usually a Webob response, but it may be any callable object that implements the WSGI application interface.

Applications will typically return strings that are converted to responses by bobo, or will construct and return Webob response objects.

request

An object that contains information about a web request. This is a Webob request object. See the Webob documentation to get details of its interface.

route

A URL pattern expressed as a path with placeholders, as in:

/greeters/:name/:page?.html

Routes are inspired by the Ruby on Rails Routing system.

Placeholders are Python identifiers preceded by “:/”. If a placeholder is followed by a question mark, it is optional. A placeholder may be followed by an extension. When a route matches a URL, the URL text corresponding to the placeholders is passed to the application as keyword parameters.

route data

Values for placeholders resulting from matching a URL against a route. For example, matching the URL: http://localhost/a/b against the route /:x/:y/:z? results in the route data {'x': 'a', 'y': 'b'}.

resource

An object that has a bobo_response method. See Advanced: resource interfaces.

routes

See route.

Reference¶

`bobo` module documentation¶

`boboserver` module documentation¶

The bobo server¶

Advanced: resource interfaces¶

IResource¶

Advanced: subclassing bobo.Application¶

Glossary¶

Table Of Contents

Previous topic

Next topic

Navigation

Reference¶

bobo module documentation¶

boboserver module documentation¶

The bobo server¶

Advanced: resource interfaces¶

IResource¶

Advanced: subclassing bobo.Application¶

Glossary¶

Table Of Contents

Previous topic

Next topic

Quick search

Navigation

`bobo` module documentation¶

`boboserver` module documentation¶