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

Merge pull request #363 from niphlod/docs/admin

Browse Source 
docstrings refactored
This commit is contained in:
mdipierro
2014-01-24 18:32:50 -08:00
parent 060eddf812 473d2d5d09
commit 2967969add
1 changed files with 111 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files
gluon/admin.py
+111 -146
View File
@@ -1,10 +1,13 @@
#!/usr/bin/env python
# -*- 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)
Utility functions for the Admin application Utility functions for the Admin application
=========================================== -------------------------------------------
""" """
import os import os
import sys import sys
@@ -25,15 +28,11 @@ if not global_settings.web2py_runtime_gae:
def apath(path='', r=None): def apath(path='', r=None):
""" """Builds a path inside an application folder
Builds a path inside an application folder
Parameters Args:
---------- path(str): path within the application folder
path: r: the global request object
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): 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 Args:
---------- app(str): application name
app: request: the global request object
application name Returns:
request:
the global request object
Returns
-------
filename:
filename of the w2p file or None on error filename of the w2p file or None on error
""" """
try: try:
if filenames is None: app_cleanup(app, request) 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): 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 Args:
---------- app(str): application name
app: request: the global request object
application name
request:
the global request object
Returns Returns:
-------
filename:
filename of the w2p file or None on error filename of the w2p file or None on error
""" """
try: try:
@@ -98,15 +86,15 @@ def app_pack_compiled(app, request, raise_ex=False):
def app_cleanup(app, request): 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 r = True
@@ -140,15 +128,15 @@ def app_cleanup(app, request):
def app_compile(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 from compileapp import compile_application, remove_compiled_application
folder = apath(app, request) folder = apath(app, request)
@@ -162,15 +150,11 @@ def app_compile(app, request):
def app_create(app, request, force=False, key=None, info=False): 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 Args:
---------- app(str): application name
app: request: the global request object
application name
request:
the global request object
""" """
path = apath(app, request) 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): def app_install(app, fobj, request, filename, overwrite=None):
""" """Installs an application:
Installs an application:
- Identifies file type by filename - Identifies file type by filename
- Writes `fobj` contents to the `../deposit/` folder - Writes `fobj` contents to the `../deposit/` folder
- Calls `w2p_unpack()` to do the job. - Calls `w2p_unpack()` to do the job.
Parameters Args:
---------- app(str): new application name
app: fobj(obj): file object containing the application to be installed
new application name request: the global request object
fobj: filename(str): original filename of the `fobj`,
file object containing the application to be installed required to determine extension
request: overwrite(bool): force overwrite of existing application
the global request object
filename:
original filename of the `fobj`, required to determine extension
Returns Returns:
-------
upname:
name of the file where app is temporarily stored or `None` on failure name of the file where app is temporarily stored or `None` on failure
""" """
did_mkdir = False did_mkdir = False
if filename[-4:] == '.w2p': if filename[-4:] == '.w2p':
@@ -265,19 +244,15 @@ def app_install(app, fobj, request, filename, overwrite=None):
def app_uninstall(app, request): def app_uninstall(app, request):
""" """Uninstalls the application.
Uninstalls the application.
Parameters Args:
---------- app(str): application name
app: request: the global request object
application name
request: Returns:
the global request object `True` on success, `False` on failure
Returns
-------
`True` on success, `False` on failure
""" """
try: try:
# Hey App, this is your end... # Hey App, this is your end...
@@ -289,22 +264,16 @@ def app_uninstall(app, request):
def plugin_pack(app, plugin_name, request): def plugin_pack(app, plugin_name, request):
""" """Builds a w2p package for the plugin
Builds a w2p package for the application
Parameters Args:
---------- app(str): application name
app: plugin_name(str): the name of the plugin without plugin_ prefix
application name request: the current request app
plugin_name:
the name of the plugin without plugin_ prefix Returns:
request: filename of the w2p file or False on error
the current request app
Returns
-------
filename:
filename of the w2p file or None on error
""" """
try: try:
filename = apath( filename = apath(
@@ -316,30 +285,24 @@ def plugin_pack(app, plugin_name, request):
def plugin_install(app, fobj, request, filename): def plugin_install(app, fobj, request, filename):
""" """Installs a plugin:
Installs an application:
- Identifies file type by filename - Identifies file type by filename
- Writes `fobj` contents to the `../deposit/` folder - Writes `fobj` contents to the `../deposit/` folder
- Calls `w2p_unpack()` to do the job. - Calls `w2p_unpack_plugin()` to do the job.
Parameters Args:
---------- app(str): new application name
app: fobj: file object containing the application to be installed
new application name request: the global request object
fobj: filename: original filename of the `fobj`,
file object containing the application to be installed required to determine extension
request:
the global request object Returns:
filename: name of the file where plugin is temporarily stored
original filename of the `fobj`, required to determine extension 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) upname = apath('../deposit/%s' % filename, request)
try: try:
@@ -354,23 +317,20 @@ def plugin_install(app, fobj, request, filename):
def check_new_version(myversion, version_url): 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 Args:
---------- myversion: the current version as stored in file `web2py/VERSION`
myversion: version_URL: the URL that contains the version
the current version as stored in file `web2py/VERSION` of the latest stable release
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: try:
from urllib import urlopen from urllib import urlopen
@@ -389,9 +349,13 @@ def check_new_version(myversion, version_url):
def unzip(filename, dir, subfolder=''): def unzip(filename, dir, subfolder=''):
""" """Unzips filename into dir (.zip only, no .gz etc)
Unzips filename into dir (.zip only, no .gz etc)
if subfolder!='' it unzip only files in subfolder Args:
filename(str): archive
dir(str): destination
subfolder(str): if != '' unzips only files in subfolder
""" """
filename = abspath(filename) filename = abspath(filename)
if not zipfile.is_zipfile(filename): if not zipfile.is_zipfile(filename):
@@ -413,21 +377,22 @@ def unzip(filename, dir, subfolder=''):
def upgrade(request, url='http://web2py.com'): def upgrade(request, url='http://web2py.com'):
""" """Upgrades web2py (src, osx, win) if a new version is posted.
Upgrades web2py (src, osx, win) is a new version is posted.
It detects whether src, osx or win is running and downloads the right one It detects whether src, osx or win is running and downloads the right one
Parameters Args:
---------- request: the current request object
request: (required to determine version and path)
the current request object, required to determine version and path url: the incomplete url where to locate the latest web2py
url: (actual url is url+'/examples/static/web2py_(src|osx|win).zip')
the incomplete url where to locate the latest web2py
actual url is url+'/examples/static/web2py_(src|osx|win).zip'
Returns Returns
------- tuple: completed, traceback
True on success, False on failure (network problem or old version)
- 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 web2py_version = request.env.web2py_version
gluon_parent = request.env.gluon_parent gluon_parent = request.env.gluon_parent