module flaskJSONRPCServer 0.9.2

Description 

This library is an extended implementation of server for JSON-RPC protocol. It supports only json-rpc 2.0 specification for now, which includes batch submission, keyword arguments, notifications, etc.

class flaskJSONRPCServer(self, bindAdress, multipleAdress=False, blocking=False, cors=False, gevent=False, debug=False, log=3, fallback=True, allowCompress=False, ssl=False, tweakDescriptors=(65536, 65536), compressMinSize=2097152, jsonBackend="simplejson", notifBackend="simple", dispatcherBackend="simple", auth=None, experimental=False, controlGC=True, magicVarForDispatcher="_connection", name=None, servBackend="auto")

Description 
Main class of server.
Parametrs
ipAndPort list List or sequence, containing IP and PORT or SOCKET_PATH and SOCKET.
multipleAdress bool If True, <ipAndPort> must be list, containing different <ipAndPort>. All of them will be binded to this server.
blocking bool Switch server to blocking mode (only one request per time will be processed).
cors bool | dict Add CORS headers to output (Access-Control-Allow-*). If 'dict', can contain values for <origin> and <method>.
gevent bool Patch Serv-backend and all process with Gevent.
debug bool Allow log messages from WSGI-backend.
log int | bool Set log-level or disable log messages about activity of flaskJSONRPCServer. If it's <int>, set log-level. 1 is error, 2 is warning, 3 is info, 4 is debug.
fallback bool Automatically accept and process JSONP requests.
allowCompress bool Allowing compression of output.
ssl list List or sequence, containing KEY and CERT. If passed, WSGI-backend will be switched to SSL protocol.
tweakDescriptors list(int, int) List containing new soft and hard limits of file-descriptors for current process.
compressMinSize int Max length of output in bytes that was not compressed.
jsonBackend str | obj Select JSON-backend for json.loads() and json.dumps(). If this parameter 'str' type, module with passed name will be imported. If this parameter 'obj' type, it must contain methods loads() and dumps().
dispatcherBackend str | dict | 'simple' Select default dispatcher-exec-backend for processing regular requests. Lib include some prepared backends. Variable <execBackendCollection.execBackendMap> contained all of them. If this parameter 'dict' type, it must contain 'add' key as function, that will be called on every notify-request and recive all data about request, and '_id' key, containing unique identificator. Also it must contain 'check' function, that will be called for waiting result of processed requests. Optionally it can contain 'start' and 'stop' keys as functions (it will be called when server starting or stopping).
notifBackend str | dict | 'simple' Select default dispatcher-exec-backend for processing notify-requests. Lib include some prepared backends. Variable <execBackendCollection.execBackendMap> contained all of them. If this parameter 'dict' type, it must contain 'add' key as function, that will be called on every notify-request and recive all data about request, and '_id' key, containing unique identificator. Optionally it can contain 'start' and 'stop' keys as functions (it will be called when server starting or stopping).
auth func This function will be called on every request to server 9before processing it) and must return status as 'bool' type.
experimental bool If 'True', server will be patched with 'experimental' package.
controlGC bool If 'True', server will control GarbageCollector and manually call 'gc.collect()' (by default every 60 minutes or 300k requests or 50k dispatcher's calls).
magicVarForDispatcher str Name for variable, that can be passed to every dispatcher and will contain many useful data and methods. For more info see <server>.aboutMagicVarForDispatcher.
name str Optional name of server. Also used as flaskAppName. If not passed, it will be generated automatically.
servBackend str | dict | 'auto' Select serving-backend. Lib include some prepared backends. Variable <servBackendCollection.servBackendMap> contained all of them. If this parameter 'dict' type, it must contain 'start' key as function, that will be called on server's start, and '_id' key, containing unique identificator. Optionally it can contain 'stop' key as function (it will be called when server stopping).
Return
instance Instance of class flaskJSONRPCServer

method_public callAsync(self, target, args=None, kwargs=None, sleepTime=0.45, sleepMethod=None, returnChecker=False)

Description 
This method allow to run heavy task asynchronously (without blocking server) when used with gevent, or simply in threaded-mode without gevent. It can return result of executed function, or function 'checker', that must be called for getting result (or happened errors).
Attention 
It's not a silver bullet! This method incress perfomance only for limited cases, like executing C-code or perfoming IO-ops, not frendly for gevent. It really help with <pymysql> on large responses. In all other cases it not incress perfomance, but incress responsiveness of server. This mean, while some function executed in this way, server still availible and can process other requests.
This method use hack, that combine greenlets and native threads. It can really burst responsiveness of your server, but strongly recomended to use it only for functions, that don't do any "complicated" things, like working with shared memory, threads or server's instances.
Parametrs
target func
args list
kwargs dict
sleepTime float
sleepMethod func | None If None, default will be used.
returnChecker bool If True, return function, that must be called for get result.
Return
any | func Returns result of executed function or checker.

method_public getWSGI(self)

Description 
This method return WSGI-app of server.

method_public lock(self, dispatcher=None)

Description 
This method locking server or specific dispatcher.
Parametrs
dispatcher func

method_public registerFunction(self, dispatcher, path="", fallback=None, name=None, dispatcherBackend=None, notifBackend=None)

Description 
This method reate dispatcher for given function.
If methods has attribute _alias(List or String), it used as aliases of name.
Parametrs
dispatcher instance Class's instance.
path str Optional string that contain path-prefix.
fallback bool | string Switch JSONP-mode fot this dispatcher.
name str Alternative name for this dispatcher.
dispatcherBackend str | obj Set specific backend for this dispatcher.
notifBackend str | obj Set specific backend for this dispatchers.

method_public registerInstance(self, dispatcher, path="", fallback=None, dispatcherBackend=None, notifBackend=None)

Description 
This method Create dispatcher for methods of given class's instance.
If methods has attribute _alias(List or String), it used as aliases of name.
Parametrs
dispatcher instance Class's instance.
path str Optional string that contain path-prefix.
fallback bool | string Switch JSONP-mode fot this dispatchers.
dispatcherBackend str | obj Set specific backend for this dispatchers.
notifBackend str | obj Set specific backend for this dispatchers.

method_public reload(self, api, clearOld=False, timeout=60, processingDispatcherCountMax=0, safely=True)

Description 
This method is wrapper above <server>._reload(). It overload server's source without stopping.
Example 
# example of passed <api>
api={
   'dispatcher':str() or "function" or "class's instance", # dispatcher's name (replace next param) or link to function (that will be loaded)
   'name':str(), # name of dispatcher that will overloaded
   'dispatcherName':str(), # same as <name>, for backward compatibility
   'scriptPath':str(), # path to source, that must be loaded. If not passed, main program's path will be used
   'scriptName':str(), # don't use it
   'isInstance':bool(), # is passed dispatcher instance of class
   'overload':list(), # overload this attrs in source or call this function
   'path':str() # API path for dispatcher
}
Parametrs
api list(dict) | dict see example
clearOld bool
timeout int
processingDispatcherCountMax int
safely bool

method_public restart(self, timeout=20, processingDispatcherCountMax=0, werkzeugTimeout=3, joinLoop=False)

Description 
This method call <server>.stop() and then <server>.start().
For flask's "werkzeug" WSGI backend it wait for <werkzeugTimeout> seconds after <server>.stop() for avoiding error "adress already in use".
For more info see <server>._waitProcessingDispatchers().
Parametrs
timeout int
processingDispatcherCountMax int
werkzeugTimeout int
joinLoop bool

method_public serveForever(self, restartOn=False, sleep=10)

Description 
This method is wrapper above <server>.start().
It implement logic, when this method block executing of source, placed below.
Example 
server=flaskJSONRPCServer(["127.0.0.1", "8080"])
print "before serveForever"
server.serveForever()
print "after serveForever" # you never see this message, while server runned
Parametrs
restart bool
sleep int

method_public start(self, joinLoop=False)

Description 
This method start all execute backends of server, then start serving backend (werkzeug or pywsgi for now).
If <joinLoop> is True, current thread join serving-thread.
Parametrs
joinLoop bool

method_public stats(self, inMS=False)

Description 
This method return statistics of server.
Parametrs
inMS bool If True, all speed-stats will be in milliseconds, else in seconds.
Return
dict Collected perfomance stats

method_public stop(self, timeout=20, processingDispatcherCountMax=0)

Description 
This method stop all execute backends of server, then stop serving backend (werkzeug or gevent.pywsgi for now). For more info see <server>._waitProcessingDispatchers().
Dont call this method from dispatchers!
Parametrs
timeout int
processingDispatcherCountMax int

method_public unlock(self, dispatcher=None, exclusive=False)

Description 
This method unlocking server or specific dispatcher.
If all server locked, you can unlock specific dispatcher by pass <exclusive> to True.
Parametrs
dispatcher func
exclusive bool

method_public wait(self, dispatcher=None, sleepMethod=None, returnStatus=False)

Description 
This method wait while server (or specific <dispatcher>) locked or return locking status.
If <returnStatus> is True, method only return locking status.
If <returnStatus> is False, method cyclically call <sleepMethod> until server or <dispatcher> locked. If <sleepMethod> not passed, it will be automatically selected.
Parametrs
dispatcher func
sleepMethod func
returnStatus bool

method_private _calcMimeType(self, request)

Description 
This method generate mime-type of response.
Parametrs
request Request()
Return
str

method_private _callDispatcher(self, uniqueId, path, data, request, isJSONP=False, nativeThread=None, overload=None)

Description 
This method call dispatcher, requested by client.
Parametrs
uniqueId str Unique ID of current request.
path str Server's path, that client used for sending request.
data list | dict Request's params.
request dict Reuest's and Enveronment's variables of WSGI or another backend.
isJSONP bool | str
nativeThread bool
overload dict | func Overload <_connection> param.

method_private _checkFileDescriptor(self, multiply=1.0)

Description 
This method check if used file descriptors near limit.
Parametrs
multiply float Multiply factor.
Return
bool

method_private _compressGZIP(self, data)

Description 
This method compress input data with gzip.
Parametrs
data str
Return
str

method_private _compressResponse(self, resp)

Description 
This method compress responce.
Parametrs
resp Response() Response object, prepared by WSGI backend.
Return
Response()

method_private _controlGC(self, force=False)

Description 
This method collects garbage if one off specific conditions is True or if <force> is True.
Parametrs
force bool

method_private _copyRequestContext(self, request)

Description 
This method create full copy of <request> in <dict> format (returned <dict> will not be thread-local variable).
Parametrs
request Request()
Return
dict

method_private _countFileDescriptor(self, pid=None)

Description 
This method return number of used file descriptors by process.
Parametrs
pid int | str Process ID if None then pid is ID of current proccess.
Return
int

method_private _countMemory(self, pid=None)

Description 
This method return used memory by process in kilobytes.
Parametrs
pid int Process ID if None then pid is ID of current proccess.
Return
dict {'peak': 'max used memory', 'now': 'current used memory'}

method_private _deepLock(self)

Description 
This method locks the server completely, the server doesn't process requests.

method_private _deepUnlock(self)

Description 
This method unlocks the server completely.

method_private _deepWait(self)

Description 
This method waits while server be locked.

method_private _fileGet(self, fName, mode="r")

Description 
This method open file and read content in mode <mode>, if file is archive then open it and find file with name <mode>.
Parametrs
fName str Path to file.
mode str Read-mode or file name.
Return
str

method_private _fileWrite(self, fName, text, mode="w")

Description 
This method write content to file with specific mode.
If mode is 'a' method append data to the end of file.
Parametrs
text str
fName str Path to file.
mode str Write-mode.
Return
str

method_private _findParentModule(self)

Description 
This method find parent module and pass him to attr <_parentModule> of server.

method_private _fixJSON(self, o)

Description 
This method can be called by JSON-backend and process special types.

method_private _formatPath(self, path="")

Description 
This method format path and add trailing slash.
Parametrs
str s
Return
str

method_private _getErrorInfo(self)

Description 
This method return info about last exception.
Return
str

method_private _getScriptName(self, withExt=False)

Description 
This method return name of current script. If <withExt> is True return name with extention.
Parametrs
withExt bool
Return
str

method_private _getScriptPath(self, full=False, real=True)

Description 
This method receives a way to a script. If <full> is False return only path, else return path and file name.
Parametrs
full bool

method_private _getServerUrl(self, *args)

Description 
This method return server's urls.
Return
list ['/static/<path:filename>', '/<path>/<method>/', '/<path>/<method>', '/<path>/', '/<path>'].

method_private _getms(self, inMS=True)

Description 
This method return curent(unix timestamp) time in millisecond or second.
Parametrs
inMS bool If True in millisecond, else in seconds.

method_private _import(self, modules, scope=None, forceDelete=True)

Description 
This methodReplace existed imported module and monke_putch if needed.

method_private _importAll(self, scope=None, forceDelete=True)

Description 
This method call _importThreading() and _importSocket().

method_private _importGlobalsFromParent(self, scope=None, typeOf=None, filterByName=None, filterByNameReversed=False)

Description 
This function import global attributes from parent module (main program) to given scope.
Imported attributes can be filtered by type, by name or by callback.
Source based on http://stackoverflow.com/a/9493520/5360266
Parametrs
scope None | dict Scope for add or change resulting variables. If not passed, new will be created.
typeOf None | True | func(name, value) | list Filtering by type or callback. If None, filtering disabled. If True, auto filtering by types [Int, Float, Long, Complex, None, Unicode, String, Boolean, Lambda, Dict, List, Tuple, Module, Function].
filterByName list If passed, only variables with this names will be imported.

method_private _importSocket(self, scope=None, forceDelete=True)

Description 
This method import (or patch) module <socket> to scope.
Parametrs
scope dict
forceDelete bool if True really delete existed modul before importing.
Return
scope

method_private _importThreading(self, scope=None, forceDelete=True)

Description 
This method import (or patch) module <threading>(and time.sleep) to scope.
Parametrs
scope dict
forceDelete bool if True really delete existed modul before importing.
Return
scope

method_private _inChild(self)

Description 
This methotd  retur True if used in  Child proccess or return False if used in Parent.
Return
bool

method_private _isArray(self, o)

method_private _isDict(self, o)

method_private _isFunction(self, o)

method_private _isInstance(self, o)

method_private _isModule(self, o)

method_private _isNum(self, var)

method_private _isString(self, o)

method_private _isTuple(self, o)

method_private _logger(self, level, *args)

Description 
This method is wrapper for logger. First parametr <level> is optional, if it not setted, message is interpreted as "critical" and will be shown also if logging disabled.
Parametrs
level int Info-level of message. 0 is critical (and visible always), 1 is error, 2 is warning, 3 is info, 4 is debug. If is not number, it passed as first part of message.

method_private _loggerPrep(self, level, args)

Description 
This method convert <args> to list and also implements fallback for messages without <level>.

method_private _mergeGlobalsToParent(self, scope, typeOf=None, filterByName=None, filterByNameReversed=False)

Description 
This function merge given scope with global attributes from parent module (main program).
Merged attributes can be filtered by type, by name or by callback.
Parametrs
scope dict Scope that will be merged.
typeOf None | True | func(name, value) | list Filtering by type or callback. If None, filtering disabled. If True, auto filtering by types [Int, Float, Long, Complex, None, Unicode, String, Boolean, Lambda, Dict, List, Tuple, Module, Function].
filterByName list If passed, only variables with this names will be imported.

method_private _parseJSON(self, data)

Description 
This method parse JSON-data to native object.
Parametrs
data str
Return
native

method_private _parseRequest(self, data)

Description 
This method parse reguest's data and validate.
Parametrs
data str
Return
set(bool, list) First argument is validation status.

method_private _patchWithGevent(self)

Description 
Patching current process for compatible with gevent.

method_private _prepResponse(self, data, isError=False)

Description 
This method prepare data for responce.
Parametrs
data dict
isError bool Switch response's format.
Return
dict

method_private _randomEx(self, mult=None, vals=None, pref="", suf="", soLong=0.1, cbSoLong=None)

Description 
This method generate random value from 0 to <mult> and add prefix and suffix.
Also has protection against the repeating values and against recurrence (long generation).
Parametrs
mult int | None If None, 'sys.maxint' will be used.
vals list | dict | str Blacklist of generated data.
pref str Prefix.
suf str Suffix.
soLong int Max time in seconds for generating.
cbSoLong func This function will called if generating so long. It can return new <mult>. If return None, generating will be aborted.
Return
str None if some problems or aborted.

method_private _raw_input(self, msg=None, forceNative=False)

Description 
Non-blocking console input. Without gevent uses native raw_input.
Parametrs
msg str
forceNative bool

method_private _registerExecBackend(self, execBackend, notif)

Description 
This merhod register new execute backend in server, backend will be start when <server>.start() called.
Parametrs
execBackend str | obj registered backend name or obj.
notif bool flag indicating is this backend a notification backend.
Return
unique identification.

method_private _registerServBackend(self, servBackend)

Description 
This merhod register new serving backend in server, backend will be start when <server>.start() called.
Parametrs
servBackend str | obj registered backend name or obj.
Return
unique identification.

method_private _registerServerUrl(self, urlMap, methods=None)

Description 
This method register new url on server for specific http-methods.
Parametrs
urlMap dict Map of urls and functions(handlers).
Return

method_private _reload(self, api, clearOld=False, timeout=60, processingDispatcherCountMax=0, safely=True)

Description 
This method  overload server's source without stopping.
Parametrs
api list | dict
clearOld bool
timeout int
processingDispatcherCountMax int
safely bool

method_private _requestHandler(self, path, method=None)

Description 
This method is callback, that will be called by WSGI or another backend for every request.
It implement error's handling of <server>._requestProcess() and some additional funtionality.
Parametrs
path str
method str
Return
Response()

method_private _requestProcess(self, path, method)

Description 
This method implement all logic of proccessing requests.
Parametrs
path str
method str
Return
Response()

method_private _serializeJSON(self, data)

Description 
This method convert native python object to JSON.
Parametrs
data native
Return
str

method_private _sha1(self, text, onError=None)

Description 
This method generate hash with sha1.
Length of symbols = 40.
Parametrs
text str
onError func | any
Return
str

method_private _sha256(self, text, onError=None)

Description 
This method generate hash with sha1.
Length of symbols = 64.
Parametrs
text str
onError func | any
Return
str

method_private _sleep(self, s, forceNative=False)

Description 
This method is wrapper above time.sleep() or gevent.sleep(). Method swithing automatically, if <forceNative> is False. If it's True, always use unpatched time.sleep().
Parametrs
s float Delay in seconds.
forceNative bool

method_private _socket(self)

Description 
This method returns correct socket class. For gevent return gevent's implementation.

method_private _speedStatsAdd(self, name, val)

Description 
This methos write stats about passed <name>.
Parametrs
name str
val float time in milliseconds, that will be writed to stats.

method_private _startExecBackends(self)

Description 
This merhod run all execute backends of server.

method_private _stopExecBackends(self, timeout=20, processingDispatcherCountMax=0)

Description 
This merhod stop all execute backends of server.
For more info see <server>._waitProcessingDispatchers().
Parametrs
timeout int
processingDispatcherCountMax int

method_private _strGet(self, text, pref="", suf="", index=0, default=None)

Description 
This method find prefix, then find suffix and return data between them.
If prefix is empty, prefix is beginnig of input data.
If suffix is empty, suffix is ending of input data.
Parametrs
text str Input data.
pref str Prefix.
suf str Suffix.
index int Position for finding.
default any Return this if nothing finded.
Return
str

method_private _thread(self, target, args=None, kwargs=None, forceNative=False)

Description 
This method is wrapper above threading.Thread() or gevent.spawn(). Method swithing automatically, if <forceNative> is False. If it's True, always use unpatched threading.Thread(). Spawned threads always will be started like daemons.
Parametrs
target func
args list
kwargs dict
forceNative bool

method_private _throw(self, data)

Description 
This method throw exception of class <ValueError:data>.
Parametrs
data str Info about error.

method_private _tryGevent(self)

method_private _tweakLimit(self, descriptors=(65536, 65536))

Description 
This method change file descriptor's limit of current process.
Parametrs
int) list(int, New soft and hard limit.

method_private _uncompressGZIP(self, data)

Description 
This method uncompress input data with gzip.
Parametrs
data str
Return
str

method_private _waitProcessingDispatchers(self, timeout=20, processingDispatcherCountMax=0)

Description 
This method try to wait (for <timeout> seconds), while currently runed dispatchers will be done.
If <processingDispatcherCountMax> is not 0, this check skip this nuber of runned dispatchers.
Parametrs
timeout int
processingDispatcherCountMax int

method_special __init__(self, bindAdress, multipleAdress=False, blocking=False, cors=False, gevent=False, debug=False, log=3, fallback=True, allowCompress=False, ssl=False, tweakDescriptors=(65536, 65536), compressMinSize=2097152, jsonBackend="simplejson", notifBackend="simple", dispatcherBackend="simple", auth=None, experimental=False, controlGC=True, magicVarForDispatcher="_connection", name=None, servBackend="auto")