Utility functions for the Admin application¶

gluon.admin.add_path_first(path)[source]¶

gluon.admin.apath(path='', r=None)[source]¶

Builds a path inside an application folder

Parameters:	path (str) – path within the application folder r – the global request object

gluon.admin.app_cleanup(app, request)[source]¶

Removes session, cache and error files

Parameters:	app (str) – application name request – the global request object
Returns:	True if everything went ok, False otherwise

gluon.admin.app_compile(app, request)[source]¶

Compiles the application

Parameters:	app (str) – application name request – the global request object
Returns:	None if everything went ok, traceback text if errors are found

gluon.admin.app_create(app, request, force=False, key=None, info=False)[source]¶

Create a copy of welcome.w2p (scaffolding) app

Parameters:	app (str) – application name request – the global request object

gluon.admin.app_install(app, fobj, request, filename, overwrite=None)[source]¶

Installs an application:

• Identifies file type by filename
• Writes fobj contents to the ../deposit/ folder
• Calls w2p_unpack() to do the job.

Parameters:	app (str) – new application name fobj (obj) – file object containing the application to be installed request – the global request object filename (str) – original filename of the fobj, required to determine extension overwrite (bool) – force overwrite of existing application
Returns:	name of the file where app is temporarily stored or None on failure

gluon.admin.app_pack(app, request, raise_ex=False, filenames=None)[source]¶

Builds a w2p package for the application

Parameters:	app (str) – application name request – the global request object
Returns:	filename of the w2p file or None on error

gluon.admin.app_pack_compiled(app, request, raise_ex=False)[source]¶

Builds a w2p bytecode-compiled package for the application

Parameters:	app (str) – application name request – the global request object
Returns:	filename of the w2p file or None on error

gluon.admin.app_uninstall(app, request)[source]¶

Uninstalls the application.

Parameters:	app (str) – application name request – the global request object
Returns:	True on success, False on failure

gluon.admin.check_new_version(myversion, version_url)[source]¶

Compares current web2py’s version with the latest stable web2py version.

Parameters:	myversion – the current version as stored in file web2py/VERSION version_URL – the URL that contains the version of the latest stable release
Returns:	state, version state : True if upgrade available, False if current version is up-to-date, -1 on error version : the most up-to-version available
Return type:	tuple

gluon.admin.create_missing_app_folders(request)[source]¶

gluon.admin.create_missing_folders()[source]¶

gluon.admin.plugin_install(app, fobj, request, filename)[source]¶

Installs a plugin:

• Identifies file type by filename
• Writes fobj contents to the ../deposit/ folder
• Calls w2p_unpack_plugin() to do the job.

Parameters:	app (str) – new application name fobj – file object containing the application to be installed request – the global request object filename – original filename of the fobj, required to determine extension
Returns:	name of the file where plugin is temporarily stored or False on failure

gluon.admin.plugin_pack(app, plugin_name, request)[source]¶

Builds a w2p package for the plugin

Parameters:	app (str) – application name plugin_name (str) – the name of the plugin without plugin_ prefix request – the current request app
Returns:	filename of the w2p file or False on error

gluon.admin.unzip(filename, dir, subfolder='')[source]¶

Unzips filename into dir (.zip only, no .gz etc)

Parameters:	filename (str) – archive dir (str) – destination subfolder (str) – if != ‘’ unzips only files in subfolder

gluon.admin.upgrade(request, url='http://web2py.com')[source]¶

Upgrades web2py (src, osx, win) if a new version is posted. It detects whether src, osx or win is running and downloads the right one

Parameters:	request – the current request object (required to determine version and path) url – the incomplete url where to locate the latest web2py (actual url is url+’/examples/static/web2py_(src|osx|win).zip’)

Returns

tuple: completed, traceback

• completed: True on success, False on failure (network problem or old version)
• traceback: None on success, raised exception details on failure

Basic caching classes and methods¶

• Cache - The generic caching object interfacing with the others
• CacheInRam - providing caching in ram
• CacheOnDisk - provides caches on disk

Memcache is also available via a different module (see gluon.contrib.memcache)

When web2py is running on Google App Engine, caching will be provided by the GAE memcache (see gluon.contrib.gae_memcache)

class gluon.cache.Cache(request)[source]¶

Bases: object

Sets up generic caching, creating an instance of both CacheInRam and CacheOnDisk. In case of GAE will make use of gluon.contrib.gae_memcache.

• self.ram is an instance of CacheInRam
• self.disk is an instance of CacheOnDisk

action(time_expire=300, cache_model=None, prefix=None, session=False, vars=True, lang=True, user_agent=False, public=True, valid_statuses=None, quick=None)[source]¶

Better fit for caching an action

Warning

Experimental!

Currently only HTTP 1.1 compliant reference : http://code.google.com/p/doctype-mirror/wiki/ArticleHttpCaching

Parameters:

time_expire (int) – same as @cache cache_model (str) – same as @cache prefix (str) – add a prefix to the calculated key session (bool) – adds response.session_id to the key vars (bool) – adds request.env.query_string lang (bool) – adds T.accepted_language user_agent (bool or dict) – if True, adds is_mobile and is_tablet to the key. Pass a dict to use all the needed values (uses str(.items())) (e.g. user_agent=request.user_agent()). Used only if session is not True public (bool) – if False forces the Cache-Control to be ‘private’ valid_statuses – by default only status codes starting with 1,2,3 will be cached. pass an explicit list of statuses on which turn the cache on quick – Session,Vars,Lang,User-agent,Public: fast overrides with initials, e.g. ‘SVLP’ or ‘VLP’, or ‘VLP’

autokey = ':%(name)s:%(args)s:%(vars)s'¶

static with_prefix(cache_model, prefix)[source]¶

allow replacing cache.ram with cache.with_prefix(cache.ram,’prefix’) it will add prefix to all the cache keys used.

gluon.cache.lazy_cache(key=None, time_expire=None, cache_model='ram')[source]¶

Can be used to cache any function including ones in modules, as long as the cached function is only called within a web2py request

If a key is not provided, one is generated from the function name time_expire defaults to None (no cache expiration)

If cache_model is “ram” then the model is current.cache.ram, etc.

Functions required to execute app components¶

gluon.cfs.getcfs(key, filename, filter=None)[source]¶

Caches the filtered file filename with key until the file is modified.

Parameters:	key (str) – the cache key filename – the file to cache filter – is the function used for filtering. Normally filename is a .py file and filter is a function that bytecode compiles the file. In this way the bytecode compiled file is cached. (Default = None)

This is used on Google App Engine since pyc files cannot be saved.

Functions required to execute app components¶

gluon.compileapp.LOAD(c=None, f='index', args=None, vars=None, extension=None, target=None, ajax=False, ajax_trap=False, url=None, user_signature=False, timeout=None, times=1, content='loading...', post_vars=<Storage {}>, **attr)[source]¶

LOADs a component into the action’s document

Parameters:

