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

257
gluon/admin.py
View File

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