dinislage/web2py
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #401 from niphlod/docs/n-p

Browse Source 
sphinx-compatible docstrings
This commit is contained in:
mdipierro
2014-03-15 21:08:05 -05:00
parent 02906fa39f e209dcc8d3
commit d343d8380c
5 changed files with 86 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files
gluon/newcron.py
+10 -7
View File
@@ -2,8 +2,12 @@
# -*- coding: utf-8 -*-
"""
Created by Attila Csipa <web2py@csipa.in.rs>
Modified by Massimo Di Pierro <mdipierro@cs.depaul.edu>
| This file is part of the web2py Web Framework
| Created by Attila Csipa <web2py@csipa.in.rs>
| Modified by Massimo Di Pierro <mdipierro@cs.depaul.edu>
| License: LGPLv3 (http://www.gnu.org/licenses/lgpl.html)
Cron-style interface
"""
import sys
@@ -27,7 +31,7 @@ _cron_subprocs = []
def absolute_path_link(path):
"""
Return an absolute path for the destination of a symlink
Returns an absolute path for the destination of a symlink
"""
if os.path.islink(path):
@@ -40,7 +44,7 @@ def absolute_path_link(path):
def stopcron():
"graceful shutdown of cron"
"Graceful shutdown of cron"
global _cron_stopping
_cron_stopping = True
while _cron_subprocs:
@@ -107,7 +111,7 @@ class Token(object):
def acquire(self, startup=False):
"""
returns the time when the lock is acquired or
Returns the time when the lock is acquired or
None if cron already running
lock is implemented by writing a pickle (start, stop) in cron.master
@@ -150,8 +154,7 @@ class Token(object):
def release(self):
"""
this function writes into cron.master the time when cron job
was completed
Writes into cron.master the time when cron job was completed
"""
if not self.master.closed:
portalocker.lock(self.master, portalocker.LOCK_EX)
gluon/portalocker.py
+5 -7
View File
@@ -1,13 +1,10 @@
#!/usr/bin/env python
# -*- coding: utf-8 -*-
# portalocker.py
# Cross-platform (posix/nt) API for flock-style file locking.
# Requires python 1.5.2 or better.
"""
Cross-platform (posix/nt) API for flock-style file locking.
Synopsis:
Synopsis::
import portalocker
file = open(\"somefile\", \"r+\")
@@ -16,18 +13,18 @@ Synopsis:
file.write(\"foo\")
file.close()
If you know what you're doing, you may choose to
If you know what you're doing, you may choose to::
portalocker.unlock(file)
before closing the file, but why?
Methods:
Methods::
lock( file, flags )
unlock( file )
Constants:
Constants::
LOCK_EX
LOCK_SH
@@ -163,6 +160,7 @@ def write_locked(filename, data):
fp.close()
if __name__ == '__main__':
import sys
f = LockedFile('test.txt', mode='wb')
f.write('test ok')
f.close()
gluon/reserved_sql_keywords.py
+1
View File
@@ -22,6 +22,7 @@ __author__ = "Thadeus Burgess <thadeusb@thadeusb.com>"
# These are keywords that are common to all SQL dialects, and should
# never be used as a table or column. Even if you use one of these
# the cursor will throw an OperationalError for the SQL syntax.
COMMON = set((
'SELECT',
'INSERT',
gluon/restricted.py
+17 -14
View File
@@ -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)
Restricted environment to execute application's code
-----------------------------------------------------
"""
import sys
@@ -26,7 +29,7 @@ __all__ = ['RestrictedError', 'restricted', 'TicketStorage', 'compile2']
class TicketStorage(Storage):
"""
defines the ticket object and the default values of its members (None)
Defines the ticket object and the default values of its members (None)
"""
def __init__(
@@ -40,7 +43,7 @@ class TicketStorage(Storage):
def store(self, request, ticket_id, ticket_data):
"""
stores the ticket. It will figure out if this must be on disk or in db
Stores the ticket. It will figure out if this must be on disk or in db
"""
if self.db:
self._store_in_db(request, ticket_id, ticket_data)
@@ -51,12 +54,12 @@ class TicketStorage(Storage):
self.db._adapter.reconnect()
try:
table = self._get_table(self.db, self.tablename, request.application)
id = table.insert(ticket_id=ticket_id,
table.insert(ticket_id=ticket_id,
ticket_data=cPickle.dumps(ticket_data),
created_datetime=request.now)
self.db.commit()
message = 'In FILE: %(layer)s\n\n%(traceback)s\n'
except Exception, e:
except Exception:
self.db.rollback()
message =' Unable to store in FILE: %(layer)s\n\n%(traceback)s\n'
self.db.close()
@@ -111,8 +114,8 @@ class TicketStorage(Storage):
class RestrictedError(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.
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.
"""
def __init__(
@@ -123,7 +126,7 @@ class RestrictedError(Exception):
environment=None,
):
"""
layer here is some description of where in the system the exception
Layer here is some description of where in the system the exception
occurred.
"""
if environment is None:
@@ -148,7 +151,7 @@ class RestrictedError(Exception):
def log(self, request):
"""
logs the exception.
Logs the exception.
"""
try:
@@ -168,7 +171,7 @@ class RestrictedError(Exception):
def load(self, request, app, ticket_id):
"""
loads a logged exception.
Loads a logged exception.
"""
ticket_storage = TicketStorage(db=request.tickets_db)
d = ticket_storage.load(request, app, ticket_id)
@@ -201,8 +204,8 @@ def compile2(code, layer):
def restricted(code, environment=None, layer='Unknown'):
"""
runs code in environment and returns the output. if an exception occurs
in code it raises a RestrictedError containing the traceback. layer is
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.
"""
if environment is None:
gluon/rewrite.py
+53 -54
View File
@@ -2,9 +2,9 @@
# -*- 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)
gluon.rewrite parses incoming URLs and formats outgoing URLs for gluon.html.URL.
@@ -57,7 +57,7 @@ regex_args = re.compile('[^\w/.@=-]')
def _router_default():
"return new copy of default base router"
"Returns new copy of default base router"
router = Storage(
default_application='init',
applications='ALL',
@@ -85,7 +85,7 @@ def _router_default():
def _params_default(app=None):
"return new copy of default parameters"
"Returns a new copy of default parameters"
p = Storage()
p.name = app or "BASE"
p.default_application = app or "init"
@@ -181,7 +181,7 @@ def fixup_missing_path_info(environ):
def url_in(request, environ):
"parse and rewrite incoming URL"
"Parses and rewrites incoming URL"
if routers:
return map_url_in(request, environ)
return regex_url_in(request, environ)
@@ -189,7 +189,7 @@ def url_in(request, environ):
def url_out(request, environ, application, controller, function,
args, other, scheme, host, port, language=None):
"assemble and rewrite outgoing URL"
"Assembles and rewrites outgoing URL"
if routers:
acf = map_url_out(request, environ, application, controller,
function, args, other, scheme, host, port, language)
@@ -214,7 +214,7 @@ def url_out(request, environ, application, controller, function,
def try_rewrite_on_error(http_response, request, environ, ticket=None):
"""
called from main.wsgibase to rewrite the http response.
Called from main.wsgibase to rewrite the http response.
"""
status = int(str(http_response.status).split()[0])
if status >= 399 and THREAD_LOCAL.routes.routes_onerror:
@@ -255,7 +255,7 @@ def try_rewrite_on_error(http_response, request, environ, ticket=None):
def try_redirect_on_error(http_object, request, ticket=None):
"called from main.wsgibase to rewrite the http response"
"Called from main.wsgibase to rewrite the http response"
status = int(str(http_object.status).split()[0])
if status > 399 and THREAD_LOCAL.routes.routes_onerror:
keys = set(('%s/%s' % (request.application, status),
@@ -392,7 +392,7 @@ def load(routes='routes.py', app=None, data=None, rdict=None):
def compile_regex(k, v, env=None):
"""
Preprocess and compile the regular expressions in routes_app/in/out
The resulting regex will match a pattern of the form:
The resulting regex will match a pattern of the form::
[remote address]:[protocol]://[host]:[method] [path]
@@ -427,7 +427,7 @@ def compile_regex(k, v, env=None):
def load_routers(all_apps):
"load-time post-processing of routers"
"Load-time post-processing of routers"
for app in routers:
# initialize apps with routers that aren't present,
@@ -533,7 +533,7 @@ def load_routers(all_apps):
def regex_uri(e, regexes, tag, default=None):
"filter incoming URI against a list of regexes"
"Filters incoming URI against a list of regexes"
path = e['PATH_INFO']
host = e.get('HTTP_HOST', e.get('SERVER_NAME', 'localhost')).lower()
i = host.find(':')
@@ -555,7 +555,7 @@ def regex_uri(e, regexes, tag, default=None):
def regex_select(env=None, app=None, request=None):
"""
select a set of regex rewrite params for the current request
Selects a set of regex rewrite params for the current request
"""
if app:
THREAD_LOCAL.routes = params_apps.get(app, params)
@@ -572,7 +572,7 @@ def regex_select(env=None, app=None, request=None):
def regex_filter_in(e):
"regex rewrite incoming URL"
"Regex rewrite incoming URL"
routes = THREAD_LOCAL.routes
query = e.get('QUERY_STRING', None)
e['WEB2PY_ORIGINAL_URI'] = e['PATH_INFO'] + (query and ('?' + query) or '')
@@ -603,7 +603,7 @@ def invalid_url(routes):
web2py_error='invalid path')
def regex_url_in(request, environ):
"rewrite and parse incoming URL"
"Rewrites and parses incoming URL"
# ##################################################
# select application
@@ -667,7 +667,7 @@ def regex_url_in(request, environ):
def regex_filter_out(url, e=None):
"regex rewrite outgoing URL"
"Regex rewrite outgoing URL"
if not hasattr(THREAD_LOCAL, 'routes'):
regex_select() # ensure routes is set (for application threads)
routes = THREAD_LOCAL.routes
@@ -810,10 +810,10 @@ def filter_err(status, application='app', ticket='tkt'):
class MapUrlIn(object):
"logic for mapping incoming URLs"
"Logic for mapping incoming URLs"
def __init__(self, request=None, env=None):
"initialize a map-in object"
"Initializes a map-in object"
self.request = request
self.env = env
@@ -861,7 +861,7 @@ class MapUrlIn(object):
self.port = '443' if self.scheme == 'https' else '80'
def map_prefix(self):
"strip path prefix, if present in its entirety"
"Strips path prefix, if present in its entirety"
prefix = routers.BASE.path_prefix
if prefix:
prefixlen = len(prefix)
@@ -873,7 +873,7 @@ class MapUrlIn(object):
self.args = List(self.args[prefixlen:]) # strip the prefix
def map_app(self):
"determine application name"
"Determines application name"
base = routers.BASE # base router
self.domain_application = None
self.domain_controller = None
@@ -935,12 +935,12 @@ class MapUrlIn(object):
self._args_match = self.router._args_match
def map_root_static(self):
'''
handle root-static files (no hyphen mapping)
"""
Handles root-static files (no hyphen mapping)
a root-static file is one whose incoming URL expects it to be at the root,
typically robots.txt & favicon.ico
'''
"""
if len(self.args) == 1 and self.arg0 in self.router.root_static:
self.controller = self.request.controller = 'static'
@@ -952,7 +952,7 @@ class MapUrlIn(object):
return None, None
def map_language(self):
"handle language (no hyphen mapping)"
"Handles language (no hyphen mapping)"
arg0 = self.arg0 # no hyphen mapping
if arg0 and self.languages and arg0 in self.languages:
self.language = arg0
@@ -964,7 +964,7 @@ class MapUrlIn(object):
arg0 = self.arg0
def map_controller(self):
"identify controller"
"Identifies controller"
# handle controller
#
arg0 = self.harg0 # map hyphens
@@ -981,7 +981,7 @@ class MapUrlIn(object):
def map_static(self):
'''
handle static files
Handles static files
file_match but no hyphen mapping
'''
if self.controller != 'static':
@@ -1025,7 +1025,7 @@ class MapUrlIn(object):
return static_file, version
def map_function(self):
"handle function.extension"
"Handles function.extension"
arg0 = self.harg0 # map hyphens
functions = self.functions.get(self.controller, set())
if isinstance(self.router.default_function, dict):
@@ -1058,9 +1058,9 @@ class MapUrlIn(object):
web2py_error='invalid extension')
def validate_args(self):
'''
check args against validation pattern
'''
"""
Checks args against validation pattern
"""
for arg in self.args:
if not self.router._args_match.match(arg):
raise HTTP(
@@ -1068,16 +1068,15 @@ class MapUrlIn(object):
web2py_error='invalid arg <%s>' % arg)
def sluggify(self):
""
self.request.env.update(
(k.lower().replace('.', '_'), v) for k, v in self.env.iteritems())
def update_request(self):
'''
update request from self
build env.request_uri
make lower-case versions of http headers in env
'''
"""
Updates request from self
Builds env.request_uri
Makes lower-case versions of http headers in env
"""
self.request.application = self.application
self.request.controller = self.controller
self.request.function = self.function
@@ -1105,24 +1104,24 @@ class MapUrlIn(object):
@property
def arg0(self):
"return first arg"
"Returns first arg"
return self.args(0)
@property
def harg0(self):
"return first arg with optional hyphen mapping"
"Returns first arg with optional hyphen mapping"
if self.map_hyphen and self.args(0):
return self.args(0).replace('-', '_')
return self.args(0)
def pop_arg_if(self, dopop):
"conditionally remove first arg and return new first arg"
"Conditionally removes first arg and returns new first arg"
if dopop:
self.args.pop(0)
class MapUrlOut(object):
"logic for mapping outgoing URLs"
"Logic for mapping outgoing URLs"
def __init__(self, request, env, application, controller,
function, args, other, scheme, host, port, language):
@@ -1179,13 +1178,13 @@ class MapUrlOut(object):
self.omit_function = False
def omit_lang(self):
"omit language if possible"
"Omits language if possible"
if not self.language or self.language == self.default_language:
self.omit_language = True
def omit_acf(self):
"omit what we can of a/c/f"
"Omits what we can of a/c/f"
router = self.router
@@ -1254,7 +1253,7 @@ class MapUrlOut(object):
self.omit_function = False
def build_acf(self):
"build acf from components"
"Builds a/c/f from components"
acf = ''
if self.map_hyphen:
self.application = self.application.replace('_', '-')
@@ -1280,7 +1279,7 @@ class MapUrlOut(object):
return acf or '/'
def acf(self):
"convert components to /app/lang/controller/function"
"Converts components to /app/lang/controller/function"
if not routers:
return None # use regex filter
@@ -1290,7 +1289,7 @@ class MapUrlOut(object):
def map_url_in(request, env, app=False):
"route incoming URL"
"Routes incoming URL"
# initialize router-url object
#
@@ -1333,8 +1332,8 @@ def map_url_in(request, env, app=False):
def map_url_out(request, env, application, controller,
function, args, other, scheme, host, port, language=None):
'''
supply /a/c/f (or /a/lang/c/f) portion of outgoing url
"""
Supply /a/c/f (or /a/lang/c/f) portion of outgoing url
The basic rule is that we can only make transformations
that map_url_in can reverse.
@@ -1342,14 +1341,14 @@ def map_url_out(request, env, application, controller,
Suppose that the incoming arguments are a,c,f,args,lang
and that the router defaults are da, dc, df, dl.
We can perform these transformations trivially if args=[] and lang=None or dl:
We can perform these transformations trivially if args=[] and lang=None or dl::
/da/dc/df => /
/a/dc/df => /a
/a/c/df => /a/c
/da/dc/df => /
/a/dc/df => /a
/a/c/df => /a/c
We would also like to be able to strip the default application or application/controller
from URLs with function/args present, thus:
from URLs with function/args present, thus::
/da/c/f/args => /c/f/args
/da/dc/f/args => /f/args
@@ -1357,14 +1356,14 @@ def map_url_out(request, env, application, controller,
We use [applications] and [controllers] and {functions} to suppress ambiguous omissions.
We assume that language names do not collide with a/c/f names.
'''
"""
map = MapUrlOut(request, env, application, controller,
function, args, other, scheme, host, port, language)
return map.acf()
def get_effective_router(appname):
"return a private copy of the effective router for the specified application"
"Returns a private copy of the effective router for the specified application"
if not routers or appname not in routers:
return None
return Storage(routers[appname]) # return a copy