c (str) – controller f (str) – function args (tuple or list) – arguments vars (dict) – vars extension (str) – extension target (str) – id of the target ajax (bool) – True to enable AJAX bahaviour ajax_trap (bool) – True if ajax is set to True, traps both links and forms “inside” the target url (str) – overrides c,`f`,`args` and vars user_signature (bool) – adds hmac signature to all links with a key that is different for every user timeout (int) – in milliseconds, specifies the time to wait before starting the request or the frequency if times is greater than 1 or “infinity” times (integer or str) – how many times the component will be requested “infinity” or “continuous” are accepted to reload indefinitely the component

class gluon.compileapp.LoadFactory(environment)[source]¶

Bases: object

Attention: this helper is new and experimental

gluon.compileapp.build_environment(request, response, session, store_current=True)[source]¶

Build the environment dictionary into which web2py files are executed.

gluon.compileapp.compile_application(folder)[source]¶

Compiles all models, views, controller for the application in folder.

gluon.compileapp.compile_controllers(folder)[source]¶

Compiles all the controllers in the application specified by folder

gluon.compileapp.compile_models(folder)[source]¶

Compiles all the models in the application specified by folder

gluon.compileapp.compile_views(folder)[source]¶

Compiles all the views in the application specified by folder

gluon.compileapp.find_exposed_functions(data)[source]¶

gluon.compileapp.local_import_aux(name, reload_force=False, app='welcome')[source]¶

In apps, instead of importing a local module (in applications/app/modules) with:

import a.b.c as d

you should do:

d = local_import('a.b.c')

or (to force a reload):

d = local_import(‘a.b.c’, reload=True)

This prevents conflict between applications and un-necessary execs. It can be used to import any module, including regular Python modules.

gluon.compileapp.model_cmp(a, b, sep='.')[source]¶

gluon.compileapp.model_cmp_sep(a, b, sep='/')[source]¶

class gluon.compileapp.mybuiltin[source]¶

Bases: object

NOTE could simple use a dict and populate it, NOTE not sure if this changes things though if monkey patching import.....

gluon.compileapp.re_compile(regex)[source]¶

gluon.compileapp.read_pyc(filename)[source]¶

Read the code inside a bytecode compiled file if the MAGIC number is compatible

Returns:	a code object

gluon.compileapp.remove_compiled_application(folder)[source]¶

Deletes the folder compiled containing the compiled application.

gluon.compileapp.run_controller_in(controller, function, environment)[source]¶

Runs the controller.function() (for the app specified by the current folder). It tries pre-compiled controller_function.pyc first before compiling it.

gluon.compileapp.run_models_in(environment)[source]¶

Runs all models (in the app specified by the current folder) It tries pre-compiled models first before compiling them.

gluon.compileapp.run_view_in(environment)[source]¶

Executes the view for the requested action. The view is the one specified in response.view or determined by the url or view/generic.extension It tries the pre-compiled views_controller_function.pyc before compiling it.

gluon.compileapp.save_pyc(filename)[source]¶

Bytecode compiles the file filename

gluon.compileapp.test()[source]¶

Example:

>>> import traceback, types
>>> environment={'x':1}
>>> open('a.py', 'w').write('print 1/x')
>>> save_pyc('a.py')
>>> os.unlink('a.py')
>>> if type(read_pyc('a.pyc'))==types.CodeType: print 'code'
code
>>> exec read_pyc('a.pyc') in environment
1

Support for smart import syntax for web2py applications¶

exception gluon.custom_import.CustomImportException[source]¶

Bases: exceptions.ImportError

class gluon.custom_import.TrackImporter[source]¶

Bases: object

An importer tracking the date of the module files and reloading them when they are changed.

PACKAGE_PATH_SUFFIX = '/__init__.py'¶

THREAD_LOCAL = <thread._local object>¶

gluon.custom_import.custom_import_install()[source]¶

gluon.custom_import.custom_importer(name, globals=None, locals=None, fromlist=None, level=-1)[source]¶

web2py’s custom importer. It behaves like the standard Python importer but it tries to transform import statements as something like “import applications.app_name.modules.x”. If the import fails, it falls back on naive_importer

gluon.custom_import.is_tracking_changes()[source]¶

gluon.custom_import.track_changes(track=True)[source]¶

Takes care of adapting pyDAL to web2py’s needs¶

Debugger support classes¶

class gluon.debug.Pipe(name, mode='r', *args, **kwargs)[source]¶

Bases: Queue.Queue

flush()[source]¶

read(count=None, timeout=None)[source]¶

readline()[source]¶

write(data)[source]¶

class gluon.debug.WebDebugger(pipe, completekey='tab', stdin=None, stdout=None)[source]¶

Bases: gluon.contrib.qdb.Frontend

Qdb web2py interface

clear_interaction()[source]¶

do_continue(*args, **kwargs)[source]¶

do_exec(statement)[source]¶

do_next(*args, **kwargs)[source]¶

do_quit(*args, **kwargs)[source]¶

do_return(*args, **kwargs)[source]¶

do_step(*args, **kwargs)[source]¶

exception(title, extype, exvalue, trace, request)[source]¶

interaction(filename, lineno, line, **context)[source]¶

run()[source]¶

gluon.debug.check_interaction(fn)[source]¶

Decorator to clean and prevent interaction when not available

gluon.debug.communicate(command=None)[source]¶

send command to debbuger, wait result

gluon.debug.set_trace()[source]¶

breakpoint shortcut (like pdb)

gluon.debug.stop_trace()[source]¶

stop waiting for the debugger (called atexit)

File operations¶

gluon.fileutils.parse_version(version)[source]¶

Attempts to parse SemVer, fallbacks on legacy

gluon.fileutils.read_file(filename, mode='r')[source]¶

Returns content from filename, making sure to close the file explicitly on exit.

gluon.fileutils.write_file(filename, value, mode='w')[source]¶

Writes <value> to filename, making sure to close the file explicitly on exit.

gluon.fileutils.readlines_file(filename, mode='r')[source]¶

Applies .split(‘ ‘) to the output of read_file()

gluon.fileutils.up(path)[source]¶

gluon.fileutils.abspath(*relpath, **base)[source]¶

Converts relative path to absolute path based (by default) on applications_parent

gluon.fileutils.mktree(path)[source]¶

gluon.fileutils.listdir(path, expression='^.+$', drop=True, add_dirs=False, sort=True, maxnum=None, exclude_content_from=None)[source]¶

Like os.listdir() but you can specify a regex pattern to filter files. If add_dirs is True, the returned items will have the full path.

gluon.fileutils.recursive_unlink(f)[source]¶

Deletes f. If it’s a folder, also its contents will be deleted

gluon.fileutils.cleanpath(path)[source]¶

Turns any expression/path into a valid filename. replaces / with _ and removes special characters.

gluon.fileutils.tar(file, dir, expression='^.+$', filenames=None, exclude_content_from=None)[source]¶

Tars dir into file, only tars file that match expression

gluon.fileutils.untar(file, dir)[source]¶

Untar file into dir

