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

sphinx-compatible docstrings

gluon/newcron.py

@@ -2,8 +2,12 @@
 # -*- coding: utf-8 -*-
 
 """
-Created by Attila Csipa <web2py@csipa.in.rs>
+| This file is part of the web2py Web Framework
-Modified by Massimo Di Pierro <mdipierro@cs.depaul.edu>
+| 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
+        Writes into cron.master the time when cron job was completed
-        was completed
         """
         if not self.master.closed:
             portalocker.lock(self.master, portalocker.LOCK_EX)

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()

gluon/reserved_sql_keywords.py

@@ -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

@@ -2,9 +2,12 @@
 # -*- coding: utf-8 -*-
 
 """
-This file is part of the web2py Web Framework
+| This file is part of the web2py Web Framework
-Copyrighted by Massimo Di Pierro <mdipierro@cs.depaul.edu>
+| Copyrighted by Massimo Di Pierro <mdipierro@cs.depaul.edu>
-License: LGPLv3 (http://www.gnu.org/licenses/lgpl.html)
+| 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
+    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.
+    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
+    Runs code in environment and returns the output. If an exception occurs
-    in code it raises a RestrictedError containing the traceback. layer is
+    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

@@ -2,9 +2,9 @@
 # -*- coding: utf-8 -*-
 
 """
-This file is part of the web2py Web Framework
+| This file is part of the web2py Web Framework
-Copyrighted by Massimo Di Pierro <mdipierro@cs.depaul.edu>
+| Copyrighted by Massimo Di Pierro <mdipierro@cs.depaul.edu>
-License: LGPLv3 (http://www.gnu.org/licenses/lgpl.html)
+| 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
+        Updates request from self
-        build env.request_uri
+        Builds env.request_uri
-        make lower-case versions of http headers in env
+        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 => /
+        /da/dc/df => /
-    /a/dc/df => /a
+        /a/dc/df => /a
-    /a/c/df => /a/c
+        /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