bag.web.burla module

Powerful URL generation independent of web frameworks.

Burla stores a collection of page URL templates, separate from a collection of API method URL templates. The only difference between them is that operations have a request method (GET, POST, PUT etc.).

Burla also facilitates generating documentation about pages and API operations in the Python server.

No matter what web framework you are using, you are better off generating URLs with Burla because this makes your application more independent of web frameworks so you can switch more easily.

Another advantage is that, based on the URL templates, burla generates URLs in the Python server as well as in the Javascript client. It generates a short Javascript library that takes care of this.

Maintenance of your web app becomes easier because you register your URLs only once (in the Python server code) and then the URLs can be used in the entire stack. When you change your URLs, you only do it in one place.

URL templates (for matching views) stop at the left of the question mark, but when generating URLs, burla supports both query params (to the right of the question mark) and fragments (to the right of the #),

Here are a few examples of usage in the Javascript client:

// Let's see a previously registered URL template:
burla.page('User details')
"/users/:user_id/details"

// Provide a map to generate a real URL from the template:
burla.page('User details', {user_id: 1})
"/users/1/details"

// Provide another argument to add a fragment (to the right of the #):
burla.page('User details', {user_id: 1}, 'tab=aboutme')
"/users/1/details#tab=aboutme"

// Extra params (not found in the URL template) go in the query:
burla.page('User details', {user_id: 1, photos: 'big'}, 'tab=aboutme')
"/users/1/details?photos=big#tab=aboutme"

You can find integration with the Pyramid web framework in bag.web.pyramid.burla. Please contribute integration into other frameworks.

class bag.web.burla.Burla(root='', page_class=<class 'bag.web.burla.Page'>, op_class=<class 'bag.web.burla.Operation'>)

Bases: object

Collection of pages and operations. Easily output as JSON.

Generates URLs and provides JS code to generate URLs in the client.

API_TITLE = 'HTTP API Documentation'

PAGES_TITLE = 'Site map'

add_op(op_name, **kw)

Decorate view handlers to register an operation with Burla.

add_page(op_name, **kw)

Decorator for view handlers that registers a page with Burla.

gen_documentation(pages=False, title='', prefix='', suffix='')

Generate documentation in reStructuredText.

If pages is True, the documentation is a site map. But by default the documentation contains HTTP API methods.

Sources of information are the ‘section’, ‘name’, ‘doc’ and ‘permission’ attributes of the registered Operation instances.

gen_ops()

gen_pages()

get_javascript_code()

Return a JS library to generate the application URLs.

Return JS code containing the registered operations and pages, plus functions to generate URLs from them.

to_dict()

Use this to generate JSON so the client knows the URLs too.

url(name, **kw)

Return only the generated URL.

class bag.web.burla.Operation(op_name, url_templ, fn=None, permission=None, section='Miscellaneous', **view_args)

Bases: bag.web.burla.Page

Subclass of Page representing an HTTP operation.

is_operation = True

is_page = False

to_dict()

Convert this instance into a dictionary, maybe for JSON output.

class bag.web.burla.Page(op_name, url_templ, fn=None, permission=None, section='Miscellaneous', **view_args)

Bases: object

Class that represents a web page in burla.

A page is comprised of a descriptive name, a URL template (from which parameters are discovered) and possibly documentation strings. The instance is able to generate its URL.

A URL template looks like this (params are preceded by a colon):

/cities/:city/streets/:street

PARAM = re.compile(':([a-z_]+)')

is_operation = False

is_page = True

to_dict()

Convert this instance into a dictionary, maybe for JSON output.

url(fragment='', **kw)

Given a dictionary, generate an actual URL from the template.