gluon.fileutils.tar_compiled(file, dir, expression='^.+$', exclude_content_from=None)[source]¶

Used to tar a compiled application. The content of models, views, controllers is not stored in the tar file.

gluon.fileutils.get_session(request, other_application='admin')[source]¶

Checks that user is authorized to access other_application

gluon.fileutils.check_credentials(request, other_application='admin', expiration=3600, gae_login=True)[source]¶

Checks that user is authorized to access other_application

gluon.fileutils.w2p_pack(filename, path, compiled=False, filenames=None)[source]¶

Packs a web2py application.

Parameters:	filename (str) – path to the resulting archive path (str) – path to the application compiled (bool) – if True packs the compiled version filenames (list) – adds filenames to the archive

gluon.fileutils.w2p_unpack(filename, path, delete_tar=True)[source]¶

gluon.fileutils.w2p_pack_plugin(filename, path, plugin_name)[source]¶

Packs the given plugin into a w2p file. Will match files at:

<path>/*/plugin_[name].*
<path>/*/plugin_[name]/*

gluon.fileutils.w2p_unpack_plugin(filename, path, delete_tar=True)[source]¶

gluon.fileutils.fix_newlines(path)[source]¶

gluon.fileutils.make_fake_file_like_object()[source]¶

Template helpers¶

class gluon.html.A(*components, **attributes)[source]¶

Bases: gluon.html.DIV

Generates an A() link. A() in web2py is really important and with the included web2py.js allows lots of Ajax interactions in the page

On top of “usual” _attributes, it takes

Parameters:	callback – an url to call but not redirect to cid – if you want to load the _href into an element of the page (component) pass its id (without the #) here delete – element to delete after calling callback target – same thing as cid confirm – text to display upon a callback with a delete noconfirm – don’t display alert upon a callback with delete

tag = 'a'¶

xml()[source]¶

gluon.html.ASSIGNJS(**kargs)[source]¶

class gluon.html.B(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'b'¶

class gluon.html.BEAUTIFY(component, **attributes)[source]¶

Bases: gluon.html.DIV

Turns any list, dictionary, etc into decent looking html.

Two special attributes are

• sorted: a function that takes the dict and returned sorted keys
• keyfilter: a function that takes a key and returns its representation or None if the key is to be skipped. By default key[:1]==’_’ is skipped.

Examples:

>>> BEAUTIFY(['a', 'b', {'hello': 'world'}]).xml()
'<div><table><tr><td><div>a</div></td></tr><tr><td><div>b</div></td></tr><tr><td><div><table><tr><td style="font-weight:bold;vertical-align:top;">hello</td><td style="vertical-align:top;">:</td><td><div>world</div></td></tr></table></div></td></tr></table></div>'

static no_underscore(key)[source]¶

tag = 'div'¶

class gluon.html.BODY(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'body'¶

class gluon.html.BR(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'br/'¶

class gluon.html.BUTTON(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'button'¶

class gluon.html.CENTER(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'center'¶

class gluon.html.CAT(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = ''¶

class gluon.html.CODE(*components, **attributes)[source]¶

Bases: gluon.html.DIV

Displays code in HTML with syntax highlighting.

Parameters:	language – indicates the language, otherwise PYTHON is assumed link – can provide a link styles – for styles

Examples:

{{=CODE(“print ‘hello world’”, language=’python’, link=None,

counter=1, styles={}, highlight_line=None)}}

supported languages are

“python”, “html_plain”, “c”, “cpp”, “web2py”, “html”

The “html” language interprets {{ and }} tags as “web2py” code, “html_plain” doesn’t.

if a link=’/examples/global/vars/’ is provided web2py keywords are linked to the online docs.

the counter is used for line numbering, counter can be None or a prompt string.

xml()[source]¶

class gluon.html.COL(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'col/'¶

class gluon.html.COLGROUP(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'colgroup'¶

class gluon.html.DIV(*components, **attributes)[source]¶

Bases: gluon.html.XmlComponent

HTML helper, for easy generating and manipulating a DOM structure. Little or no validation is done.

Behaves like a dictionary regarding updating of attributes. Behaves like a list regarding inserting/appending components.

Examples:

>>> DIV('hello', 'world', _style='color:red;').xml()
'<div style="color:red;">helloworld</div>'

All other HTML helpers are derived from DIV.

_something=”value” attributes are transparently translated into something=”value” HTML attributes

append(value)[source]¶

list style appending of components

Examples:

>>> a=DIV()
>>> a.append(SPAN('x'))
>>> print a
<div><span>x</span></div>

element(*args, **kargs)[source]¶

Finds the first component that matches the supplied attribute dictionary, or None if nothing could be found

Also the components of the components are searched.

elements(*args, **kargs)[source]¶

Find all components that match the supplied attribute dictionary, or None if nothing could be found

All components of the components are searched.

Examples:

>>> a = DIV(DIV(SPAN('x'),3,DIV(SPAN('y'))))
>>> for c in a.elements('span',first_only=True): c[0]='z'
>>> print a
<div><div><span>z</span>3<div><span>y</span></div></div></div>
>>> for c in a.elements('span'): c[0]='z'
>>> print a
<div><div><span>z</span>3<div><span>z</span></div></div></div>

It also supports a syntax compatible with jQuery

Examples:

>>> a=TAG('<div><span><a id="1-1" u:v=$>hello</a></span><p class="this is a test">world</p></div>')
>>> for e in a.elements('div a#1-1, p.is'): print e.flatten()
hello
world
>>> for e in a.elements('#1-1'): print e.flatten()
hello
>>> a.elements('a[u:v=$]')[0].xml()
'<a id="1-1" u:v="$">hello</a>'
>>> a=FORM( INPUT(_type='text'), SELECT(range(1)), TEXTAREA() )
>>> for c in a.elements('input, select, textarea'): c['_disabled'] = 'disabled'
>>> a.xml()
'<form action="#" enctype="multipart/form-data" method="post"><input disabled="disabled" type="text" /><select disabled="disabled"><option value="0">0</option></select><textarea cols="40" disabled="disabled" rows="10"></textarea></form>'

Elements that are matched can also be replaced or removed by specifying a “replace” argument (note, a list of the original matching elements is still returned as usual).

Examples:

>>> a = DIV(DIV(SPAN('x', _class='abc'), DIV(SPAN('y', _class='abc'), SPAN('z', _class='abc'))))
>>> b = a.elements('span.abc', replace=P('x', _class='xyz'))
>>> print a
<div><div><p class="xyz">x</p><div><p class="xyz">x</p><p class="xyz">x</p></div></div></div>

“replace” can be a callable, which will be passed the original element and should return a new element to replace it.

Examples:

>>> a = DIV(DIV(SPAN('x', _class='abc'), DIV(SPAN('y', _class='abc'), SPAN('z', _class='abc'))))
>>> b = a.elements('span.abc', replace=lambda el: P(el[0], _class='xyz'))
>>> print a
<div><div><p class="xyz">x</p><div><p class="xyz">y</p><p class="xyz">z</p></div></div></div>

If replace=None, matching elements will be removed completely.

Examples:

>>> a = DIV(DIV(SPAN('x', _class='abc'), DIV(SPAN('y', _class='abc'), SPAN('z', _class='abc'))))
>>> b = a.elements('span', find='y', replace=None)
>>> print a
<div><div><span class="abc">x</span><div><span class="abc">z</span></div></div></div>

If a “find_text” argument is specified, elements will be searched for text components that match find_text, and any matching text components will be replaced (find_text is ignored if “replace” is not also specified). Like the “find” argument, “find_text” can be a string or a compiled regex.

Examples:

>>> a = DIV(DIV(SPAN('x', _class='abc'), DIV(SPAN('y', _class='abc'), SPAN('z', _class='abc'))))
>>> b = a.elements(find_text=re.compile('x|y|z'), replace='hello')
>>> print a
<div><div><span class="abc">hello</span><div><span class="abc">hello</span><span class="abc">hello</span></div></div></div>

If other attributes are specified along with find_text, then only components that match the specified attributes will be searched for find_text.

Examples:

>>> a = DIV(DIV(SPAN('x', _class='abc'), DIV(SPAN('y', _class='efg'), SPAN('z', _class='abc'))))
>>> b = a.elements('span.efg', find_text=re.compile('x|y|z'), replace='hello')
>>> print a
<div><div><span class="abc">x</span><div><span class="efg">hello</span><span class="abc">z</span></div></div></div>

flatten(render=None)[source]¶

Returns the text stored by the DIV object rendered by the render function the render function must take text, tagname, and attributes render=None is equivalent to render=lambda text, tag, attr: text

Examples:

>>> markdown = lambda text,tag=None,attributes={}:                         {None: re.sub('\s+',' ',text),                          'h1':'#'+text+'\n\n',                          'p':text+'\n'}.get(tag,text)
>>> a=TAG('<h1>Header</h1><p>this is a     test</p>')
>>> a.flatten(markdown)
'#Header\n\nthis is a test\n'

insert(i, value)[source]¶

List-style inserting of components

Examples:

>>> a=DIV()
>>> a.insert(0,SPAN('x'))
>>> print a
<div><span>x</span></div>

regex_attr = <_sre.SRE_Pattern object>¶

regex_class = <_sre.SRE_Pattern object>¶

regex_id = <_sre.SRE_Pattern object>¶

regex_tag = <_sre.SRE_Pattern object>¶

sibling(*args, **kargs)[source]¶

Finds the first sibling component that match the supplied argument list and attribute dictionary, or None if nothing could be found

siblings(*args, **kargs)[source]¶

Finds all sibling components that match the supplied argument list and attribute dictionary, or None if nothing could be found

tag = 'div'¶

update(**kargs)[source]¶

dictionary like updating of the tag attributes

xml()[source]¶

generates the xml for this component.

class gluon.html.EM(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'em'¶

class gluon.html.EMBED(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'embed/'¶

class gluon.html.FIELDSET(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'fieldset'¶

class gluon.html.FORM(*components, **attributes)[source]¶

Bases: gluon.html.DIV

Examples:

>>> from validators import IS_NOT_EMPTY
>>> form=FORM(INPUT(_name="test", requires=IS_NOT_EMPTY()))
>>> form.xml()
'<form action="#" enctype="multipart/form-data" method="post"><input name="test" type="text" /></form>'

a FORM is container for INPUT, TEXTAREA, SELECT and other helpers

form has one important method:

form.accepts(request.vars, session)

if form is accepted (and all validators pass) form.vars contains the accepted vars, otherwise form.errors contains the errors. in case of errors the form is modified to present the errors to the user.

REDIRECT_JS = "window.location='%s';return false"¶

accepts(request_vars, session=None, formname='default', keepvalues=False, onvalidation=None, hideerror=False, **kwargs)[source]¶

kwargs is not used but allows to specify the same interface for FORM and SQLFORM

add_button(value, url, _class=None)[source]¶

as_dict(flat=False, sanitize=True)[source]¶

EXPERIMENTAL

Sanitize is naive. It should catch any unsafe value for client retrieval.

as_json(sanitize=True)[source]¶

as_xml(sanitize=True)[source]¶

as_yaml(sanitize=True)[source]¶

assert_status(status, request_vars)[source]¶

static confirm(text='OK', buttons=None, hidden=None)[source]¶

hidden_fields()[source]¶

process(**kwargs)[source]¶

Perform the .validate() method but returns the form

Usage in controllers:

# directly on return
def action():
    #some code here
    return dict(form=FORM(...).process(...))

You can use it with FORM, SQLFORM or FORM based plugins:

# response.flash messages
def action():
    form = SQLFORM(db.table).process(message_onsuccess='Sucess!')
    return dict(form=form)

# callback function
# callback receives True or False as first arg, and a list of args.
def my_callback(status, msg):
    response.flash = "Success! "+msg if status else "Errors occured"

# after argument can be 'flash' to response.flash messages
# or a function name to use as callback or None to do nothing.
def action():
    return dict(form=SQLFORM(db.table).process(onsuccess=my_callback)

tag = 'form'¶

validate(**kwargs)[source]¶

This function validates the form, you can use it instead of directly form.accepts.

Usage: In controller:

def action():
    form=FORM(INPUT(_name="test", requires=IS_NOT_EMPTY()))
    form.validate() #you can pass some args here - see below
    return dict(form=form)

This can receive a bunch of arguments

onsuccess = ‘flash’ - will show message_onsuccess in response.flash

None - will do nothing can be a function (lambda form: pass)

onfailure = ‘flash’ - will show message_onfailure in response.flash

None - will do nothing can be a function (lambda form: pass)

onchange = ‘flash’ - will show message_onchange in response.flash

None - will do nothing can be a function (lambda form: pass)

message_onsuccess message_onfailure message_onchange next = where to redirect in case of success any other kwargs will be passed for form.accepts(...)

xml()[source]¶

class gluon.html.H1(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'h1'¶

class gluon.html.H2(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'h2'¶

class gluon.html.H3(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'h3'¶

class gluon.html.H4(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'h4'¶

class gluon.html.H5(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'h5'¶

class gluon.html.H6(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'h6'¶

class gluon.html.HEAD(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'head'¶

class gluon.html.HR(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'hr/'¶

class gluon.html.HTML(*components, **attributes)[source]¶

Bases: gluon.html.DIV

There are four predefined document type definitions. They can be specified in the ‘doctype’ parameter:

• ‘strict’ enables strict doctype
• ‘transitional’ enables transitional doctype (default)
• ‘frameset’ enables frameset doctype
• ‘html5’ enables HTML 5 doctype
• any other string will be treated as user’s own doctype

‘lang’ parameter specifies the language of the document. Defaults to ‘en’.

See also DIV

frameset = '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">\n'¶

html5 = '<!DOCTYPE HTML>\n'¶

strict = '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">\n'¶

tag = 'html'¶

transitional = '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">\n'¶

xml()[source]¶

class gluon.html.I(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'i'¶

class gluon.html.IFRAME(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'iframe'¶

class gluon.html.IMG(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'img/'¶

class gluon.html.INPUT(*components, **attributes)[source]¶

Bases: gluon.html.DIV

INPUT Component

Takes two special attributes value= and requires=.

Parameters:	value – used to pass the initial value for the input field. value differs from _value because it works for checkboxes, radio, textarea and select/option too. For a checkbox value should be ‘’ or ‘on’. For a radio or select/option value should be the _value of the checked/selected item. requires – should be None, or a validator or a list of validators for the value of the field.

Examples:

>>> INPUT(_type='text', _name='name', value='Max').xml()
'<input name="name" type="text" value="Max" />'

>>> INPUT(_type='checkbox', _name='checkbox', value='on').xml()
'<input checked="checked" name="checkbox" type="checkbox" value="on" />'

>>> INPUT(_type='radio', _name='radio', _value='yes', value='yes').xml()
'<input checked="checked" name="radio" type="radio" value="yes" />'

>>> INPUT(_type='radio', _name='radio', _value='no', value='yes').xml()
'<input name="radio" type="radio" value="no" />'

tag = 'input/'¶

xml()[source]¶

class gluon.html.LABEL(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'label'¶

class gluon.html.LEGEND(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'legend'¶

class gluon.html.LI(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'li'¶

class gluon.html.LINK(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'link/'¶

class gluon.html.OL(*components, **attributes)[source]¶

Bases: gluon.html.UL

tag = 'ol'¶

class gluon.html.UL(*components, **attributes)[source]¶

Bases: gluon.html.DIV

UL Component.

If subcomponents are not LI-components they will be wrapped in a LI

tag = 'ul'¶

class gluon.html.MARKMIN(text, extra=None, allowed=None, sep='p', url=None, environment=None, latex='google', autolinks='default', protolinks='default', class_prefix='', id_prefix='markmin_', **kwargs)[source]¶

Bases: gluon.html.XmlComponent

For documentation: http://web2py.com/examples/static/markmin.html

flatten()[source]¶

xml()[source]¶

class gluon.html.MENU(data, **args)[source]¶

Bases: gluon.html.DIV

Used to build menus

Parameters:	_class – defaults to ‘web2py-menu web2py-menu-vertical’ ul_class – defaults to ‘web2py-menu-vertical’ li_class – defaults to ‘web2py-menu-expand’ li_first – defaults to ‘web2py-menu-first’ li_last – defaults to ‘web2py-menu-last’

Use like:

menu = MENU([['name', False, URL(...), [submenu]], ...])
{{=menu}}

serialize(data, level=0)[source]¶

serialize_mobile(data, select=None, prefix='')[source]¶

tag = 'ul'¶

xml()[source]¶

class gluon.html.META(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'meta/'¶

class gluon.html.OBJECT(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'object'¶

class gluon.html.OPTION(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'option'¶

class gluon.html.P(*components, **attributes)[source]¶

Bases: gluon.html.DIV

Will replace \n by <br /> if the cr2br attribute is provided.

see also DIV

tag = 'p'¶

xml()[source]¶

class gluon.html.PRE(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'pre'¶

class gluon.html.SCRIPT(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'script'¶

xml()[source]¶

class gluon.html.OPTGROUP(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'optgroup'¶

class gluon.html.SELECT(*components, **attributes)[source]¶

Bases: gluon.html.INPUT

Examples:

>>> from validators import IS_IN_SET
>>> SELECT('yes', 'no', _name='selector', value='yes',
...    requires=IS_IN_SET(['yes', 'no'])).xml()
'<select name="selector"><option selected="selected" value="yes">yes</option><option value="no">no</option></select>'

tag = 'select'¶

class gluon.html.SPAN(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'span'¶

class gluon.html.STRONG(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'strong'¶

class gluon.html.STYLE(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'style'¶

xml()[source]¶

class gluon.html.TABLE(*components, **attributes)[source]¶

Bases: gluon.html.DIV

TABLE Component.

If subcomponents are not TR/TBODY/THEAD/TFOOT-components they will be wrapped in a TR

tag = 'table'¶

gluon.html.TAG¶

TAG factory

Examples:

>>> print TAG.first(TAG.second('test'), _key = 3)
<first key="3"><second>test</second></first>

class gluon.html.TD(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'td'¶

class gluon.html.TEXTAREA(*components, **attributes)[source]¶

Bases: gluon.html.INPUT

Examples:

TEXTAREA(_name='sometext', value='blah ' * 100, requires=IS_NOT_EMPTY())

‘blah blah blah ...’ will be the content of the textarea field.

tag = 'textarea'¶

class gluon.html.TH(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'th'¶

class gluon.html.THEAD(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'thead'¶

class gluon.html.TBODY(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'tbody'¶

class gluon.html.TFOOT(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'tfoot'¶

class gluon.html.TITLE(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'title'¶

class gluon.html.TR(*components, **attributes)[source]¶

Bases: gluon.html.DIV

TR Component.

If subcomponents are not TD/TH-components they will be wrapped in a TD

tag = 'tr'¶

class gluon.html.TT(*components, **attributes)[source]¶

Bases: gluon.html.DIV

tag = 'tt'¶

gluon.html.URL(a=None, c=None, f=None, r=None, args=None, vars=None, anchor='', extension=None, env=None, hmac_key=None, hash_vars=True, salt=None, user_signature=None, scheme=None, host=None, port=None, encode_embedded_slash=False, url_encode=True, language=None)[source]¶

generates a url ‘/a/c/f’ corresponding to application a, controller c and function f. If r=request is passed, a, c, f are set, respectively, to r.application, r.controller, r.function.

The more typical usage is:

URL(‘index’)

that generates a url for the index function within the present application and controller.

Parameters:

a – application (default to current if r is given) c – controller (default to current if r is given) f – function (default to current if r is given) r – request (optional) args – any arguments (optional). Additional “path” elements vars – any variables (optional). Querystring elements anchor – anchorname, without # (optional) extension – force an extension hmac_key – key to use when generating hmac signature (optional) hash_vars – which of the vars to include in our hmac signature True (default) - hash all vars, False - hash none of the vars, iterable - hash only the included vars [‘key1’,’key2’] salt – salt hashing with this string user_signature – signs automatically the URL in such way that only the user can access the URL (use with URL.verify or auth.requires_signature()) scheme – URI scheme (True, ‘http’ or ‘https’, etc); forces absolute URL (optional) host – string to force absolute URL with host (True means http_host) port – optional port number (forces absolute URL) encode_embedded_slash – encode slash characters included in args url_encode – encode characters included in vars

Raises:

SyntaxError – when no application, controller or function is available or when a CRLF is found in the generated url

Examples:

>>> str(URL(a='a', c='c', f='f', args=['x', 'y', 'z'],
...     vars={'p':1, 'q':2}, anchor='1'))
'/a/c/f/x/y/z?p=1&q=2#1'

>>> str(URL(a='a', c='c', f='f', args=['x', 'y', 'z'],
...     vars={'p':(1,3), 'q':2}, anchor='1'))
'/a/c/f/x/y/z?p=1&p=3&q=2#1'

>>> str(URL(a='a', c='c', f='f', args=['x', 'y', 'z'],
...     vars={'p':(3,1), 'q':2}, anchor='1'))
'/a/c/f/x/y/z?p=3&p=1&q=2#1'

>>> str(URL(a='a', c='c', f='f', anchor='1+2'))
'/a/c/f#1%2B2'

>>> str(URL(a='a', c='c', f='f', args=['x', 'y', 'z'],
...     vars={'p':(1,3), 'q':2}, anchor='1', hmac_key='key'))
'/a/c/f/x/y/z?p=1&p=3&q=2&_signature=a32530f0d0caa80964bb92aad2bedf8a4486a31f#1'

>>> str(URL(a='a', c='c', f='f', args=['w/x', 'y/z']))
'/a/c/f/w/x/y/z'

>>> str(URL(a='a', c='c', f='f', args=['w/x', 'y/z'], encode_embedded_slash=True))
'/a/c/f/w%2Fx/y%2Fz'

>>> str(URL(a='a', c='c', f='f', args=['%(id)d'], url_encode=False))
'/a/c/f/%(id)d'

>>> str(URL(a='a', c='c', f='f', args=['%(id)d'], url_encode=True))
'/a/c/f/%25%28id%29d'

>>> str(URL(a='a', c='c', f='f', vars={'id' : '%(id)d' }, url_encode=False))
'/a/c/f?id=%(id)d'

>>> str(URL(a='a', c='c', f='f', vars={'id' : '%(id)d' }, url_encode=True))
'/a/c/f?id=%25%28id%29d'

>>> str(URL(a='a', c='c', f='f', anchor='%(id)d', url_encode=False))
'/a/c/f#%(id)d'

>>> str(URL(a='a', c='c', f='f', anchor='%(id)d', url_encode=True))
'/a/c/f#%25%28id%29d'

class gluon.html.XHTML(*components, **attributes)[source]¶

Bases: gluon.html.DIV

This is XHTML version of the HTML helper.

There are three predefined document type definitions. They can be specified in the ‘doctype’ parameter:

• ‘strict’ enables strict doctype
• ‘transitional’ enables transitional doctype (default)
• ‘frameset’ enables frameset doctype
• any other string will be treated as user’s own doctype

‘lang’ parameter specifies the language of the document and the xml document. Defaults to ‘en’.

‘xmlns’ parameter specifies the xml namespace. Defaults to ‘http://www.w3.org/1999/xhtml‘.

See also DIV

frameset = '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">\n'¶

strict = '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">\n'¶

tag = 'html'¶

transitional = '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\n'¶

xml()[source]¶

xmlns = 'http://www.w3.org/1999/xhtml'¶

class gluon.html.XML(text, sanitize=False, permitted_tags=['a', 'b', 'blockquote', 'br/', 'i', 'li', 'ol', 'ul', 'p', 'cite', 'code', 'pre', 'img/', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'table', 'tr', 'td', 'div', 'strong', 'span'], allowed_attributes={'a': ['href', 'title', 'target'], 'td': ['colspan'], 'blockquote': ['type'], 'img': ['src', 'alt']})[source]¶

Bases: gluon.html.XmlComponent

use it to wrap a string that contains XML/HTML so that it will not be escaped by the template

Examples:

>>> XML('<h1>Hello</h1>').xml()
'<h1>Hello</h1>'

elements(*args, **kargs)[source]¶

to be considered experimental since the behavior of this method is questionable another option could be TAG(self.text).elements(*args,**kwargs)

flatten(render=None)[source]¶

returns the text stored by the XML object rendered by the render function

xml()[source]¶

gluon.html.xmlescape(data, quote=True)[source]¶

Returns an escaped string of the provided data

Parameters:	data – the data to be escaped quote – optional (default False)

gluon.html.embed64(filename=None, file=None, data=None, extension='image/gif')[source]¶

helper to encode the provided (binary) data into base64.

Parameters:	filename – if provided, opens and reads this file in ‘rb’ mode file – if provided, reads this file data – if provided, uses the provided data

HTTP statuses helpers¶

exception gluon.http.HTTP(status, body='', cookies=None, **headers)[source]¶

Bases: exceptions.Exception

Raises an HTTP response

Parameters:

status – usually an integer. If it’s a well known status code, the ERROR message will be automatically added. A string can also be passed as 510 Foo Bar and in that case the status code and the error message will be parsed accordingly body – what to return as body. If left as is, will return the error code and the status message in the body itself cookies – pass cookies along (usually not needed) headers – pass headers as usual dict mapping

cookies2headers(cookies)[source]¶

message¶

compose a message describing this exception

“status defined_status [web2py_error]”

message elements that are not defined are omitted

to(responder, env=None)[source]¶

gluon.http.redirect(location='', how=303, client_side=False, headers=None)[source]¶

Raises a redirect (303)

Parameters:	location – the url where to redirect how – what HTTP status code to use when redirecting client_side – if set to True, it triggers a reload of the entire page when the fragment has been loaded as a component

Translation system¶

class gluon.languages.translator(langpath, http_accept_language)[source]¶

Bases: object

This class is instantiated by gluon.compileapp.build_environment as the T object

Example

T.force(None) # turns off translation T.force(‘fr, it’) # forces web2py to translate using fr.py or it.py

T(“Hello World”) # translates “Hello World” using the selected file

Note

• there is no need to force since, by default, T uses http_accept_language to determine a translation file.
• en and en-en are considered different languages!
• if language xx-yy is not found force() probes other similar languages using such algorithm: xx-yy.py -> xx.py -> xx-yy*.py -> xx*.py

M(message, symbols={}, language=None, lazy=None, filter=None, ftag=None, ns=None)[source]¶

Gets cached translated markmin-message with inserted parametes if lazy==True lazyT object is returned

apply_filter(message, symbols={}, filter=None, ftag=None)[source]¶

force(*languages)[source]¶

Selects language(s) for translation

if a list of languages is passed as a parameter, the first language from this list that matches the ones from the possible_languages dictionary will be selected

default language will be selected if none of them matches possible_languages.

get_possible_languages()[source]¶

Gets list of all possible languages for current application

get_possible_languages_info(lang=None)[source]¶

Returns info for selected language or dictionary with all possible languages info from APP/languages/*.py It Returns:

• a tuple containing:

  langcode, langname, langfile_mtime,
  pluraldict_fname, pluraldict_mtime,
  prules_langcode, nplurals,
  get_plural_id, construct_plural_form
  
  or None
  

• if lang is NOT defined a dictionary with all possible languages:

  { langcode(from filename):
      ( langcode,        # language code from !langcode!
        langname,
            # language name in national spelling from !langname!
        langfile_mtime,  # m_time of language file
        pluraldict_fname,# name of plural dictionary file or None (when default.py is not exist)
        pluraldict_mtime,# m_time of plural dictionary file or 0 if file is not exist
        prules_langcode, # code of plural rules language or 'default'
        nplurals,        # nplurals for current language
        get_plural_id,   # get_plural_id() for current language
        construct_plural_form) # construct_plural_form() for current language
  }
  

Parameters:	lang (str) – language

get_t(message, prefix='')[source]¶

Use ## to add a comment into a translation string the comment can be useful do discriminate different possible translations for the same string (for example different locations):

T(' hello world ') -> ' hello world '
T(' hello world ## token') -> ' hello world '
T('hello ## world## token') -> 'hello ## world'

the ## notation is ignored in multiline strings and strings that start with ##. This is needed to allow markmin syntax to be translated

params_substitution(message, symbols)[source]¶

Substitutes parameters from symbols into message using %. also parse %%{} placeholders for plural-forms processing.

Returns:	string with parameters

Note

symbols MUST BE OR tuple OR dict of parameters!

plural(word, n)[source]¶

Gets plural form of word for number n invoked from T()/T.M() in %%{} tag

Note

“word” MUST be defined in current language (T.accepted_language)

Parameters:	word (str) – word in singular n (numeric) – number plural form created for
Returns:	word – word in appropriate singular/plural form
Return type:	str

set_current_languages(*languages)[source]¶

Sets current AKA “default” languages Setting one of this languages makes the force() function to turn translation off

translate(message, symbols)[source]¶

Gets cached translated message with inserted parameters(symbols)

gluon.languages.findT(path, language='en')[source]¶

Note

Must be run by the admin app

gluon.languages.update_all_languages(application_path)[source]¶

Note

Must be run by the admin app

The gluon wsgi application¶

gluon.main.wsgibase(environ, responder)[source]¶

The gluon wsgi application. The first function called when a page is requested (static or dynamic). It can be called by paste.httpserver or by apache mod_wsgi (or any WSGI-compatible server).

• fills request with info
• the environment variables, replacing ‘.’ with ‘_’
• adds web2py path and version info
• compensates for fcgi missing path_info and query_string
• validates the path in url

The url path must be either:

1. for static pages:

• /<application>/static/<file>

2. for dynamic pages:

• /<application>[/<controller>[/<function>[/<sub>]]][.<extension>]

The naming conventions are:

• application, controller, function and extension may only contain [a-zA-Z0-9_]
• file and sub may also contain ‘-‘, ‘=’, ‘.’ and ‘/’

gluon.main.save_password(password, port)[source]¶

Used by main() to save the password in the parameters_port.py file.

gluon.main.appfactory(wsgiapp=<function wsgibase>, logfilename='httpserver.log', profiler_dir=None, profilerfilename=None)[source]¶

generates a wsgi application that does logging and profiling and calls wsgibase

Parameters:	wsgiapp – the base application logfilename – where to store apache-compatible requests log profiler_dir – where to store profile files

class gluon.main.HttpServer(ip='127.0.0.1', port=8000, password='', pid_filename='httpserver.pid', log_filename='httpserver.log', profiler_dir=None, ssl_certificate=None, ssl_private_key=None, ssl_ca_certificate=None, min_threads=None, max_threads=None, server_name=None, request_queue_size=5, timeout=10, socket_timeout=1, shutdown_timeout=None, path=None, interfaces=None)[source]¶

Bases: object

the web2py web server (Rocket)

start()[source]¶

start the web server

stop(stoplogging=False)[source]¶

stop cron and the web server

Useful regexes¶

Generates names for cache and session files¶

gluon.recfile.exists(filename, path=None)[source]¶

gluon.recfile.generate(filename, depth=2, base=512)[source]¶

gluon.recfile.open(filename, mode='r', path=None)[source]¶

gluon.recfile.remove(filename, path=None)[source]¶

gluon.recfile.test()[source]¶

Restricted environment to execute application’s code¶

exception gluon.restricted.RestrictedError(layer='', code='', output='', environment=None)[source]¶

Bases: exceptions.Exception

Class used to wrap an exception that occurs in the restricted environment below. The traceback is used to log the exception and generate a ticket.

load(request, app, ticket_id)[source]¶

Loads a logged exception.

log(request)[source]¶

Logs the exception.

gluon.restricted.restricted(code, environment=None, layer='Unknown')[source]¶

Runs code in environment and returns the output. If an exception occurs in code it raises a RestrictedError containing the traceback. Layer is passed to RestrictedError to identify where the error occurred.

class gluon.restricted.TicketStorage(db=None, tablename='web2py_ticket')[source]¶

Bases: gluon.storage.Storage

Defines the ticket object and the default values of its members (None)

load(request, app, ticket_id)[source]¶

store(request, ticket_id, ticket_data)[source]¶

Stores the ticket. It will figure out if this must be on disk or in db

gluon.restricted.compile2(code, layer)[source]¶

The +'\n' is necessary else compile fails when code ends in a comment.

Cross-site scripting (XSS) defense¶

gluon.sanitizer.sanitize(text, permitted_tags=['a', 'b', 'blockquote', 'br/', 'i', 'li', 'ol', 'ul', 'p', 'cite', 'code', 'pre', 'img/', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'table', 'tbody', 'thead', 'tfoot', 'tr', 'td', 'div', 'strong', 'span'], allowed_attributes={'a': ['href', 'title'], 'td': ['colspan'], 'blockquote': ['type'], 'img': ['src', 'alt']}, escape=True)[source]¶

Background processes made simple¶

class gluon.scheduler.JobGraph(db, job_name)[source]¶

Bases: object

Experimental: with JobGraph you can specify dependencies amongs tasks

add_deps(task_parent, task_child)[source]¶

Creates a dependency between task_parent and task_child

validate(job_name)[source]¶

Validates if all tasks job_name can be completed, i.e. there are no mutual dependencies among tasks. Commits at the end if successfull, or it rollbacks the entire transaction. Handle with care!

class gluon.scheduler.MetaScheduler[source]¶

Bases: threading.Thread

Base class documenting scheduler’s base methods

async(task)[source]¶

Starts the background process

Parameters:	task – a Task object
Returns:	containing: ('ok',result,output) ('error',exception,None) ('timeout',None,None) ('terminated',None,None)
Return type:	tuple

die()[source]¶

Forces termination of the worker process along with any running task

give_up()[source]¶

Waits for any running task to be executed, then exits the worker process

loop()[source]¶

Main loop, fetching tasks and starting executor’s background processes

pop_task()[source]¶

Fetches a task ready to be executed

report_task(task, task_report)[source]¶

Creates a task report

run()[source]¶

This is executed by the main thread to send heartbeats

send_heartbeat(counter)[source]¶

sleep()[source]¶

start_heartbeats()[source]¶

terminate_process()[source]¶

Terminates any running tasks (internal use only)

class gluon.scheduler.Scheduler(db, tasks=None, migrate=True, worker_name=None, group_names=None, heartbeat=3, max_empty_runs=0, discard_results=False, utc_time=False)[source]¶

Bases: gluon.scheduler.MetaScheduler

Scheduler object

Parameters:

db – DAL connection where Scheduler will create its tables tasks (dict) – either a dict containing name–>func or None. If None, functions will be searched in the environment migrate (bool) – turn migration on/off for the Scheduler’s tables worker_name (str) – force worker_name to identify each process. Leave it to None to autoassign a name (hostname#pid) group_names (list) – process tasks belonging to this group defaults to [‘main’] if nothing gets passed heartbeat (int) – how many seconds the worker sleeps between one execution and the following one. Indirectly sets how many seconds will pass between checks for new tasks max_empty_runs (int) – how many loops are allowed to pass without processing any tasks before exiting the process. 0 to keep always the process alive discard_results (bool) – Scheduler stores executions’s details into the scheduler_run table. By default, only if there is a result the details are kept. Turning this to True means discarding results even for tasks that return something utc_time (bool) – do all datetime calculations assuming UTC as the timezone. Remember to pass start_time and stop_time to tasks accordingly

adj_hibernation()[source]¶

Used to increase the “sleep” interval for DISABLED workers

assign_tasks(db)[source]¶

Assigns task to workers, that can then pop them from the queue

Deals with group_name(s) logic, in order to assign linearly tasks to available workers for those groups

being_a_ticker()[source]¶

Elects a TICKER process that assigns tasks to available workers. Does its best to elect a worker that is not busy processing other tasks to allow a proper distribution of tasks among all active workers ASAP

define_tables(db, migrate)[source]¶

Defines Scheduler tables structure

disable(group_names=None, limit=None, worker_name=None)[source]¶

Sets DISABLED on the workers processing group_names tasks. A DISABLED worker will be kept alive but it won’t be able to process any waiting tasks, essentially putting it to sleep. By default, all group_names of Scheduler’s instantation are selected

get_workers(only_ticker=False)[source]¶

Returns a dict holding worker_name : {**columns} representing all “registered” workers only_ticker returns only the workers running as a TICKER, if there are any

kill(group_names=None, limit=None, worker_name=None)[source]¶

Sets KILL as worker status. The worker will be killed even if it’s processing a task.

loop(worker_name=None)[source]¶

Main loop

This works basically as a neverending loop that:

• checks if the worker is ready to process tasks (is not DISABLED)
• pops a task from the queue
• if there is a task:
  • spawns the executor background process
  • waits for the process to be finished
  • sleeps heartbeat seconds
• if there is not a task:
  • checks for max_empty_runs
  • sleeps heartbeat seconds

now()[source]¶

Shortcut that fetches current time based on UTC preferences

pop_task(db)[source]¶

Grabs a task ready to be executed from the queue

queue_task(function, pargs=[], pvars={}, **kwargs)[source]¶

Queue tasks. This takes care of handling the validation of all parameters

Parameters:	function – the function (anything callable with a __name__) pargs – “raw” args to be passed to the function. Automatically jsonified. pvars – “raw” kwargs to be passed to the function. Automatically jsonified kwargs – all the parameters available (basically, every scheduler_task column). If args and vars are here, they should be jsonified already, and they will override pargs and pvars
Returns:	a dict just as a normal validate_and_insert(), plus a uuid key holding the uuid of the queued task. If validation is not passed ( i.e. some parameters are invalid) both id and uuid will be None, and you’ll get an “error” dict holding the errors found.

report_task(task, task_report)[source]¶

Takes care of storing the result according to preferences and deals with logic for repeating tasks

resume(group_names=None, limit=None, worker_name=None)[source]¶

Wakes a worker up (it will be able to process queued tasks)

send_heartbeat(counter)[source]¶

This function is vital for proper coordination among available workers. It:

• sends the heartbeat

• elects a ticker among available workers (the only process that

  effectively dispatch tasks to workers)

• deals with worker’s statuses

• does “housecleaning” for dead workers

• triggers tasks assignment to workers

set_requirements(scheduler_task)[source]¶

Called to set defaults for lazy_tables connections

set_worker_status(group_names=None, action='ACTIVE', exclude=None, limit=None, worker_name=None)[source]¶

Internal function to set worker’s status

sleep()[source]¶

Calculates the number of seconds to sleep according to worker’s status and heartbeat parameter

stop_task(ref)[source]¶

Shortcut for task termination.

If the task is RUNNING it will terminate it, meaning that status will be set as FAILED.

If the task is QUEUED, its stop_time will be set as to “now”,

the enabled flag will be set to False, and the status to STOPPED

Parameters:	ref – can be an integer : lookup will be done by scheduler_task.id a string : lookup will be done by scheduler_task.uuid
Returns:	1 if task was stopped (meaning an update has been done) None if task was not found, or if task was not RUNNING or QUEUED

Note

Experimental

task_status(ref, output=False)[source]¶

Retrieves task status and optionally the result of the task

Parameters:	ref – can be an integer : lookup will be done by scheduler_task.id a string : lookup will be done by scheduler_task.uuid a Query : lookup as you wish, e.g. db.scheduler_task.task_name == 'test1' output (bool) – if True, fetch also the scheduler_run record
Returns:	a single Row object, for the last queued task. If output == True, returns also the last scheduler_run record. The scheduler_run record is fetched by a left join, so it can have all fields == None

terminate(group_names=None, limit=None, worker_name=None)[source]¶

Sets TERMINATE as worker status. The worker will wait for any currently running tasks to be executed and then it will exit gracefully

update_dependencies(db, task_id)[source]¶

wrapped_assign_tasks(db)[source]¶

Commodity function to call assign_tasks and trap exceptions If an exception is raised, assume it happened because of database contention and retries assign_task after 0.5 seconds

wrapped_pop_task()[source]¶

Commodity function to call pop_task and trap exceptions If an exception is raised, assume it happened because of database contention and retries pop_task after 0.5 seconds

wrapped_report_task(task, task_report)[source]¶

Commodity function to call report_task and trap exceptions If an exception is raised, assume it happened because of database contention and retries pop_task after 0.5 seconds

class gluon.scheduler.TYPE(myclass=<type 'list'>, parse=False)[source]¶

Bases: object

Validator that checks whether field is valid json and validates its type. Used for args and vars of the scheduler_task table

class gluon.scheduler.Task(app, function, timeout, args='[]', vars='{}', **kwargs)[source]¶

Bases: object

Defines a “task” object that gets passed from the main thread to the executor’s one

class gluon.scheduler.TaskReport(status, result=None, output=None, tb=None)[source]¶

Bases: object

Defines a “task report” object that gets passed from the executor’s thread to the main one

gluon.scheduler.demo_function(*argv, **kwargs)[source]¶

test function

gluon.scheduler.executor(queue, task, out)[source]¶

The function used to execute tasks in the background process

gluon.scheduler.main()[source]¶

allows to run worker without python web2py.py .... by simply:

python gluon/scheduler.py