Merge pull request #396 from niphlod/docs/html
sphinx-compatible docstrings
This commit is contained in:
mdipierro
+303
-233
@@ -2,9 +2,12 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
|
||||
"""
|
||||
This file is part of the web2py Web Framework
|
||||
Copyrighted by Massimo Di Pierro <mdipierro@cs.depaul.edu>
|
||||
License: LGPLv3 (http://www.gnu.org/licenses/lgpl.html)
|
||||
| This file is part of the web2py Web Framework
|
||||
| Copyrighted by Massimo Di Pierro <mdipierro@cs.depaul.edu>
|
||||
| License: LGPLv3 (http://www.gnu.org/licenses/lgpl.html)
|
||||
|
||||
Template helpers
|
||||
--------------------------------------------
|
||||
"""
|
||||
|
||||
import cgi
|
||||
@@ -109,10 +112,11 @@ __all__ = [
|
||||
|
||||
def xmlescape(data, quote=True):
|
||||
"""
|
||||
returns an escaped string of the provided data
|
||||
Returns an escaped string of the provided data
|
||||
|
||||
:param data: the data to be escaped
|
||||
:param quote: optional (default False)
|
||||
Args:
|
||||
data: the data to be escaped
|
||||
quote: optional (default False)
|
||||
"""
|
||||
|
||||
# first try the xml function
|
||||
@@ -164,80 +168,92 @@ def URL(
|
||||
language=None,
|
||||
):
|
||||
"""
|
||||
generate a URL
|
||||
|
||||
example::
|
||||
|
||||
>>> 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'
|
||||
|
||||
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(r=request, f='index') that generates a url for the index function
|
||||
URL('index')
|
||||
|
||||
that generates a url for the index function
|
||||
within the present application and controller.
|
||||
|
||||
:param a: application (default to current if r is given)
|
||||
:param c: controller (default to current if r is given)
|
||||
:param f: function (default to current if r is given)
|
||||
:param r: request (optional)
|
||||
:param args: any arguments (optional)
|
||||
:param vars: any variables (optional)
|
||||
:param anchor: anchorname, without # (optional)
|
||||
:param hmac_key: key to use when generating hmac signature (optional)
|
||||
:param 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']
|
||||
:param scheme: URI scheme (True, 'http' or 'https', etc); forces absolute URL (optional)
|
||||
:param host: string to force absolute URL with host (True means http_host)
|
||||
:param port: optional port number (forces absolute URL)
|
||||
Args:
|
||||
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'
|
||||
|
||||
|
||||
|
||||
|
||||
:raises SyntaxError: when no application, controller or function is
|
||||
available
|
||||
:raises SyntaxError: when a CRLF is found in the generated url
|
||||
"""
|
||||
|
||||
from rewrite import url_out # done here in case used not-in web2py
|
||||
@@ -528,7 +544,7 @@ class XML(XmlComponent):
|
||||
use it to wrap a string that contains XML/HTML so that it will not be
|
||||
escaped by the template
|
||||
|
||||
example:
|
||||
Examples:
|
||||
|
||||
>>> XML('<h1>Hello</h1>').xml()
|
||||
'<h1>Hello</h1>'
|
||||
@@ -564,19 +580,19 @@ class XML(XmlComponent):
|
||||
},
|
||||
):
|
||||
"""
|
||||
:param text: the XML text
|
||||
:param sanitize: sanitize text using the permitted tags and allowed
|
||||
attributes (default False)
|
||||
:param permitted_tags: list of permitted tags (default: simple list of
|
||||
tags)
|
||||
:param allowed_attributes: dictionary of allowed attributed (default
|
||||
for A, IMG and BlockQuote).
|
||||
The key is the tag; the value is a list of allowed attributes.
|
||||
Args:
|
||||
text: the XML text
|
||||
sanitize: sanitize text using the permitted tags and allowed
|
||||
attributes (default False)
|
||||
permitted_tags: list of permitted tags (default: simple list of
|
||||
tags)
|
||||
allowed_attributes: dictionary of allowed attributed (default
|
||||
for A, IMG and BlockQuote).
|
||||
The key is the tag; the value is a list of allowed attributes.
|
||||
"""
|
||||
|
||||
if sanitize:
|
||||
text = sanitizer.sanitize(text, permitted_tags,
|
||||
allowed_attributes)
|
||||
text = sanitizer.sanitize(text, permitted_tags, allowed_attributes)
|
||||
if isinstance(text, unicode):
|
||||
text = text.encode('utf8', 'xmlcharrefreplace')
|
||||
elif not isinstance(text, str):
|
||||
@@ -620,7 +636,8 @@ class XML(XmlComponent):
|
||||
|
||||
def flatten(self, render=None):
|
||||
"""
|
||||
return the text stored by the XML object rendered by the render function
|
||||
returns the text stored by the XML object rendered
|
||||
by the `render` function
|
||||
"""
|
||||
if render:
|
||||
return render(self.text, None, {})
|
||||
@@ -628,8 +645,9 @@ class XML(XmlComponent):
|
||||
|
||||
def elements(self, *args, **kargs):
|
||||
"""
|
||||
to be considered experimental since the behavior of this method is questionable
|
||||
another options could be TAG(self.text).elements(*args,**kargs)
|
||||
to be considered experimental since the behavior of this method
|
||||
is questionable
|
||||
another option could be `TAG(self.text).elements(*args,**kwargs)`
|
||||
"""
|
||||
return []
|
||||
|
||||
@@ -653,15 +671,15 @@ class DIV(XmlComponent):
|
||||
Behaves like a dictionary regarding updating of attributes.
|
||||
Behaves like a list regarding inserting/appending components.
|
||||
|
||||
example::
|
||||
Examples:
|
||||
|
||||
>>> DIV('hello', 'world', _style='color:red;').xml()
|
||||
'<div style=\"color:red;\">helloworld</div>'
|
||||
>>> DIV('hello', 'world', _style='color:red;').xml()
|
||||
'<div style=\"color:red;\">helloworld</div>'
|
||||
|
||||
all other HTML helpers are derived from DIV.
|
||||
All other HTML helpers are derived from `DIV`.
|
||||
|
||||
_something=\"value\" attributes are transparently translated into
|
||||
something=\"value\" HTML attributes
|
||||
`_something="value"` attributes are transparently translated into
|
||||
`something="value"` HTML attributes
|
||||
"""
|
||||
|
||||
# name of the tag, subclasses should update this
|
||||
@@ -671,10 +689,12 @@ class DIV(XmlComponent):
|
||||
|
||||
def __init__(self, *components, **attributes):
|
||||
"""
|
||||
:param *components: any components that should be nested in this element
|
||||
:param **attributes: any attributes you want to give to this element
|
||||
Args:
|
||||
components: any components that should be nested in this element
|
||||
attributes: any attributes you want to give to this element
|
||||
|
||||
:raises SyntaxError: when a stand alone tag receives components
|
||||
Raises:
|
||||
SyntaxError: when a stand alone tag receives components
|
||||
"""
|
||||
|
||||
if self.tag[-1:] == '/' and components:
|
||||
@@ -705,6 +725,8 @@ class DIV(XmlComponent):
|
||||
"""
|
||||
list style appending of components
|
||||
|
||||
Examples:
|
||||
|
||||
>>> a=DIV()
|
||||
>>> a.append(SPAN('x'))
|
||||
>>> print a
|
||||
@@ -717,7 +739,9 @@ class DIV(XmlComponent):
|
||||
|
||||
def insert(self, i, value):
|
||||
"""
|
||||
list style inserting of components
|
||||
List-style inserting of components
|
||||
|
||||
Examples:
|
||||
|
||||
>>> a=DIV()
|
||||
>>> a.insert(0,SPAN('x'))
|
||||
@@ -731,12 +755,12 @@ class DIV(XmlComponent):
|
||||
|
||||
def __getitem__(self, i):
|
||||
"""
|
||||
gets attribute with name 'i' or component #i.
|
||||
Gets attribute with name 'i' or component #i.
|
||||
If attribute 'i' is not found returns None
|
||||
|
||||
:param i: index
|
||||
if i is a string: the name of the attribute
|
||||
otherwise references to number of the component
|
||||
Args:
|
||||
i: index. If i is a string: the name of the attribute
|
||||
otherwise references to number of the component
|
||||
"""
|
||||
|
||||
if isinstance(i, str):
|
||||
@@ -749,12 +773,12 @@ class DIV(XmlComponent):
|
||||
|
||||
def __setitem__(self, i, value):
|
||||
"""
|
||||
sets attribute with name 'i' or component #i.
|
||||
Sets attribute with name 'i' or component #i.
|
||||
|
||||
:param i: index
|
||||
if i is a string: the name of the attribute
|
||||
otherwise references to number of the component
|
||||
:param value: the new value
|
||||
Args:
|
||||
i: index. If i is a string: the name of the attribute
|
||||
otherwise references to number of the component
|
||||
value: the new value
|
||||
"""
|
||||
self._setnode(value)
|
||||
if isinstance(i, (str, unicode)):
|
||||
@@ -764,11 +788,11 @@ class DIV(XmlComponent):
|
||||
|
||||
def __delitem__(self, i):
|
||||
"""
|
||||
deletes attribute with name 'i' or component #i.
|
||||
Deletes attribute with name 'i' or component #i.
|
||||
|
||||
:param i: index
|
||||
if i is a string: the name of the attribute
|
||||
otherwise references to number of the component
|
||||
Args:
|
||||
i: index. If i is a string: the name of the attribute
|
||||
otherwise references to number of the component
|
||||
"""
|
||||
|
||||
if isinstance(i, str):
|
||||
@@ -778,13 +802,13 @@ class DIV(XmlComponent):
|
||||
|
||||
def __len__(self):
|
||||
"""
|
||||
returns the number of included components
|
||||
Returns the number of included components
|
||||
"""
|
||||
return len(self.components)
|
||||
|
||||
def __nonzero__(self):
|
||||
"""
|
||||
always return True
|
||||
Always returns True
|
||||
"""
|
||||
return True
|
||||
|
||||
@@ -804,10 +828,11 @@ class DIV(XmlComponent):
|
||||
helper for _fixup. Checks if a component is in allowed_parents,
|
||||
otherwise wraps it in wrap_parent
|
||||
|
||||
:param allowed_parents: (tuple) classes that the component should be an
|
||||
instance of
|
||||
:param wrap_parent: the class to wrap the component in, if needed
|
||||
:param wrap_lambda: lambda to use for wrapping, if needed
|
||||
Args:
|
||||
allowed_parents: (tuple) classes that the component should be an
|
||||
instance of
|
||||
wrap_parent: the class to wrap the component in, if needed
|
||||
wrap_lambda: lambda to use for wrapping, if needed
|
||||
|
||||
"""
|
||||
components = []
|
||||
@@ -875,7 +900,7 @@ class DIV(XmlComponent):
|
||||
|
||||
def _xml(self):
|
||||
"""
|
||||
helper for xml generation. Returns separately:
|
||||
Helper for xml generation. Returns separately:
|
||||
- the component attributes
|
||||
- the generated xml of the inner components
|
||||
|
||||
@@ -883,7 +908,8 @@ class DIV(XmlComponent):
|
||||
do not have a False or None value. The underscore is removed.
|
||||
A value of True is replaced with the attribute name.
|
||||
|
||||
:returns: tuple: (attributes, components)
|
||||
Returns:
|
||||
tuple: (attributes, components)
|
||||
"""
|
||||
|
||||
# get the attributes for this component
|
||||
@@ -932,16 +958,18 @@ class DIV(XmlComponent):
|
||||
|
||||
def __str__(self):
|
||||
"""
|
||||
str(COMPONENT) returns equals COMPONENT.xml()
|
||||
str(COMPONENT) returns COMPONENT.xml()
|
||||
"""
|
||||
|
||||
return self.xml()
|
||||
|
||||
def flatten(self, render=None):
|
||||
"""
|
||||
return the text stored by the DIV object rendered by the render function
|
||||
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
|
||||
`render=None` is equivalent to `render=lambda text, tag, attr: text`
|
||||
|
||||
Examples:
|
||||
|
||||
>>> markdown = lambda text,tag=None,attributes={}: \
|
||||
{None: re.sub('\s+',' ',text), \
|
||||
@@ -972,11 +1000,13 @@ class DIV(XmlComponent):
|
||||
|
||||
def elements(self, *args, **kargs):
|
||||
"""
|
||||
find all component that match the supplied attribute dictionary,
|
||||
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
|
||||
@@ -987,6 +1017,8 @@ class DIV(XmlComponent):
|
||||
|
||||
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
|
||||
@@ -995,7 +1027,6 @@ class DIV(XmlComponent):
|
||||
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()
|
||||
@@ -1005,6 +1036,8 @@ class DIV(XmlComponent):
|
||||
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
|
||||
@@ -1013,6 +1046,8 @@ class DIV(XmlComponent):
|
||||
"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
|
||||
@@ -1020,6 +1055,8 @@ class DIV(XmlComponent):
|
||||
|
||||
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
|
||||
@@ -1030,6 +1067,8 @@ class DIV(XmlComponent):
|
||||
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
|
||||
@@ -1038,6 +1077,8 @@ class DIV(XmlComponent):
|
||||
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
|
||||
@@ -1134,7 +1175,7 @@ class DIV(XmlComponent):
|
||||
|
||||
def element(self, *args, **kargs):
|
||||
"""
|
||||
find the first component that matches the supplied attribute dictionary,
|
||||
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.
|
||||
@@ -1148,7 +1189,7 @@ class DIV(XmlComponent):
|
||||
|
||||
def siblings(self, *args, **kargs):
|
||||
"""
|
||||
find all sibling components that match the supplied argument list
|
||||
Finds all sibling components that match the supplied argument list
|
||||
and attribute dictionary, or None if nothing could be found
|
||||
"""
|
||||
sibs = [s for s in self.parent.components if not s == self]
|
||||
@@ -1175,7 +1216,7 @@ class DIV(XmlComponent):
|
||||
|
||||
def sibling(self, *args, **kargs):
|
||||
"""
|
||||
find the first sibling component that match the supplied argument list
|
||||
Finds the first sibling component that match the supplied argument list
|
||||
and attribute dictionary, or None if nothing could be found
|
||||
"""
|
||||
kargs['first_only'] = True
|
||||
@@ -1211,10 +1252,12 @@ copy_reg.pickle(__tag_div__, TAG_pickler, TAG_unpickler)
|
||||
class __TAG__(XmlComponent):
|
||||
|
||||
"""
|
||||
TAG factory example::
|
||||
TAG factory
|
||||
|
||||
>>> print TAG.first(TAG.second('test'), _key = 3)
|
||||
<first key=\"3\"><second>test</second></first>
|
||||
Examples:
|
||||
|
||||
>>> print TAG.first(TAG.second('test'), _key = 3)
|
||||
<first key=\"3\"><second>test</second></first>
|
||||
|
||||
"""
|
||||
|
||||
@@ -1239,16 +1282,16 @@ class 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
|
||||
- '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 :class:`DIV`
|
||||
See also `DIV`
|
||||
"""
|
||||
|
||||
tag = 'html'
|
||||
@@ -1289,10 +1332,10 @@ class XHTML(DIV):
|
||||
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
|
||||
- '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'.
|
||||
@@ -1300,7 +1343,7 @@ class XHTML(DIV):
|
||||
'xmlns' parameter specifies the xml namespace.
|
||||
Defaults to 'http://www.w3.org/1999/xhtml'.
|
||||
|
||||
See also :class:`DIV`
|
||||
See also `DIV`
|
||||
"""
|
||||
|
||||
tag = 'html'
|
||||
@@ -1443,7 +1486,7 @@ class P(DIV):
|
||||
"""
|
||||
Will replace ``\\n`` by ``<br />`` if the `cr2br` attribute is provided.
|
||||
|
||||
see also :class:`DIV`
|
||||
see also `DIV`
|
||||
"""
|
||||
|
||||
tag = 'p'
|
||||
@@ -1476,6 +1519,23 @@ class HR(DIV):
|
||||
|
||||
|
||||
class A(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
|
||||
|
||||
Args:
|
||||
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'
|
||||
|
||||
@@ -1546,24 +1606,25 @@ class CENTER(DIV):
|
||||
class CODE(DIV):
|
||||
|
||||
"""
|
||||
displays code in HTML with syntax highlighting.
|
||||
Displays code in HTML with syntax highlighting.
|
||||
|
||||
:param attributes: optional attributes:
|
||||
Args:
|
||||
language: indicates the language, otherwise PYTHON is assumed
|
||||
link: can provide a link
|
||||
styles: for styles
|
||||
|
||||
- language: indicates the language, otherwise PYTHON is assumed
|
||||
- link: can provide a link
|
||||
- styles: for styles
|
||||
Examples:
|
||||
|
||||
Example::
|
||||
|
||||
{{=CODE(\"print 'hello world'\", language='python', link=None,
|
||||
counter=1, styles={}, highlight_line=None)}}
|
||||
{{=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.
|
||||
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.
|
||||
@@ -1607,7 +1668,6 @@ class UL(DIV):
|
||||
|
||||
If subcomponents are not LI-components they will be wrapped in a LI
|
||||
|
||||
see also :class:`DIV`
|
||||
"""
|
||||
|
||||
tag = 'ul'
|
||||
@@ -1637,7 +1697,6 @@ class TR(DIV):
|
||||
|
||||
If subcomponents are not TD/TH-components they will be wrapped in a TD
|
||||
|
||||
see also :class:`DIV`
|
||||
"""
|
||||
|
||||
tag = 'tr'
|
||||
@@ -1652,7 +1711,6 @@ class __TRHEAD__(DIV):
|
||||
|
||||
If subcomponents are not TD/TH-components they will be wrapped in a TH
|
||||
|
||||
see also :class:`DIV`
|
||||
"""
|
||||
|
||||
tag = 'tr'
|
||||
@@ -1702,7 +1760,6 @@ class TABLE(DIV):
|
||||
If subcomponents are not TR/TBODY/THEAD/TFOOT-components
|
||||
they will be wrapped in a TR
|
||||
|
||||
see also :class:`DIV`
|
||||
"""
|
||||
|
||||
tag = 'table'
|
||||
@@ -1724,34 +1781,36 @@ class IFRAME(DIV):
|
||||
class INPUT(DIV):
|
||||
|
||||
"""
|
||||
INPUT Component
|
||||
INPUT Component
|
||||
|
||||
examples::
|
||||
Takes two special attributes value= and requires=.
|
||||
|
||||
>>> 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\" />'
|
||||
|
||||
the input helper takes two special attributes value= and requires=.
|
||||
|
||||
:param value: used to pass the initial value for the input field.
|
||||
Args:
|
||||
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.
|
||||
|
||||
- for a checkbox value should be '' or 'on'.
|
||||
- for a radio or select/option value should be the _value
|
||||
of the checked/selected item.
|
||||
|
||||
:param requires: should be None, or a validator or a list of validators
|
||||
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/'
|
||||
@@ -1847,11 +1906,12 @@ class INPUT(DIV):
|
||||
class TEXTAREA(INPUT):
|
||||
|
||||
"""
|
||||
example::
|
||||
Examples::
|
||||
|
||||
TEXTAREA(_name='sometext', value='blah '*100, requires=IS_NOT_EMPTY())
|
||||
TEXTAREA(_name='sometext', value='blah ' * 100, requires=IS_NOT_EMPTY())
|
||||
|
||||
'blah blah blah ...' will be the content of the textarea field.
|
||||
|
||||
"""
|
||||
|
||||
tag = 'textarea'
|
||||
@@ -1898,12 +1958,12 @@ class OPTGROUP(DIV):
|
||||
class SELECT(INPUT):
|
||||
|
||||
"""
|
||||
example::
|
||||
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>'
|
||||
>>> 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>'
|
||||
|
||||
"""
|
||||
|
||||
@@ -1962,12 +2022,13 @@ class LEGEND(DIV):
|
||||
class FORM(DIV):
|
||||
|
||||
"""
|
||||
example::
|
||||
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>'
|
||||
|
||||
>>> 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
|
||||
|
||||
@@ -2107,12 +2168,12 @@ class FORM(DIV):
|
||||
you can use it instead of directly form.accepts.
|
||||
|
||||
Usage:
|
||||
In controller
|
||||
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)
|
||||
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
|
||||
|
||||
@@ -2190,29 +2251,31 @@ class FORM(DIV):
|
||||
"""
|
||||
Perform the .validate() method but returns the form
|
||||
|
||||
Usage in controllers:
|
||||
# directly on return
|
||||
def action():
|
||||
#some code here
|
||||
return dict(form=FORM(...).process(...))
|
||||
Usage in controllers::
|
||||
|
||||
You can use it with FORM, SQLFORM or FORM based plugins
|
||||
# directly on return
|
||||
def action():
|
||||
#some code here
|
||||
return dict(form=FORM(...).process(...))
|
||||
|
||||
Examples:
|
||||
#response.flash messages
|
||||
def action():
|
||||
form = SQLFORM(db.table).process(message_onsuccess='Sucess!')
|
||||
retutn dict(form=form)
|
||||
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)
|
||||
|
||||
# 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)
|
||||
"""
|
||||
kwargs['dbio'] = kwargs.get('dbio', True)
|
||||
# necessary for SQLHTML forms
|
||||
@@ -2223,7 +2286,7 @@ class FORM(DIV):
|
||||
|
||||
def add_button(self, value, url, _class=None):
|
||||
submit = self.element(_type='submit')
|
||||
_class = "%s w2p-form-button" % _class if _class else "w2p-form-button"
|
||||
_class = "%s w2p-form-button" % _class if _class else "w2p-form-button"
|
||||
submit.parent.append(
|
||||
TAG['button'](value, _class=_class,
|
||||
_onclick=url if url.startswith('javascript:') else
|
||||
@@ -2313,16 +2376,20 @@ class FORM(DIV):
|
||||
class BEAUTIFY(DIV):
|
||||
|
||||
"""
|
||||
example::
|
||||
Turns any list, dictionary, etc into decent looking html.
|
||||
|
||||
>>> 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>'
|
||||
|
||||
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 funciton that takes a key and returns its representation
|
||||
or None if the key is to be skipped. By default key[:1]=='_' is skipped.
|
||||
|
||||
- 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>'
|
||||
|
||||
"""
|
||||
|
||||
tag = 'div'
|
||||
@@ -2394,16 +2461,18 @@ class MENU(DIV):
|
||||
"""
|
||||
Used to build menus
|
||||
|
||||
Optional arguments
|
||||
_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'
|
||||
Args:
|
||||
_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::
|
||||
|
||||
Example:
|
||||
menu = MENU([['name', False, URL(...), [submenu]], ...])
|
||||
{{=menu}}
|
||||
|
||||
"""
|
||||
|
||||
tag = 'ul'
|
||||
@@ -2503,9 +2572,10 @@ def embed64(
|
||||
"""
|
||||
helper to encode the provided (binary) data into base64.
|
||||
|
||||
:param filename: if provided, opens and reads this file in 'rb' mode
|
||||
:param file: if provided, reads this file
|
||||
:param data: if provided, uses the provided data
|
||||
Args:
|
||||
filename: if provided, opens and reads this file in 'rb' mode
|
||||
file: if provided, reads this file
|
||||
data: if provided, uses the provided data
|
||||
"""
|
||||
|
||||
if filename and os.path.exists(file):
|
||||
|
||||
Reference in New Issue
Block a user