From 473d2d5d096a72fb4c88bacefe3dc6742a878b58 Mon Sep 17 00:00:00 2001 From: niphlod Date: Fri, 24 Jan 2014 22:17:43 +0100 Subject: [PATCH] docstrings refactored --- gluon/admin.py | 257 +++++++++++++++++++++---------------------------- 1 file changed, 111 insertions(+), 146 deletions(-) diff --git a/gluon/admin.py b/gluon/admin.py index 0661d80e..e81f3e02 100644 --- a/gluon/admin.py +++ b/gluon/admin.py @@ -1,10 +1,13 @@ +#!/usr/bin/env python +# -*- 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) Utility functions for the Admin application -=========================================== +------------------------------------------- """ import os import sys @@ -25,15 +28,11 @@ if not global_settings.web2py_runtime_gae: def apath(path='', r=None): - """ - Builds a path inside an application folder + """Builds a path inside an application folder - Parameters - ---------- - path: - path within the application folder - r: - the global request object + Args: + path(str): path within the application folder + r: the global request object """ @@ -44,20 +43,14 @@ def apath(path='', r=None): def app_pack(app, request, raise_ex=False, filenames=None): - """ - Builds a w2p package for the application + """Builds a w2p package for the application - Parameters - ---------- - app: - application name - request: - the global request object - - Returns - ------- - filename: + Args: + app(str): application name + request: the global request object + Returns: filename of the w2p file or None on error + """ try: if filenames is None: app_cleanup(app, request) @@ -71,20 +64,15 @@ def app_pack(app, request, raise_ex=False, filenames=None): def app_pack_compiled(app, request, raise_ex=False): - """ - Builds a w2p bytecode-compiled package for the application + """Builds a w2p bytecode-compiled package for the application - Parameters - ---------- - app: - application name - request: - the global request object + Args: + app(str): application name + request: the global request object - Returns - ------- - filename: + Returns: filename of the w2p file or None on error + """ try: @@ -98,15 +86,15 @@ def app_pack_compiled(app, request, raise_ex=False): def app_cleanup(app, request): - """ - Removes session, cache and error files + """Removes session, cache and error files + + Args: + app(str): application name + request: the global request object + + Returns: + True if everything went ok, False otherwise - Parameters - ---------- - app: - application name - request: - the global request object """ r = True @@ -140,15 +128,15 @@ def app_cleanup(app, request): def app_compile(app, request): - """ - Compiles the application + """Compiles the application + + Args: + app(str): application name + request: the global request object + + Returns: + None if everything went ok, traceback text if errors are found - Parameters - ---------- - app: - application name - request: - the global request object """ from compileapp import compile_application, remove_compiled_application folder = apath(app, request) @@ -162,15 +150,11 @@ def app_compile(app, request): def app_create(app, request, force=False, key=None, info=False): - """ - Create a copy of welcome.w2p (scaffolding) app + """Create a copy of welcome.w2p (scaffolding) app - Parameters - ---------- - app: - application name - request: - the global request object + Args: + app(str): application name + request: the global request object """ path = apath(app, request) @@ -215,28 +199,23 @@ def app_create(app, request, force=False, key=None, info=False): def app_install(app, fobj, request, filename, overwrite=None): - """ - Installs an application: + """Installs an application: - Identifies file type by filename - Writes `fobj` contents to the `../deposit/` folder - Calls `w2p_unpack()` to do the job. - Parameters - ---------- - app: - 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 + Args: + 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 - ------- - upname: + Returns: name of the file where app is temporarily stored or `None` on failure + """ did_mkdir = False if filename[-4:] == '.w2p': @@ -265,19 +244,15 @@ def app_install(app, fobj, request, filename, overwrite=None): def app_uninstall(app, request): - """ - Uninstalls the application. + """Uninstalls the application. - Parameters - ---------- - app: - application name - request: - the global request object + Args: + app(str): application name + request: the global request object + + Returns: + `True` on success, `False` on failure - Returns - ------- - `True` on success, `False` on failure """ try: # Hey App, this is your end... @@ -289,22 +264,16 @@ def app_uninstall(app, request): def plugin_pack(app, plugin_name, request): - """ - Builds a w2p package for the application + """Builds a w2p package for the plugin - Parameters - ---------- - app: - application name - plugin_name: - the name of the plugin without plugin_ prefix - request: - the current request app + Args: + 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 - Returns - ------- - filename: - filename of the w2p file or None on error """ try: filename = apath( @@ -316,30 +285,24 @@ def plugin_pack(app, plugin_name, request): def plugin_install(app, fobj, request, filename): - """ - Installs an application: + """Installs a plugin: - Identifies file type by filename - Writes `fobj` contents to the `../deposit/` folder - - Calls `w2p_unpack()` to do the job. + - Calls `w2p_unpack_plugin()` to do the job. - Parameters - ---------- - app: - 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 + Args: + 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 - Returns - ------- - upname: - name of the file where app is temporarily stored or `None` on failure """ - upname = apath('../deposit/%s' % filename, request) try: @@ -354,23 +317,20 @@ def plugin_install(app, fobj, request, filename): def check_new_version(myversion, version_url): - """ - Compares current web2py's version with the latest stable web2py version. + """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 + Args: + myversion: the current version as stored in file `web2py/VERSION` + version_URL: the URL that contains the version + of the latest stable release + + Returns: + tuple: 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 - Returns - ------- - state: - `True` if upgrade available, `False` if current version if up-to-date, - -1 on error - version: - the most up-to-version available """ try: from urllib import urlopen @@ -389,9 +349,13 @@ def check_new_version(myversion, version_url): def unzip(filename, dir, subfolder=''): - """ - Unzips filename into dir (.zip only, no .gz etc) - if subfolder!='' it unzip only files in subfolder + """Unzips filename into dir (.zip only, no .gz etc) + + Args: + filename(str): archive + dir(str): destination + subfolder(str): if != '' unzips only files in subfolder + """ filename = abspath(filename) if not zipfile.is_zipfile(filename): @@ -413,21 +377,22 @@ def unzip(filename, dir, subfolder=''): def upgrade(request, url='http://web2py.com'): - """ - Upgrades web2py (src, osx, win) is a new version is posted. + """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' + Args: + 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 - ------- - True on success, False on failure (network problem or old version) + tuple: completed, traceback + + - completed: True on success, False on failure + (network problem or old version) + - traceback: None on success, raised exception details on failure + """ web2py_version = request.env.web2py_version gluon_parent = request.env.gluon_parent