From e209dcc8d31c56874a72060a84910a8573d62d34 Mon Sep 17 00:00:00 2001 From: niphlod Date: Wed, 12 Mar 2014 22:03:42 +0100 Subject: [PATCH] sphinx-compatible docstrings --- gluon/newcron.py | 17 +++--- gluon/portalocker.py | 12 ++-- gluon/reserved_sql_keywords.py | 1 + gluon/restricted.py | 31 +++++----- gluon/rewrite.py | 107 ++++++++++++++++----------------- 5 files changed, 86 insertions(+), 82 deletions(-) diff --git a/gluon/newcron.py b/gluon/newcron.py index c9853ddd..7245507c 100644 --- a/gluon/newcron.py +++ b/gluon/newcron.py @@ -2,8 +2,12 @@ # -*- coding: utf-8 -*- """ -Created by Attila Csipa -Modified by Massimo Di Pierro +| This file is part of the web2py Web Framework +| Created by Attila Csipa +| Modified by Massimo Di Pierro +| 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) diff --git a/gluon/portalocker.py b/gluon/portalocker.py index 5090535c..2bcd63f5 100644 --- a/gluon/portalocker.py +++ b/gluon/portalocker.py @@ -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() diff --git a/gluon/reserved_sql_keywords.py b/gluon/reserved_sql_keywords.py index 9ff314ae..6e3002e2 100644 --- a/gluon/reserved_sql_keywords.py +++ b/gluon/reserved_sql_keywords.py @@ -22,6 +22,7 @@ __author__ = "Thadeus Burgess " # 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', diff --git a/gluon/restricted.py b/gluon/restricted.py index 64e1c679..59b7b751 100644 --- a/gluon/restricted.py +++ b/gluon/restricted.py @@ -2,9 +2,12 @@ # -*- coding: utf-8 -*- """ -This file is part of the web2py Web Framework -Copyrighted by Massimo Di Pierro -License: LGPLv3 (http://www.gnu.org/licenses/lgpl.html) +| This file is part of the web2py Web Framework +| Copyrighted by Massimo Di Pierro +| 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: diff --git a/gluon/rewrite.py b/gluon/rewrite.py index aefb8df5..eabefc2c 100644 --- a/gluon/rewrite.py +++ b/gluon/rewrite.py @@ -2,9 +2,9 @@ # -*- coding: utf-8 -*- """ -This file is part of the web2py Web Framework -Copyrighted by Massimo Di Pierro -License: LGPLv3 (http://www.gnu.org/licenses/lgpl.html) +| This file is part of the web2py Web Framework +| Copyrighted by Massimo Di Pierro +| 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