signature:
def c6h6 ( df ) :
    """Calculs réglementaires pour le benzène
 Paramètres :
 df : DataFrame contenant les mesures , avec un index temporel
 ( voir xair . get _ mesure )
 Retourne :
 Une série de résultats dans un DataFrame :
 unité ( u ) : μg / m3 ( microgramme par mètre cube )
 Objectif de qualité en moyenne A : 2u
 Valeur limite pour la santé humaine en moyenne A : 5u
 Les résultats sont donnés en terme d ' heure de dépassement"""

implementation:
polluant = 'C6H6'
# Le DataFrame doit être en heure
if not isinstance ( df . index . freq , pdoffset . Hour ) :
    raise FreqException ( "df doit être en heure." )
res = { "Objectif de qualité en moyenne A: 2u" : depassement ( df . resample ( 'A' , how = 'mean' ) , valeur = 2 ) , "Valeur limite pour la santé humaine en moyenne A: 5u" : depassement ( df . resample ( 'A' , how = 'mean' ) , valeur = 5 ) , }
return polluant , res


signature:
def arsenic ( df ) :
    """Calculs réglementaires pour l ' arsenic
 Paramètres :
 df : DataFrame contenant les mesures , avec un index temporel
 ( voir xair . get _ mesure )
 Retourne :
 Une série de résultats dans un DataFrame :
 unité ( u ) : ng / m3 ( nanogramme par mètre cube )
 Valeur cible en moyenne A : 6u
 Les résultats sont donnés en terme d ' heure de dépassement"""

implementation:
polluant = 'As'
# Le DataFrame doit être en heure
if not isinstance ( df . index . freq , pdoffset . Hour ) :
    raise FreqException ( "df doit être en heure." )
res = { "Valeur cible en moyenne A: 6u" : depassement ( df . resample ( 'A' , how = 'mean' ) , valeur = 6 ) , }
return polluant , res


signature:
def print_synthese ( fct , df ) :
    """Présente une synthèse des calculs réglementaires en fournissant les valeurs
 calculées suivant les réglementations définies dans chaque fonction de calcul
 et un tableau de nombre de dépassement .
 Paramètres :
 fct : fonction renvoyant les éléments calculées
 df : DataFrame de valeurs d ' entrée à fournir à la fonction
 Retourne :
 Imprime sur l ' écran les valeurs synthétisées"""

implementation:
res_count = dict ( )
polluant , res = fct ( df )
print ( "\nPour le polluant: %s" % polluant )
print ( "\nValeurs mesurées suivant critères:" )
for k , v in res . items ( ) :
    comp = compresse ( v )
    if not comp . empty :
        comp . index . name = k
        print ( comp . to_string ( na_rep = '' , float_format = lambda x : "%.0f" % x ) )
    else :
        print ( "\n%s: aucune valeur en dépassement" % k )
    res_count [ k ] = v . count ( )
res_count = pd . DataFrame ( res_count ) . T
print ( "Nombre de dépassements des critères:\n" )
print ( res_count )


signature:
def excel_synthese ( fct , df , excel_file ) :
    """Enregistre dans un fichier Excel une synthèse des calculs réglementaires en
 fournissant les valeurs calculées suivant les réglementations définies dans
 chaque fonction de calcul et un tableau de nombre de dépassement .
 Les résultats sont enregistrés
 Paramètres :
 fct : fonction renvoyant les éléments calculées
 df : DataFrame de valeurs d ' entrée à fournir à la fonction
 excel _ file : Chemin du fichier excel où écrire les valeurs
 Retourne :
 Rien"""

implementation:
def sheet_name ( name ) : # formatage du nom des feuilles ( suppression des guillements , : , . . . )
    name = unicodedata . normalize ( 'NFKD' , name ) . encode ( 'ascii' , 'ignore' )
    name = k . replace ( "'" , "" ) . replace ( ":" , "" ) . replace ( " " , "_" )
    name = "%i-%s" % ( i , name )
    name = name [ : 31 ]
    return name
res_count = dict ( )
polluant , res = fct ( df )
print ( "\nTraitement du polluant: %s" % polluant )
writer = pd . ExcelWriter ( excel_file )
# Valeurs mesurées suivant critères
for i , ( k , v ) in enumerate ( res . items ( ) ) :
    comp = compresse ( v )
    comp . index . name = k
    comp = comp . apply ( pd . np . round )
    comp . to_excel ( writer , sheet_name = sheet_name ( k ) )
    res_count [ k ] = v . count ( )
# Nombre de dépassements des critères
name = "Nombre_de_depassements"
res_count = pd . DataFrame ( res_count ) . T
res_count . index . name = name
res_count . to_excel ( writer , sheet_name = name )
writer . save ( )


signature:
def html_synthese ( fct , df ) :
    """Retourne au format html une synthèse des calculs réglementaires en
 fournissant les valeurs calculées suivant les réglementations définies dans
 chaque fonction de calcul et un tableau de nombre de dépassement .
 Paramètres :
 fct : fonction renvoyant les éléments calculées
 df : DataFrame de valeurs d ' entrée à fournir à la fonction
 Retourne :
 Une chaine de caractère prête à être utilisé dans une page html"""

implementation:
html = str ( )
res_count = dict ( )
buf = StringIO ( )
polluant , res = fct ( df )
html += '

Pour le polluant: {}

' . format ( polluant )
# On enregistre tous les résultats dans le buffer et on calcule la somme de chaque
for k , v in res . items ( ) :
    buf . write ( "
" )
    comp = compresse ( v )
    if not comp . empty :
        comp . index . name = k
        comp . to_html ( buf = buf , sparsify = True , na_rep = "" )
    else :
        buf . write ( '

{}	Aucun dépassement

' . format ( k ) )
    buf . write ( "
" )
    res_count [ k ] = v . count ( )
res_count = pd . DataFrame ( res_count ) . T
res_count . index . name = "Nombre de dépassements des critères"
html += "
"
html += res_count . to_html ( sparsify = True )
html += "
"
html += buf . getvalue ( )
return html


signature:
def show_max ( df ) :
    """Pour chaque serie ( colonne ) d ' un DataFrame , va rechercher la ( les ) valeur ( s )
 et la ( les ) date ( s ) du ( des ) max .
 Paramètres :
 df : DataFrame de valeurs à calculer
 Retourne :
 Un DataFrame montrant pour chaque serie ( colonne ) , les valeurs maxs aux dates
 d ' apparition ."""

implementation:
df = df . astype ( pd . np . float )
res = list ( )
for c in df . columns :
    serie = df [ c ]
    res . append ( serie . where ( cond = serie == serie . max ( ) , other = pd . np . nan ) . dropna ( ) )
return pd . DataFrame ( res ) . T


signature:
def taux_de_representativite ( df ) :
    """Calcul le taux de représentativité d ' un dataframe"""

implementation: return ( df . count ( ) . astype ( pd . np . float ) / df . shape [ 0 ] * 100 ) . round ( 1 )


signature:
def validate ( self ) :
    '''Validate all the entries in the environment cache .'''

implementation:
for env in list ( self ) :
    if not env . exists :
        self . remove ( env )


signature:
def load ( self ) :
    '''Load the environment cache from disk .'''

implementation:
if not os . path . exists ( self . path ) :
    return
with open ( self . path , 'r' ) as f :
    env_data = yaml . load ( f . read ( ) )
if env_data :
    for env in env_data :
        self . add ( VirtualEnvironment ( env [ 'root' ] ) )


signature:
def save ( self ) :
    '''Save the environment cache to disk .'''

implementation:
env_data = [ dict ( name = env . name , root = env . path ) for env in self ]
encode = yaml . safe_dump ( env_data , default_flow_style = False )
with open ( self . path , 'w' ) as f :
    f . write ( encode )


signature:
def prompt ( text , default = None , hide_input = False , confirmation_prompt = False , type = None , value_proc = None , prompt_suffix = ': ' , show_default = True , err = False ) :
    """Prompts a user for input . This is a convenience function that can
 be used to prompt a user for input later .
 If the user aborts the input by sending a interrupt signal , this
 function will catch it and raise a : exc : ` Abort ` exception .
 . . versionadded : : 6.0
 Added unicode support for cmd . exe on Windows .
 . . versionadded : : 4.0
 Added the ` err ` parameter .
 : param text : the text to show for the prompt .
 : param default : the default value to use if no input happens . If this
 is not given it will prompt until it ' s aborted .
 : param hide _ input : if this is set to true then the input value will
 be hidden .
 : param confirmation _ prompt : asks for confirmation for the value .
 : param type : the type to use to check the value against .
 : param value _ proc : if this parameter is provided it ' s a function that
 is invoked instead of the type conversion to
 convert a value .
 : param prompt _ suffix : a suffix that should be added to the prompt .
 : param show _ default : shows or hides the default value in the prompt .
 : param err : if set to true the file defaults to ` ` stderr ` ` instead of
 ` ` stdout ` ` , the same as with echo ."""

implementation:
result = None
def prompt_func ( text ) :
    f = hide_input and hidden_prompt_func or visible_prompt_func
    try : # Write the prompt separately so that we get nice
    # coloring through colorama on Windows
        echo ( text , nl = False , err = err )
        return f ( '' )
    except ( KeyboardInterrupt , EOFError ) : # getpass doesn ' t print a newline if the user aborts input with ^ C .
    # Allegedly this behavior is inherited from getpass ( 3 ) .
    # A doc bug has been filed at https : / / bugs . python . org / issue24711
        if hide_input :
            echo ( None , err = err )
        raise Abort ( )
if value_proc is None :
    value_proc = convert_type ( type , default )
prompt = _build_prompt ( text , prompt_suffix , show_default , default )
while 1 :
    while 1 :
        value = prompt_func ( prompt )
        if value :
            break
        # If a default is set and used , then the confirmation
        # prompt is always skipped because that ' s the only thing
        # that really makes sense .
        elif default is not None :
            return default
    try :
        result = value_proc ( value )
    except UsageError as e :
        echo ( 'Error: %s' % e . message , err = err )
        continue
    if not confirmation_prompt :
        return result
    while 1 :
        value2 = prompt_func ( 'Repeat for confirmation: ' )
        if value2 :
            break
    if value == value2 :
        return result
    echo ( 'Error: the two entered values do not match' , err = err )


signature:
def echo_via_pager ( text , color = None ) :
    """This function takes a text and shows it via an environment specific
 pager on stdout .
 . . versionchanged : : 3.0
 Added the ` color ` flag .
 : param text : the text to page .
 : param color : controls if the pager supports ANSI colors or not . The
 default is autodetection ."""

implementation:
color = resolve_color_default ( color )
if not isinstance ( text , string_types ) :
    text = text_type ( text )
from . _termui_impl import pager
return pager ( text + '\n' , color )


signature:
def _remote_setup_engine ( engine_id , nengines ) :
    """( Executed on remote engine ) creates an ObjectEngine instance"""

implementation:
if distob . engine is None :
    distob . engine = distob . ObjectEngine ( engine_id , nengines )
# TODO these imports should be unnecessary with improved deserialization
import numpy as np
from scipy import stats
# TODO Using @ ipyparallel . interactive still did not import to _ _ main _ _
# so will do it this way for now .
import __main__
__main__ . __dict__ [ 'np' ] = np
__main__ . __dict__ [ 'stats' ] = stats


signature:
def setup_engines ( client = None ) :
    """Prepare all iPython engines for distributed object processing .
 Args :
 client ( ipyparallel . Client , optional ) : If None , will create a client
 using the default ipyparallel profile ."""

implementation:
if not client :
    try :
        client = ipyparallel . Client ( )
    except :
        raise DistobClusterError ( u"""Could not connect to an ipyparallel cluster. Make
                 sure a cluster is started (e.g. to use the CPUs of a
                 single computer, can type 'ipcluster start')""" )
eids = client . ids
if not eids :
    raise DistobClusterError ( u'No ipyparallel compute engines are available' )
nengines = len ( eids )
dv = client [ eids ]
dv . use_dill ( )
with dv . sync_imports ( quiet = True ) :
    import distob
# create global ObjectEngine distob . engine on each engine
ars = [ ]
for i in eids :
    dv . targets = i
    ars . append ( dv . apply_async ( _remote_setup_engine , i , nengines ) )
dv . wait ( ars )
for ar in ars :
    if not ar . successful ( ) :
        raise ar . r
# create global ObjectHub distob . engine on the client host
if distob . engine is None :
    distob . engine = ObjectHub ( - 1 , client )


signature:
def _process_args ( args , kwargs , prefer_local = True , recurse = True ) :
    """Select local or remote execution and prepare arguments accordingly .
 Assumes any remote args have already been moved to a common engine .
 Local execution will be chosen if :
 - all args are ordinary objects or Remote instances on the local engine ; or
 - the local cache of all remote args is current , and prefer _ local is True .
 Otherwise , remote execution will be chosen .
 For remote execution , replaces any remote arg with its Id .
 For local execution , replaces any remote arg with its locally cached object
 Any arguments or kwargs that are Sequences will be recursed one level deep .
 Args :
 args ( list )
 kwargs ( dict )
 prefer _ local ( bool , optional ) : Whether cached local results are prefered
 if available , instead of returning Remote objects . Default is True ."""

implementation:
this_engine = distob . engine . eid
local_args = [ ]
remote_args = [ ]
execloc = this_engine
# the chosen engine id for execution of the call
for a in args :
    id = None
    if isinstance ( a , Remote ) :
        id = a . _ref . id
    elif isinstance ( a , Ref ) :
        id = a . id
    elif isinstance ( a , Id ) :
        id = a
    if id is not None :
        if id . engine is this_engine :
            local_args . append ( distob . engine [ id ] )
            remote_args . append ( distob . engine [ id ] )
        else :
            if ( prefer_local and isinstance ( a , Remote ) and a . _obcache_current ) :
                local_args . append ( a . _obcache )
                remote_args . append ( id )
            else : # will choose remote execution
                if execloc is not this_engine and id . engine is not execloc :
                    raise DistobValueError ( 'two remote arguments are from different engines' )
                else :
                    execloc = id . engine
                    local_args . append ( None )
                    remote_args . append ( id )
    elif ( isinstance ( a , collections . Sequence ) and not isinstance ( a , string_types ) and recurse ) :
        eid , ls , _ = _process_args ( a , { } , prefer_local , recurse = False )
        if eid is not this_engine :
            if execloc is not this_engine and eid is not execloc :
                raise DistobValueError ( 'two remote arguments are from different engines' )
            execloc = eid
        local_args . append ( ls )
        remote_args . append ( ls )
    else : # argument is an ordinary object
        local_args . append ( a )
        remote_args . append ( a )
local_kwargs = dict ( )
remote_kwargs = dict ( )
for k , a in kwargs . items ( ) :
    id = None
    if isinstance ( a , Remote ) :
        id = a . _ref . id
    elif isinstance ( a , Ref ) :
        id = a . id
    elif isinstance ( a , Id ) :
        id = a
    if id is not None :
        if id . engine is this_engine :
            local_kwargs [ k ] = distob . engine [ id ]
            remote_kwargs [ k ] = distob . engine [ id ]
        else :
            if ( prefer_local and isinstance ( a , Remote ) and a . _obcache_current ) :
                local_kwargs [ k ] = a . _obcache
                remote_kwargs [ k ] = id
            else : # will choose remote execution
                if execloc is not this_engine and id . engine is not execloc :
                    raise DistobValueError ( 'two remote arguments are from different engines' )
                else :
                    execloc = id . engine
                    local_kwargs [ k ] = None
                    remote_kwargs [ k ] = id
    elif ( isinstance ( a , collections . Sequence ) and not isinstance ( a , string_types ) and recurse ) :
        eid , ls , _ = _process_args ( a , { } , prefer_local , recurse = False )
        if eid is not this_engine :
            if execloc is not this_engine and eid is not execloc :
                raise DistobValueError ( 'two remote arguments are from different engines' )
            execloc = eid
        local_kwargs [ k ] = ls
        remote_kwargs [ k ] = ls
    else : # argument is an ordinary object
        local_kwargs [ k ] = a
        remote_kwargs [ k ] = a
if execloc is this_engine :
    return execloc , tuple ( local_args ) , local_kwargs
else :
    return execloc , tuple ( remote_args ) , remote_kwargs


signature:
def _remote_call ( f , * args , ** kwargs ) :
    """( Executed on remote engine ) convert Ids to real objects , call f"""

implementation:
nargs = [ ]
for a in args :
    if isinstance ( a , Id ) :
        nargs . append ( distob . engine [ a ] )
    elif ( isinstance ( a , collections . Sequence ) and not isinstance ( a , string_types ) ) :
        nargs . append ( [ distob . engine [ b ] if isinstance ( b , Id ) else b for b in a ] )
    else :
        nargs . append ( a )
for k , a in kwargs . items ( ) :
    if isinstance ( a , Id ) :
        kwargs [ k ] = distob . engine [ a ]
    elif ( isinstance ( a , collections . Sequence ) and not isinstance ( a , string_types ) ) :
        kwargs [ k ] = [ distob . engine [ b ] if isinstance ( b , Id ) else b for b in a ]
result = f ( * nargs , ** kwargs )
if ( isinstance ( result , collections . Sequence ) and not isinstance ( result , string_types ) ) : # We will return any sub - sequences by value , not recurse deeper
    results = [ ]
    for subresult in result :
        if type ( subresult ) in distob . engine . proxy_types :
            results . append ( Ref ( subresult ) )
        else :
            results . append ( subresult )
    return results
elif type ( result ) in distob . engine . proxy_types :
    return Ref ( result )
else :
    return result


signature:
def call ( f , * args , ** kwargs ) :
    """Execute f on the arguments , either locally or remotely as appropriate .
 If there are multiple remote arguments , they must be on the same engine .
 kwargs :
 prefer _ local ( bool , optional ) : Whether to return cached local results if
 available , in preference to returning Remote objects . Default is True .
 block ( bool , optional ) : Whether remote calls should be synchronous .
 If False , returned results may be AsyncResults and should be converted
 by the caller using convert _ result ( ) before use . Default is True ."""

implementation:
this_engine = distob . engine . eid
prefer_local = kwargs . pop ( 'prefer_local' , True )
block = kwargs . pop ( 'block' , True )
execloc , args , kwargs = _process_args ( args , kwargs , prefer_local )
if execloc is this_engine :
    r = f ( * args , ** kwargs )
else :
    if False and prefer_local : # result cache disabled until issue mattja / distob # 1 is fixed
        try :
            kwtuple = tuple ( ( k , kwargs [ k ] ) for k in sorted ( kwargs . keys ( ) ) )
            key = ( f , args , kwtuple )
            r = _call_cache [ key ]
        except TypeError as te :
            if te . args [ 0 ] [ : 10 ] == 'unhashable' : # print ( " unhashable . won ' t be able to cache " )
                r = _uncached_call ( execloc , f , * args , ** kwargs )
            else :
                raise
        except KeyError :
            r = _uncached_call ( execloc , f , * args , ** kwargs )
            if block :
                _call_cache [ key ] = r . r
    else :
        r = _uncached_call ( execloc , f , * args , ** kwargs )
if block :
    return convert_result ( r )
else :
    return r


signature:
def convert_result ( r ) :
    """Waits for and converts any AsyncResults . Converts any Ref into a Remote .
 Args :
 r : can be an ordinary object , ipyparallel . AsyncResult , a Ref , or a
 Sequence of objects , AsyncResults and Refs .
 Returns :
 either an ordinary object or a Remote instance"""

implementation:
if ( isinstance ( r , collections . Sequence ) and not isinstance ( r , string_types ) ) :
    rs = [ ]
    for subresult in r :
        rs . append ( convert_result ( subresult ) )
    return rs
if isinstance ( r , ipyparallel . AsyncResult ) :
    r = r . r
if isinstance ( r , Ref ) :
    RemoteClass = distob . engine . proxy_types [ r . type ]
    r = RemoteClass ( r )
return r


signature:
def _remote_methodcall ( id , method_name , * args , ** kwargs ) :
    """( Executed on remote engine ) convert Ids to real objects , call method"""

implementation:
obj = distob . engine [ id ]
nargs = [ ]
for a in args :
    if isinstance ( a , Id ) :
        nargs . append ( distob . engine [ a ] )
    elif ( isinstance ( a , collections . Sequence ) and not isinstance ( a , string_types ) ) :
        nargs . append ( [ distob . engine [ b ] if isinstance ( b , Id ) else b for b in a ] )
    else :
        nargs . append ( a )
for k , a in kwargs . items ( ) :
    if isinstance ( a , Id ) :
        kwargs [ k ] = distob . engine [ a ]
    elif ( isinstance ( a , collections . Sequence ) and not isinstance ( a , string_types ) ) :
        kwargs [ k ] = [ distob . engine [ b ] if isinstance ( b , Id ) else b for b in a ]
result = getattr ( obj , method_name ) ( * nargs , ** kwargs )
if ( isinstance ( result , collections . Sequence ) and not isinstance ( result , string_types ) ) : # We will return any sub - sequences by value , not recurse deeper
    results = [ ]
    for subresult in result :
        if type ( subresult ) in distob . engine . proxy_types :
            results . append ( Ref ( subresult ) )
        else :
            results . append ( subresult )
    return results
elif type ( result ) in distob . engine . proxy_types :
    return Ref ( result )
else :
    return result


signature:
def methodcall ( obj , method_name , * args , ** kwargs ) :
    """Call a method of ` obj ` , either locally or remotely as appropriate .
 obj may be an ordinary object , or a Remote object ( or Ref or object Id )
 If there are multiple remote arguments , they must be on the same engine .
 kwargs :
 prefer _ local ( bool , optional ) : Whether to return cached local results if
 available , in preference to returning Remote objects . Default is True .
 block ( bool , optional ) : Whether remote calls should be synchronous .
 If False , returned results may be AsyncResults and should be converted
 by the caller using convert _ result ( ) before use . Default is True ."""

implementation:
this_engine = distob . engine . eid
args = [ obj ] + list ( args )
prefer_local = kwargs . pop ( 'prefer_local' , None )
if prefer_local is None :
    if isinstance ( obj , Remote ) :
        prefer_local = obj . prefer_local
    else :
        prefer_local = True
block = kwargs . pop ( 'block' , True )
execloc , args , kwargs = _process_args ( args , kwargs , prefer_local )
if execloc is this_engine :
    r = getattr ( args [ 0 ] , method_name ) ( * args [ 1 : ] , ** kwargs )
else :
    if False and prefer_local : # result cache disabled until issue mattja / distob # 1 is fixed
        try :
            kwtuple = tuple ( ( k , kwargs [ k ] ) for k in sorted ( kwargs . keys ( ) ) )
            key = ( args [ 0 ] , method_name , args , kwtuple )
            r = _call_cache [ key ]
        except TypeError as te :
            if te . args [ 0 ] [ : 10 ] == 'unhashable' : # print ( " unhashable . won ' t be able to cache " )
                r = _uncached_methodcall ( execloc , args [ 0 ] , method_name , * args [ 1 : ] , ** kwargs )
            else :
                raise
        except KeyError :
            r = _uncached_methodcall ( execloc , args [ 0 ] , method_name , * args [ 1 : ] , ** kwargs )
            if block :
                _call_cache [ key ] = r . r
    else :
        r = _uncached_methodcall ( execloc , args [ 0 ] , method_name , * args [ 1 : ] , ** kwargs )
if block :
    return convert_result ( r )
else :
    return r


signature:
def _scan_instance ( obj , include_underscore , exclude ) :
    """( Executed on remote or local engine ) Examines an object and returns info
 about any instance - specific methods or attributes .
 ( For example , any attributes that were set by _ _ init _ _ ( ) )
 By default , methods or attributes starting with an underscore are ignored .
 Args :
 obj ( object ) : the object to scan . must be on this local engine .
 include _ underscore ( bool or sequence of str ) : Should methods or
 attributes that start with an underscore be proxied anyway ? If a
 sequence of names is provided then methods or attributes starting with
 an underscore will only be proxied if their names are in the sequence .
 exclude ( sequence of str ) : names of any methods or attributes that should
 not be reported ."""

implementation:
from sys import getsizeof
always_exclude = ( '__new__' , '__init__' , '__getattribute__' , '__class__' , '__reduce__' , '__reduce_ex__' )
method_info = [ ]
attributes_info = [ ]
if hasattr ( obj , '__dict__' ) :
    for name in obj . __dict__ :
        if ( name not in exclude and name not in always_exclude and ( name [ 0 ] != '_' or include_underscore is True or name in include_underscore ) ) :
            f = obj . __dict__ [ name ]
            if hasattr ( f , '__doc__' ) :
                doc = f . __doc__
            else :
                doc = None
            if callable ( f ) and not isinstance ( f , type ) :
                method_info . append ( ( name , doc ) )
            else :
                attributes_info . append ( ( name , doc ) )
return ( method_info , attributes_info , getsizeof ( obj ) )


signature:
def proxy_methods ( base , include_underscore = None , exclude = None , supers = True ) :
    """class decorator . Modifies ` Remote ` subclasses to add proxy methods and
 attributes that mimic those defined in class ` base ` .
 Example :
 @ proxy _ methods ( Tree )
 class RemoteTree ( Remote , Tree )
 The decorator registers the new proxy class and specifies which methods
 and attributes of class ` base ` should be proxied via a remote call to
 a real object , and which methods / attributes should not be proxied but
 instead called directly on the instance of the proxy class .
 By default all methods and attributes of the class ` base ` will be
 proxied except those starting with an underscore .
 The MRO of the decorated class is respected :
 Any methods and attributes defined in the decorated class
 ( or in other bases of the decorated class that do not come after ` base `
 in its MRO ) will override those added by this decorator ,
 so that ` base ` is treated like a base class .
 Args :
 base ( type ) : The class whose instances should be remotely controlled .
 include _ underscore ( bool or sequence of str ) : Should methods or
 attributes that start with an underscore be proxied anyway ? If a
 sequence of names is provided then methods or attributes starting with
 an underscore will only be proxied if their names are in the sequence .
 exclude ( sequence of str ) : Names of any methods or attributes that
 should not be proxied .
 supers ( bool ) : Proxy methods and attributes defined in superclasses
 of ` ` base ` ` , in addition to those defined directly in class ` ` base ` `"""

implementation:
always_exclude = ( '__new__' , '__init__' , '__getattribute__' , '__class__' , '__reduce__' , '__reduce_ex__' )
if isinstance ( include_underscore , str ) :
    include_underscore = ( include_underscore , )
if isinstance ( exclude , str ) :
    exclude = ( exclude , )
if not include_underscore :
    include_underscore = ( )
if not exclude :
    exclude = ( )
def rebuild_class ( cls ) : # Identify any bases of cls that do not come after ` base ` in the list :
    bases_other = list ( cls . __bases__ )
    if bases_other [ - 1 ] is object :
        bases_other . pop ( )
    if base in bases_other :
        bases_other = bases_other [ : bases_other . index ( base ) ]
    if not issubclass ( cls . __bases__ [ 0 ] , Remote ) :
        raise DistobTypeError ( 'First base class must be subclass of Remote' )
    if not issubclass ( base , object ) :
        raise DistobTypeError ( 'Only new-style classes currently supported' )
    dct = cls . __dict__ . copy ( )
    if cls . __doc__ is None or '\n' not in cls . __doc__ :
        base_doc = base . __doc__
        if base_doc is None :
            base_doc = ''
        dct [ '__doc__' ] = """Local object representing a remote %s
                  It can be used just like a %s object, but behind the scenes
                  all requests are passed to a real %s object on a remote host.

                  """ % ( ( base . __name__ , ) * 3 ) + base_doc
    newcls = type ( cls . __name__ , cls . __bases__ , dct )
    newcls . _include_underscore = include_underscore
    newcls . _exclude = exclude
    if supers :
        proxied_classes = base . __mro__ [ : - 1 ]
    else :
        proxied_classes = ( base , )
    for c in proxied_classes :
        for name in c . __dict__ : # respect MRO : proxy an attribute only if it is not overridden
            if ( name not in newcls . __dict__ and all ( name not in b . __dict__ for c in bases_other for b in c . mro ( ) [ : - 1 ] ) and name not in newcls . _exclude and name not in always_exclude and ( name [ 0 ] != '_' or newcls . _include_underscore is True or name in newcls . _include_underscore ) ) :
                f = c . __dict__ [ name ]
                if hasattr ( f , '__doc__' ) :
                    doc = f . __doc__
                else :
                    doc = None
                if callable ( f ) and not isinstance ( f , type ) :
                    setattr ( newcls , name , _make_proxy_method ( name , doc ) )
                else :
                    setattr ( newcls , name , _make_proxy_property ( name , doc ) )
    newcls . __module__ = '__main__'
    # cause dill to pickle it whole
    import __main__
    __main__ . __dict__ [ newcls . __name__ ] = newcls
    # for dill . .
    ObjectHub . register_proxy_type ( base , newcls )
    return newcls
return rebuild_class


signature:
def _async_scatter ( obj , destination = None ) :
    """Distribute an obj or list to remote engines .
 Return an async result or ( possibly nested ) lists of async results ,
 each of which is a Ref"""

implementation:
# TODO Instead of special cases for strings and Remote , should have a
# list of types that should not be proxied , inc . strings and Remote .
if ( isinstance ( obj , Remote ) or isinstance ( obj , numbers . Number ) or obj is None ) :
    return obj
if ( isinstance ( obj , collections . Sequence ) and not isinstance ( obj , string_types ) ) :
    ars = [ ]
    if destination is not None :
        assert ( len ( destination ) == len ( obj ) )
        for i in range ( len ( obj ) ) :
            ars . append ( _async_scatter ( obj [ i ] , destination [ i ] ) )
    else :
        for i in range ( len ( obj ) ) :
            ars . append ( _async_scatter ( obj [ i ] , destination = None ) )
    return ars
else :
    if distob . engine is None :
        setup_engines ( )
    client = distob . engine . _client
    dv = distob . engine . _dv
    def remote_put ( obj ) :
        return Ref ( obj )
    if destination is not None :
        assert ( isinstance ( destination , numbers . Integral ) )
        dv . targets = destination
    else :
        dv . targets = _async_scatter . next_engine
        _async_scatter . next_engine = ( _async_scatter . next_engine + 1 ) % len ( client )
    ar_ref = dv . apply_async ( remote_put , obj )
    dv . targets = client . ids
    return ar_ref


signature:
def _ars_to_proxies ( ars ) :
    """wait for async results and return proxy objects
 Args :
 ars : AsyncResult ( or sequence of AsyncResults ) , each result type ` ` Ref ` ` .
 Returns :
 Remote * proxy object ( or list of them )"""

implementation:
if ( isinstance ( ars , Remote ) or isinstance ( ars , numbers . Number ) or ars is None ) :
    return ars
elif isinstance ( ars , collections . Sequence ) :
    res = [ ]
    for i in range ( len ( ars ) ) :
        res . append ( _ars_to_proxies ( ars [ i ] ) )
    return res
elif isinstance ( ars , ipyparallel . AsyncResult ) :
    ref = ars . r
    ObClass = ref . type
    if ObClass in distob . engine . proxy_types :
        RemoteClass = distob . engine . proxy_types [ ObClass ]
    else :
        RemoteClass = type ( 'Remote' + ObClass . __name__ , ( Remote , ObClass ) , dict ( ) )
        RemoteClass = proxy_methods ( ObClass ) ( RemoteClass )
    proxy_obj = RemoteClass ( ref )
    return proxy_obj
else :
    raise DistobTypeError ( 'Unpacking ars: unexpected type %s' % type ( ars ) )


signature:
def _scatter_ndarray ( ar , axis = - 1 , destination = None , blocksize = None ) :
    """Turn a numpy ndarray into a DistArray or RemoteArray
 Args :
 ar ( array _ like )
 axis ( int , optional ) : specifies along which axis to split the array to
 distribute it . The default is to split along the last axis . ` None ` means
 do not distribute .
 destination ( int or list of int , optional ) : Optionally force the array to
 go to a specific engine . If an array is to be scattered along an axis ,
 this should be a list of engine ids with the same length as that axis .
 blocksize ( int ) : Optionally control the size of intervals into which the
 distributed axis is split ( the default splits the distributed axis
 evenly over all computing engines ) ."""

implementation:
from . arrays import DistArray , RemoteArray
shape = ar . shape
ndim = len ( shape )
if axis is None :
    return _directed_scatter ( [ ar ] , destination = [ destination ] , blocksize = blocksize ) [ 0 ]
if axis < - ndim or axis > ndim - 1 :
    raise DistobValueError ( 'axis out of range' )
if axis < 0 :
    axis = ndim + axis
n = shape [ axis ]
if n == 1 :
    return _directed_scatter ( [ ar ] , destination = [ destination ] ) [ 0 ]
if isinstance ( destination , collections . Sequence ) :
    ne = len ( destination )
    # number of engines to scatter array to
else :
    if distob . engine is None :
        setup_engines ( )
    ne = distob . engine . nengines
    # by default scatter across all engines
if blocksize is None :
    blocksize = ( ( n - 1 ) // ne ) + 1
if blocksize > n :
    blocksize = n
if isinstance ( ar , DistArray ) :
    if axis == ar . _distaxis :
        return ar
    else :
        raise DistobError ( 'Currently can only scatter one axis of array' )
# Currently , if requested to scatter an array that is already Remote and
# large , first get whole array locally , then scatter . Not really optimal .
if isinstance ( ar , RemoteArray ) and n > blocksize :
    ar = ar . _ob
s = slice ( None )
subarrays = [ ]
low = 0
for i in range ( 0 , n // blocksize ) :
    high = low + blocksize
    index = ( s , ) * axis + ( slice ( low , high ) , ) + ( s , ) * ( ndim - axis - 1 )
    subarrays . append ( ar [ index ] )
    low += blocksize
if n % blocksize != 0 :
    high = low + ( n % blocksize )
    index = ( s , ) * axis + ( slice ( low , high ) , ) + ( s , ) * ( ndim - axis - 1 )
    subarrays . append ( ar [ index ] )
subarrays = _directed_scatter ( subarrays , destination = destination )
return DistArray ( subarrays , axis )


signature:
def scatter ( obj , axis = - 1 , blocksize = None ) :
    """Distribute obj or list to remote engines , returning proxy objects
 Args :
 obj : any python object , or list of objects
 axis ( int , optional ) : Can be used if scattering a numpy array ,
 specifying along which axis to split the array to distribute it . The
 default is to split along the last axis . ` None ` means do not distribute
 blocksize ( int , optional ) : Can be used if scattering a numpy array .
 Optionally control the size of intervals into which the distributed
 axis is split ( the default splits the distributed axis evenly over all
 computing engines ) ."""

implementation:
if hasattr ( obj , '__distob_scatter__' ) :
    return obj . __distob_scatter__ ( axis , None , blocksize )
if distob . _have_numpy and ( isinstance ( obj , np . ndarray ) or hasattr ( type ( obj ) , '__array_interface__' ) ) :
    return _scatter_ndarray ( obj , axis , blocksize )
elif isinstance ( obj , Remote ) :
    return obj
ars = _async_scatter ( obj )
proxy_obj = _ars_to_proxies ( ars )
return proxy_obj


signature:
def gather ( obj ) :
    """Retrieve objects that have been distributed , making them local again"""

implementation:
if hasattr ( obj , '__distob_gather__' ) :
    return obj . __distob_gather__ ( )
elif ( isinstance ( obj , collections . Sequence ) and not isinstance ( obj , string_types ) ) :
    return [ gather ( subobj ) for subobj in obj ]
else :
    return obj


signature:
def vectorize ( f ) :
    """Upgrade normal function f to act in parallel on distibuted lists / arrays
 Args :
 f ( callable ) : an ordinary function which expects as its first argument a
 single object , or a numpy array of N dimensions .
 Returns :
 vf ( callable ) : new function that takes as its first argument a list of
 objects , or a array of N + 1 dimensions . ` ` vf ( ) ` ` will do the
 computation ` ` f ( ) ` ` on each part of the input in parallel and will
 return a list of results , or a distributed array of results ."""

implementation:
def vf ( obj , * args , ** kwargs ) : # user classes can customize how to vectorize a function :
    if hasattr ( obj , '__distob_vectorize__' ) :
        return obj . __distob_vectorize__ ( f ) ( obj , * args , ** kwargs )
    if isinstance ( obj , Remote ) :
        return call ( f , obj , * args , ** kwargs )
    elif distob . _have_numpy and ( isinstance ( obj , np . ndarray ) or hasattr ( type ( obj ) , '__array_interface__' ) ) :
        distarray = scatter ( obj , axis = - 1 )
        return vf ( distarray , * args , ** kwargs )
    elif isinstance ( obj , collections . Sequence ) :
        inputs = scatter ( obj )
        dv = distob . engine . _client [ : ]
        kwargs = kwargs . copy ( )
        kwargs [ 'block' ] = False
        results = [ ]
        for obj in inputs :
            results . append ( call ( f , obj , * args , ** kwargs ) )
        for i in range ( len ( results ) ) :
            results [ i ] = convert_result ( results [ i ] )
        return results
if hasattr ( f , '__name__' ) :
    vf . __name__ = 'v' + f . __name__
    f_str = f . __name__ + '()'
else :
    f_str = 'callable'
doc = u"""Apply %s in parallel to a list or array\n
           Args:
             obj (Sequence of objects or an array)
             other args are the same as for %s
           """ % ( f_str , f_str )
if hasattr ( f , '__doc__' ) and f . __doc__ is not None :
    doc = doc . rstrip ( ) + ( ' detailed below:\n----------\n' + f . __doc__ )
vf . __doc__ = doc
return vf


signature:
def apply ( f , obj , * args , ** kwargs ) :
    """Apply a function in parallel to each element of the input"""

implementation: return vectorize ( f ) ( obj , * args , ** kwargs )


signature:
def call_all ( sequence , method_name , * args , ** kwargs ) :
    """Call a method on each element of a sequence , in parallel .
 Returns :
 list of results"""

implementation:
kwargs = kwargs . copy ( )
kwargs [ 'block' ] = False
results = [ ]
for obj in sequence :
    results . append ( methodcall ( obj , method_name , * args , ** kwargs ) )
for i in range ( len ( results ) ) :
    results [ i ] = convert_result ( results [ i ] )
return results


signature:
def register_proxy_type ( cls , real_type , proxy_type ) :
    """Configure engines so that remote methods returning values of type
 ` real _ type ` will instead return by proxy , as type ` proxy _ type `"""

implementation:
if distob . engine is None :
    cls . _initial_proxy_types [ real_type ] = proxy_type
elif isinstance ( distob . engine , ObjectHub ) :
    distob . engine . _runtime_reg_proxy_type ( real_type , proxy_type )
else : # TODO : remove next line after issue # 58 in dill is fixed .
    distob . engine . _singleeng_reg_proxy_type ( real_type , proxy_type )
    pass


signature:
def _fetch ( self ) :
    """forces update of a local cached copy of the real object
 ( regardless of the preference setting self . cache )"""

implementation:
if not self . is_local and not self . _obcache_current : # print ( ' fetching data from % s ' % self . _ ref . id )
    def _remote_fetch ( id ) :
        return distob . engine [ id ]
    self . _obcache = self . _dv . apply_sync ( _remote_fetch , self . _id )
    self . _obcache_current = True
    self . __engine_affinity__ = ( distob . engine . eid , self . __engine_affinity__ [ 1 ] )


signature:
def extract_json ( fileobj , keywords , comment_tags , options ) :
    """Supports : gettext , ngettext . See package README or github ( https : / / github . com / tigrawap / pybabel - json ) for more usage info ."""

implementation:
data = fileobj . read ( )
json_extractor = JsonExtractor ( data )
strings_data = json_extractor . get_lines_data ( )
for item in strings_data :
    messages = [ item [ 'content' ] ]
    if item . get ( 'funcname' ) == 'ngettext' :
        messages . append ( item [ 'alt_content' ] )
    yield item [ 'line_number' ] , item . get ( 'funcname' , 'gettext' ) , tuple ( messages ) , [ ]


signature:
def get_lines_data ( self ) :
    """Returns string : line _ numbers list
 Since all strings are unique it is OK to get line numbers this way .
 Since same string can occur several times inside single . json file the values should be popped ( FIFO ) from the list
 : rtype : list"""

implementation:
encoding = 'utf-8'
for token in tokenize ( self . data . decode ( encoding ) ) :
    if token . type == 'operator' :
        if token . value == '{' :
            self . start_object ( )
        elif token . value == ':' :
            self . with_separator ( token )
        elif token . value == '}' :
            self . end_object ( )
        elif token . value == ',' :
            self . end_pair ( )
    elif token . type == 'string' :
        if self . state == 'key' :
            self . current_key = unquote_string ( token . value )
            if self . current_key == JSON_GETTEXT_KEYWORD :
                self . gettext_mode = True
        # = = value not actually used , but if only key was met ( like in list ) it still will be used . The important part , that key wont be parsed as value , not reversal
        if self . gettext_mode :
            if self . current_key == JSON_GETTEXT_KEY_CONTENT :
                self . token_to_add = token
            elif self . current_key == JSON_GETTEXT_KEY_ALT_CONTENT :
                self . token_params [ 'alt_token' ] = token
            elif self . current_key == JSON_GETTEXT_KEY_FUNCNAME :
                self . token_params [ 'funcname' ] = token . value
        else :
            self . token_to_add = token
return self . results


signature:
def is_git_repo ( path ) :
    '''Returns True if path is a git repository .'''

implementation:
if path . startswith ( 'git@' ) or path . startswith ( 'https://' ) :
    return True
if os . path . exists ( unipath ( path , '.git' ) ) :
    return True
return False


signature:
def is_home_environment ( path ) :
    '''Returns True if path is in CPENV _ HOME'''

implementation:
home = unipath ( os . environ . get ( 'CPENV_HOME' , '~/.cpenv' ) )
path = unipath ( path )
return path . startswith ( home )


signature:
def is_redirecting ( path ) :
    '''Returns True if path contains a . cpenv file'''

implementation:
candidate = unipath ( path , '.cpenv' )
return os . path . exists ( candidate ) and os . path . isfile ( candidate )


signature:
def redirect_to_env_paths ( path ) :
    '''Get environment path from redirect file'''

implementation:
with open ( path , 'r' ) as f :
    redirected = f . read ( )
return shlex . split ( redirected )


signature:
def expandpath ( path ) :
    '''Returns an absolute expanded path'''

implementation: return os . path . abspath ( os . path . expandvars ( os . path . expanduser ( path ) ) )


signature:
def unipath ( * paths ) :
    '''Like os . path . join but also expands and normalizes path parts .'''

implementation: return os . path . normpath ( expandpath ( os . path . join ( * paths ) ) )


signature:
def binpath ( * paths ) :
    '''Like os . path . join but acts relative to this packages bin path .'''

implementation:
package_root = os . path . dirname ( __file__ )
return os . path . normpath ( os . path . join ( package_root , 'bin' , * paths ) )


signature:
def ensure_path_exists ( path , * args ) :
    '''Like os . makedirs but keeps quiet if path already exists'''

implementation:
if os . path . exists ( path ) :
    return
os . makedirs ( path , * args )


signature:
def walk_dn ( start_dir , depth = 10 ) :
    '''Walk down a directory tree . Same as os . walk but allows for a depth limit
 via depth argument'''

implementation:
start_depth = len ( os . path . split ( start_dir ) )
end_depth = start_depth + depth
for root , subdirs , files in os . walk ( start_dir ) :
    yield root , subdirs , files
    if len ( os . path . split ( root ) ) >= end_depth :
        break


signature:
def walk_up ( start_dir , depth = 20 ) :
    '''Walk up a directory tree'''

implementation:
root = start_dir
for i in xrange ( depth ) :
    contents = os . listdir ( root )
    subdirs , files = [ ] , [ ]
    for f in contents :
        if os . path . isdir ( os . path . join ( root , f ) ) :
            subdirs . append ( f )
        else :
            files . append ( f )
    yield root , subdirs , files
    parent = os . path . dirname ( root )
    if parent and not parent == root :
        root = parent
    else :
        break


signature:
def preprocess_dict ( d ) :
    '''Preprocess a dict to be used as environment variables .
 : param d : dict to be processed'''

implementation:
out_env = { }
for k , v in d . items ( ) :
    if not type ( v ) in PREPROCESSORS :
        raise KeyError ( 'Invalid type in dict: {}' . format ( type ( v ) ) )
    out_env [ k ] = PREPROCESSORS [ type ( v ) ] ( v )
return out_env


signature:
def _join_seq ( d , k , v ) :
    '''Add a sequence value to env dict'''

implementation:
if k not in d :
    d [ k ] = list ( v )
elif isinstance ( d [ k ] , list ) :
    for item in v :
        if item not in d [ k ] :
            d [ k ] . insert ( 0 , item )
elif isinstance ( d [ k ] , string_types ) :
    v . append ( d [ k ] )
    d [ k ] = v


signature:
def join_dicts ( * dicts ) :
    '''Join a bunch of dicts'''

implementation:
out_dict = { }
for d in dicts :
    for k , v in d . iteritems ( ) :
        if not type ( v ) in JOINERS :
            raise KeyError ( 'Invalid type in dict: {}' . format ( type ( v ) ) )
        JOINERS [ type ( v ) ] ( out_dict , k , v )
return out_dict


signature:
def env_to_dict ( env , pathsep = os . pathsep ) :
    '''Convert a dict containing environment variables into a standard dict .
 Variables containing multiple values will be split into a list based on
 the argument passed to pathsep .
 : param env : Environment dict like os . environ . data
 : param pathsep : Path separator used to split variables'''

implementation:
out_dict = { }
for k , v in env . iteritems ( ) :
    if pathsep in v :
        out_dict [ k ] = v . split ( pathsep )
    else :
        out_dict [ k ] = v
return out_dict


signature:
def dict_to_env ( d , pathsep = os . pathsep ) :
    '''Convert a python dict to a dict containing valid environment variable
 values .
 : param d : Dict to convert to an env dict
 : param pathsep : Path separator used to join lists ( default os . pathsep )'''

implementation:
out_env = { }
for k , v in d . iteritems ( ) :
    if isinstance ( v , list ) :
        out_env [ k ] = pathsep . join ( v )
    elif isinstance ( v , string_types ) :
        out_env [ k ] = v
    else :
        raise TypeError ( '{} not a valid env var type' . format ( type ( v ) ) )
return out_env


signature:
def expand_envvars ( env ) :
    '''Expand all environment variables in an environment dict
 : param env : Environment dict'''

implementation:
out_env = { }
for k , v in env . iteritems ( ) :
    out_env [ k ] = Template ( v ) . safe_substitute ( env )
# Expand twice to make sure we expand everything we possibly can
for k , v in out_env . items ( ) :
    out_env [ k ] = Template ( v ) . safe_substitute ( out_env )
return out_env


signature:
def get_store_env_tmp ( ) :
    '''Returns an unused random filepath .'''

implementation:
tempdir = tempfile . gettempdir ( )
temp_name = 'envstore{0:0>3d}'
temp_path = unipath ( tempdir , temp_name . format ( random . getrandbits ( 9 ) ) )
if not os . path . exists ( temp_path ) :
    return temp_path
else :
    return get_store_env_tmp ( )


signature:
def store_env ( path = None ) :
    '''Encode current environment as yaml and store in path or a temporary
 file . Return the path to the stored environment .'''

implementation:
path = path or get_store_env_tmp ( )
env_dict = yaml . safe_dump ( os . environ . data , default_flow_style = False )
with open ( path , 'w' ) as f :
    f . write ( env_dict )
return path


signature:
def restore_env ( env_dict ) :
    '''Set environment variables in the current python process from a dict
 containing envvars and values .'''

implementation:
if hasattr ( sys , 'real_prefix' ) :
    sys . prefix = sys . real_prefix
    del ( sys . real_prefix )
replace_osenviron ( expand_envvars ( dict_to_env ( env_dict ) ) )


signature:
def restore_env_from_file ( env_file ) :
    '''Restore the current environment from an environment stored in a yaml
 yaml file .
 : param env _ file : Path to environment yaml file .'''

implementation:
with open ( env_file , 'r' ) as f :
    env_dict = yaml . load ( f . read ( ) )
restore_env ( env_dict )


signature:
def set_env ( * env_dicts ) :
    '''Set environment variables in the current python process from a dict
 containing envvars and values .'''

implementation:
old_env_dict = env_to_dict ( os . environ . data )
new_env_dict = join_dicts ( old_env_dict , * env_dicts )
new_env = dict_to_env ( new_env_dict )
replace_osenviron ( expand_envvars ( new_env ) )


signature:
def set_env_from_file ( env_file ) :
    '''Restore the current environment from an environment stored in a yaml
 yaml file .
 : param env _ file : Path to environment yaml file .'''

implementation:
with open ( env_file , 'r' ) as f :
    env_dict = yaml . load ( f . read ( ) )
if 'environment' in env_dict :
    env_dict = env_dict [ 'environment' ]
set_env ( env_dict )


signature:
def upstream_url ( self , uri ) :
    "Returns the URL to the upstream data source for the given URI based on configuration"

implementation: return self . application . options . upstream + self . request . uri


signature:
def cache_get ( self ) :
    "Returns ( headers , body ) from the cache or raise KeyError"

implementation:
key = self . cache_key ( )
( headers , body , expires_ts ) = self . application . _cache [ key ]
if expires_ts < time . now ( ) : # asset has expired , delete it
    del self . application . _cache [ key ]
    raise KeyError ( key )
return ( headers , body )


signature:
def make_upstream_request ( self ) :
    "Return request object for calling the upstream"

implementation:
url = self . upstream_url ( self . request . uri )
return tornado . httpclient . HTTPRequest ( url , method = self . request . method , headers = self . request . headers , body = self . request . body if self . request . body else None )


signature:
def ttl ( self , response ) :
    """Returns time to live in seconds . 0 means no caching .
 Criteria :
 - response code 200
 - read - only method ( GET , HEAD , OPTIONS )
 Plus http headers :
 - cache - control : option1 , option2 , . . .
 where options are :
 private | public
 no - cache
 no - store
 max - age : seconds
 s - maxage : seconds
 must - revalidate
 proxy - revalidate
 - expires : Thu , 01 Dec 1983 20:00:00 GMT
 - pragma : no - cache ( = cache - control : no - cache )
 See http : / / www . mobify . com / blog / beginners - guide - to - http - cache - headers /
 TODO : tests"""

implementation:
if response . code != 200 :
    return 0
if not self . request . method in [ 'GET' , 'HEAD' , 'OPTIONS' ] :
    return 0
try :
    pragma = self . request . headers [ 'pragma' ]
    if pragma == 'no-cache' :
        return 0
except KeyError :
    pass
try :
    cache_control = self . request . headers [ 'cache-control' ]
    # no caching options
    for option in [ 'private' , 'no-cache' , 'no-store' , 'must-revalidate' , 'proxy-revalidate' ] :
        if cache_control . find ( option ) :
            return 0
    # further parsing to get a ttl
    options = parse_cache_control ( cache_control )
    try :
        return int ( options [ 's-maxage' ] )
    except KeyError :
        pass
    try :
        return int ( options [ 'max-age' ] )
    except KeyError :
        pass
    if 's-maxage' in options :
        max_age = options [ 's-maxage' ]
        if max_age < ttl :
            ttl = max_age
    if 'max-age' in options :
        max_age = options [ 'max-age' ]
        if max_age < ttl :
            ttl = max_age
    return ttl
except KeyError :
    pass
try :
    expires = self . request . headers [ 'expires' ]
    return time . mktime ( time . strptime ( expires , '%a, %d %b %Y %H:%M:%S' ) ) - time . time ( )
except KeyError :
    pass


signature:
def hist2d ( x , y , bins = 10 , labels = None , aspect = "auto" , plot = True , fig = None , ax = None , interpolation = 'none' , cbar = True , ** kwargs ) :
    """Creates a 2 - D histogram of data * x * , * y * with * bins * , * labels * = : code : ` [ title , xlabel , ylabel ] ` , aspect ration * aspect * . Attempts to use axis * ax * first , then the current axis of * fig * , then the last axis , to use an already - created window .
 Plotting ( * plot * ) is on by default , setting false doesn ' t attempt to create a figure .
 * interpolation * sets the interpolation type of : meth : ` matplotlib . axis . imshow ` .
 Returns a handle and extent as : code : ` h , extent `"""

implementation:
h_range = kwargs . pop ( 'range' , None )
h_normed = kwargs . pop ( 'normed' , None )
h_weights = kwargs . pop ( 'weights' , None )
h , xe , ye = _np . histogram2d ( x , y , bins = bins , range = h_range , normed = h_normed , weights = h_weights )
extent = [ xe [ 0 ] , xe [ - 1 ] , ye [ 0 ] , ye [ - 1 ] ]
# fig = plt . figure ( )
if plot :
    if ax is None :
        if fig is None :
            fig = _figure ( 'hist2d' )
        ax = fig . gca ( )
        ax . clear ( )
    img = ax . imshow ( h . transpose ( ) , extent = extent , interpolation = interpolation , aspect = aspect , ** kwargs )
    if cbar :
        _colorbar ( ax = ax , im = img )
    if labels is not None :
        _addlabel ( labels [ 0 ] , labels [ 1 ] , labels [ 2 ] )
    # _ showfig ( fig , aspect )
return h , extent


signature:
def w_p ( self ) :
    """Plasma frequency : math : ` \\ omega _ p ` for given plasma density"""

implementation: return _np . sqrt ( self . n_p * _np . power ( _spc . e , 2 ) / ( _spc . m_e * _spc . epsilon_0 ) )


signature:
def k_ion ( self , E ) :
    """Geometric focusing force due to ion column for given plasma density as a function of * E *"""

implementation: return self . n_p * _np . power ( _spc . e , 2 ) / ( 2 * _sltr . GeV2joule ( E ) * _spc . epsilon_0 )


signature:
def manifest ( ) :
    """Guarantee the existence of a basic MANIFEST . in .
 manifest doc : http : / / docs . python . org / distutils / sourcedist . html # manifest
 ` options . paved . dist . manifest . include ` : set of files ( or globs ) to include with the ` include ` directive .
 ` options . paved . dist . manifest . recursive _ include ` : set of files ( or globs ) to include with the ` recursive - include ` directive .
 ` options . paved . dist . manifest . prune ` : set of files ( or globs ) to exclude with the ` prune ` directive .
 ` options . paved . dist . manifest . include _ sphinx _ docroot ` : True - > sphinx docroot is added as ` graft `
 ` options . paved . dist . manifest . include _ sphinx _ docroot ` : True - > sphinx builddir is added as ` prune `"""

implementation:
prune = options . paved . dist . manifest . prune
graft = set ( )
if options . paved . dist . manifest . include_sphinx_docroot :
    docroot = options . get ( 'docroot' , 'docs' )
    graft . update ( [ docroot ] )
    if options . paved . dist . manifest . exclude_sphinx_builddir :
        builddir = docroot + '/' + options . get ( "builddir" , ".build" )
        prune . update ( [ builddir ] )
with open ( options . paved . cwd / 'MANIFEST.in' , 'w' ) as fo :
    for item in graft :
        fo . write ( 'graft %s\n' % item )
    for item in options . paved . dist . manifest . include :
        fo . write ( 'include %s\n' % item )
    for item in options . paved . dist . manifest . recursive_include :
        fo . write ( 'recursive-include %s\n' % item )
    for item in prune :
        fo . write ( 'prune %s\n' % item )


signature:
def accessor ( parser , token ) :
    """This template tag is used to do complex nested attribute accessing of
 an object . The first parameter is the object being accessed , subsequent
 paramters are one of :
 * a variable in the template context
 * a literal in the template context
 * either of the above surrounded in square brackets
 For each variable or literal parameter given a ` getattr ` is called on the
 object , chaining to the next parameter . For any sqaure bracket enclosed
 items the access is done through a dictionary lookup .
 Example : :
 { % accessor car where ' front _ seat ' [ position ] [ ' fabric ' ] % }
 The above would result in the following chain of commands :
 . . code - block : : python
 ref = getattr ( car , where )
 ref = getattr ( ref , ' front _ seat ' )
 ref = ref [ position ]
 return ref [ ' fabric ' ]
 This tag also supports " as " syntax , putting the results into a template
 variable : :
 { % accessor car ' interior ' as foo % }"""

implementation:
contents = token . split_contents ( )
tag = contents [ 0 ]
if len ( contents ) < 3 :
    raise template . TemplateSyntaxError ( ( '%s requires at least two ' 'arguments: object and one or more getattr parms' ) % tag )
as_var = None
if len ( contents ) >= 4 : # check for " as " syntax
    if contents [ - 2 ] == 'as' :
        as_var = contents [ - 1 ]
        contents = contents [ : - 2 ]
return AccessorNode ( contents [ 1 ] , contents [ 2 : ] , as_var )


signature:
def get_field_value_from_context ( field_name , context_list ) :
    """Helper to get field value from string path .
 String ' < context > ' is used to go up on context stack . It just
 can be used at the beginning of path : < context > . < context > . field _ name _ 1
 On the other hand , ' < root > ' is used to start lookup from first item on context ."""

implementation:
field_path = field_name . split ( '.' )
if field_path [ 0 ] == '<root>' :
    context_index = 0
    field_path . pop ( 0 )
else :
    context_index = - 1
    while field_path [ 0 ] == '<context>' :
        context_index -= 1
        field_path . pop ( 0 )
try :
    field_value = context_list [ context_index ]
    while len ( field_path ) :
        field = field_path . pop ( 0 )
        if isinstance ( field_value , ( list , tuple , ListModel ) ) :
            if field . isdigit ( ) :
                field = int ( field )
            field_value = field_value [ field ]
        elif isinstance ( field_value , dict ) :
            try :
                field_value = field_value [ field ]
            except KeyError :
                if field . isdigit ( ) :
                    field = int ( field )
                    field_value = field_value [ field ]
                else :
                    field_value = None
        else :
            field_value = getattr ( field_value , field )
    return field_value
except ( IndexError , AttributeError , KeyError , TypeError ) :
    return None


signature:
def create_threadpool_executed_func ( original_func ) :
    """Returns a function wrapper that defers function calls execute inside gevent ' s threadpool but keeps any exception
 or backtrace in the caller ' s context .
 : param original _ func : function to wrap
 : returns : wrapper function"""

implementation:
def wrapped_func ( * args , ** kwargs ) :
    try :
        result = original_func ( * args , ** kwargs )
        return True , result
    except :
        return False , sys . exc_info ( )
def new_func ( * args , ** kwargs ) :
    status , result = gevent . get_hub ( ) . threadpool . apply ( wrapped_func , args , kwargs )
    if status :
        return result
    else :
        six . reraise ( * result )
new_func . __name__ = original_func . __name__
new_func . __doc__ = "(gevent-friendly)" + ( " " + original_func . __doc__ if original_func . __doc__ is not None else "" )
return new_func


signature:
def format_pathname ( pathname , max_length ) :
    """Format a pathname
 : param str pathname : Pathname to format
 : param int max _ length : Maximum length of result pathname ( > 3)
 : return : Formatted pathname
 : rtype : str
 : raises ValueError : If * max _ length * is not larger than 3
 This function formats a pathname so it is not longer than * max _ length *
 characters . The resulting pathname is returned . It does so by replacing
 characters at the start of the * pathname * with three dots , if necessary .
 The idea is that the end of the * pathname * is the most important part
 to be able to identify the file ."""

implementation:
if max_length <= 3 :
    raise ValueError ( "max length must be larger than 3" )
if len ( pathname ) > max_length :
    pathname = "...{}" . format ( pathname [ - ( max_length - 3 ) : ] )
return pathname


signature:
def format_time_point ( time_point_string ) :
    """: param str time _ point _ string : String representation of a time point
 to format
 : return : Formatted time point
 : rtype : str
 : raises ValueError : If * time _ point _ string * is not formatted by
 dateutil . parser . parse
 See : py : meth : ` datetime . datetime . isoformat ` function for supported formats ."""

implementation:
time_point = dateutil . parser . parse ( time_point_string )
if not is_aware ( time_point ) :
    time_point = make_aware ( time_point )
time_point = local_time_point ( time_point )
return time_point . strftime ( "%Y-%m-%dT%H:%M:%S" )


signature:
def format_uuid ( uuid , max_length = 10 ) :
    """Format a UUID string
 : param str uuid : UUID to format
 : param int max _ length : Maximum length of result string ( > 3)
 : return : Formatted UUID
 : rtype : str
 : raises ValueError : If * max _ length * is not larger than 3
 This function formats a UUID so it is not longer than * max _ length *
 characters . The resulting string is returned . It does so by replacing
 characters at the end of the * uuid * with three dots , if necessary .
 The idea is that the start of the * uuid * is the most important part
 to be able to identify the related entity .
 The default * max _ length * is 10 , which will result in a string
 containing the first 7 characters of the * uuid * passed in . Most of
 the time , such a string is still unique within a collection of UUIDs ."""

implementation:
if max_length <= 3 :
    raise ValueError ( "max length must be larger than 3" )
if len ( uuid ) > max_length :
    uuid = "{}..." . format ( uuid [ 0 : max_length - 3 ] )
return uuid


signature:
def chisquare ( observe , expect , error , ddof , verbose = True ) :
    """Finds the reduced chi square difference of * observe * and * expect * with a given * error * and * ddof * degrees of freedom .
 * verbose * flag determines if the reduced chi square is printed to the terminal ."""

implementation:
chisq = 0
error = error . flatten ( )
observe = observe . flatten ( )
expect = expect . flatten ( )
for i , el in enumerate ( observe ) :
    chisq = chisq + _np . power ( ( el - expect [ i ] ) / error [ i ] , 2 )
red_chisq = chisq / ( len ( observe ) - ddof )
if verbose : # print ' Chi - Squared is { } . ' . format ( chisq )
    print ( 'Reduced Chi-Squared is {}.' . format ( red_chisq ) )
return red_chisq


signature:
def frexp10 ( x ) :
    """Finds the mantissa and exponent of a number : math : ` x ` such that : math : ` x = m 10 ^ e ` .
 Parameters
 x : float
 Number : math : ` x ` such that : math : ` x = m 10 ^ e ` .
 Returns
 mantissa : float
 Number : math : ` m ` such that : math : ` x = m 10 ^ e ` .
 exponent : float
 Number : math : ` e ` such that : math : ` x = m 10 ^ e ` ."""

implementation:
expon = _np . int ( _np . floor ( _np . log10 ( _np . abs ( x ) ) ) )
mant = x / _np . power ( 10 , expon )
return ( mant , expon )


signature:
def get_upcoming_events_count ( days = 14 , featured = False ) :
    """Returns count of upcoming events for a given number of days , either featured or all
 Usage :
 { % get _ upcoming _ events _ count DAYS as events _ count % }
 with days being the number of days you want , or 5 by default"""

implementation:
from happenings . models import Event
start_period = today - datetime . timedelta ( days = 2 )
end_period = today + datetime . timedelta ( days = days )
if featured :
    return Event . objects . filter ( featured = True , start_date__gte = start_period , start_date__lte = end_period ) . count ( )
return Event . objects . filter ( start_date__gte = start_period , start_date__lte = end_period ) . count ( )


signature:
def get_upcoming_events ( num , days , featured = False ) :
    """Get upcoming events .
 Allows slicing to a given number ,
 picking the number of days to hold them after they ' ve started
 and whether they should be featured or not .
 Usage :
 { % get _ upcoming _ events 5 14 featured as events % }
 Would return no more than 5 Featured events ,
 holding them for 14 days past their start date ."""

implementation:
from happenings . models import Event
start_date = today - datetime . timedelta ( days = days )
events = Event . objects . filter ( start_date__gt = start_date ) . order_by ( 'start_date' )
if featured :
    events = events . filter ( featured = True )
events = events [ : num ]
return events


signature:
def get_events_by_date_range ( days_out , days_hold , max_num = 5 , featured = False ) :
    """Get upcoming events for a given number of days ( days out )
 Allows specifying number of days to hold events after they ' ve started
 The max number to show ( defaults to 5)
 and whether they should be featured or not .
 Usage :
 { % get _ events _ by _ date _ range 14 3 3 ' featured ' as events % }
 Would return no more than 3 featured events ,
 that fall within the next 14 days or have ended within the past 3."""

implementation:
from happenings . models import Event
range_start = today - datetime . timedelta ( days = days_hold )
range_end = today + datetime . timedelta ( days = days_out )
events = Event . objects . filter ( start_date__gte = range_start , start_date__lte = range_end ) . order_by ( 'start_date' )
if featured :
    events = events . filter ( featured = True )
events = events [ : max_num ]
return events


signature:
def paginate_update ( update ) :
    """attempts to get next and previous on updates"""

implementation:
from happenings . models import Update
time = update . pub_time
event = update . event
try :
    next = Update . objects . filter ( event = event , pub_time__gt = time ) . order_by ( 'pub_time' ) . only ( 'title' ) [ 0 ]
except :
    next = None
try :
    previous = Update . objects . filter ( event = event , pub_time__lt = time ) . order_by ( '-pub_time' ) . only ( 'title' ) [ 0 ]
except :
    previous = None
return { 'next' : next , 'previous' : previous , 'event' : event }


signature:
def notify_client ( notifier_uri , client_id , status_code , message = None ) :
    """Notify the client of the result of handling a request
 The payload contains two elements :
 - client _ id
 - result
 The * client _ id * is the id of the client to notify . It is assumed
 that the notifier service is able to identify the client by this id
 and that it can pass the * result * to it .
 The * result * always contains a * status _ code * element . In case the
 message passed in is not None , it will also contain a * message *
 element .
 In case the notifier service does not exist or returns an error ,
 an error message will be logged to * stderr * ."""

implementation:
payload = { "client_id" : client_id , "result" : { "response" : { "status_code" : status_code } } }
if message is not None :
    payload [ "result" ] [ "response" ] [ "message" ] = message
response = requests . post ( notifier_uri , json = payload )
if response . status_code != 201 :
    sys . stderr . write ( "failed to notify client: {}\n" . format ( payload ) )
    sys . stderr . flush ( )


signature:
def consume_message ( method ) :
    """Decorator for methods handling requests from RabbitMQ
 The goal of this decorator is to perform the tasks common to all
 methods handling requests :
 - Log the raw message to * stdout *
 - Decode the message into a Python dictionary
 - Log errors to * stderr *
 - Signal the broker that we ' re done handling the request
 The method passed in will be called with the message body as a
 dictionary . It is assumed here that the message body is a JSON string
 encoded in UTF8."""

implementation:
def wrapper ( self , channel , method_frame , header_frame , body ) : # Log the message
    sys . stdout . write ( "received message: {}\n" . format ( body ) )
    sys . stdout . flush ( )
    try : # Grab the data and call the method
        body = body . decode ( "utf-8" )
        data = json . loads ( body )
        method ( self , data )
    except Exception as exception : # Log the error message
        sys . stderr . write ( "{}\n" . format ( traceback . format_exc ( ) ) )
        sys . stderr . flush ( )
    # Signal the broker we are done
    channel . basic_ack ( delivery_tag = method_frame . delivery_tag )
return wrapper


signature:
def consume_message_with_notify ( notifier_uri_getter ) :
    """Decorator for methods handling requests from RabbitMQ
 This decorator builds on the : py : func : ` consume _ message ` decorator . It extents
 it by logic for notifying a client of the result of handling the
 request .
 The * notifier _ uri _ getter * argument must be a callable which accepts
 * self * and returns the uri of the notifier service ."""

implementation:
def consume_message_with_notify_decorator ( method ) :
    @ consume_message
    def wrapper ( self , data ) :
        notifier_uri = notifier_uri_getter ( self )
        client_id = data [ "client_id" ]
        # Forward the call to the method and notify the client of the
        # result
        try :
            method ( self , data )
            notify_client ( notifier_uri , client_id , 200 )
        except Exception as exception :
            notify_client ( notifier_uri , client_id , 400 , str ( exception ) )
            raise
    return wrapper
return consume_message_with_notify_decorator


signature:
def get ( self , key ) :
    """> > > c = LRUCache ( )
 > > > c . get ( ' toto ' )
 Traceback ( most recent call last ) :
 KeyError : ' toto '
 > > > c . stats ( ) [ ' misses ' ]
 > > > c . put ( ' toto ' , ' tata ' )
 > > > c . get ( ' toto ' )
 ' tata '
 > > > c . stats ( ) [ ' hits ' ]"""

implementation:
try :
    value = self . _cache [ key ]
    self . _order . push ( key )
    self . _hits += 1
    return value
except KeyError , e :
    self . _misses += 1
    raise


implementation:
self . _cache [ key ] = value
self . _order . push ( key )
self . _size += 1


signature:
def delete ( self , key ) :
    """> > > c = LRUCache ( )
 > > > c . put ( 1 , ' one ' )
 > > > c . get ( 1)
 ' one '
 > > > c . delete ( 1)
 > > > c . get ( 1)
 Traceback ( most recent call last ) :
 KeyError : 1
 > > > c . delete ( 1)
 Traceback ( most recent call last ) :
 KeyError : 1"""

implementation:
del self . _cache [ key ]
self . _order . delete ( key )
self . _size -= 1


signature:
def put ( self , key , value ) :
    """> > > c = MemSizeLRUCache ( maxmem = 24*4)
 > > > c . put ( 1 , 1)
 > > > c . mem ( ) # 24 - bytes per integer
 24
 > > > c . put ( 2 , 2)
 > > > c . put ( 3 , 3)
 > > > c . put ( 4 , 4)
 > > > c . get ( 1)
 > > > c . mem ( )
 96
 > > > c . size ( )
 > > > c . put ( 5 , 5)
 > > > c . size ( )
 > > > c . get ( 2)
 Traceback ( most recent call last ) :
 KeyError : 2"""

implementation:
mem = sys . getsizeof ( value )
if self . _mem + mem > self . _maxmem :
    self . delete ( self . last ( ) )
LRUCache . put ( self , key , ( value , mem ) )
self . _mem += mem


signature:
def delete ( self , key ) :
    """> > > c = MemSizeLRUCache ( )
 > > > c . put ( 1 , 1)
 > > > c . mem ( )
 24
 > > > c . delete ( 1)
 > > > c . mem ( )"""

implementation:
( _value , mem ) = LRUCache . get ( self , key )
self . _mem -= mem
LRUCache . delete ( self , key )


signature:
def put ( self , key , value ) :
    """> > > c = FixedSizeLRUCache ( maxsize = 5)
 > > > c . put ( 1 , ' one ' )
 > > > c . get ( 1)
 ' one '
 > > > c . size ( )
 > > > c . put ( 2 , ' two ' )
 > > > c . put ( 3 , ' three ' )
 > > > c . put ( 4 , ' four ' )
 > > > c . put ( 5 , ' five ' )
 > > > c . get ( 5)
 ' five '
 > > > c . size ( )
 > > > c . put ( 6 , ' six ' )
 > > > c . size ( )
 > > > c . get ( 1)
 Traceback ( most recent call last ) :
 KeyError : 1
 > > > c . get ( 2)
 ' two '
 > > > c . put ( 7 , ' seven ' )
 > > > c . get ( 2)
 ' two '
 > > > c . get ( 3)
 Traceback ( most recent call last ) :
 KeyError : 3"""

implementation:
# check if we ' re maxed out first
if self . size ( ) == self . _maxsize : # need to kick something out . . .
    self . delete ( self . last ( ) )
LRUCache . put ( self , key , value )


signature:
def setting ( self , name_hyphen ) :
    """Retrieves the setting value whose name is indicated by name _ hyphen .
 Values starting with $ are assumed to reference environment variables ,
 and the value stored in environment variables is retrieved . It ' s an
 error if thes corresponding environment variable it not set ."""

implementation:
if name_hyphen in self . _instance_settings :
    value = self . _instance_settings [ name_hyphen ] [ 1 ]
else :
    msg = "No setting named '%s'" % name_hyphen
    raise UserFeedback ( msg )
if hasattr ( value , 'startswith' ) and value . startswith ( "$" ) :
    env_var = value . lstrip ( "$" )
    if env_var in os . environ :
        return os . getenv ( env_var )
    else :
        msg = "'%s' is not defined in your environment" % env_var
        raise UserFeedback ( msg )
elif hasattr ( value , 'startswith' ) and value . startswith ( "\$" ) :
    return value . replace ( "\$" , "$" )
else :
    return value


signature:
def setting_values ( self , skip = None ) :
    """Returns dict of all setting values ( removes the helpstrings ) ."""

implementation:
if not skip :
    skip = [ ]
return dict ( ( k , v [ 1 ] ) for k , v in six . iteritems ( self . _instance_settings ) if not k in skip )


signature:
def _update_settings ( self , new_settings , enforce_helpstring = True ) :
    """This method does the work of updating settings . Can be passed with
 enforce _ helpstring = False which you may want if allowing end users to
 add arbitrary metadata via the settings system .
 Preferable to use update _ settings ( without leading _ ) in code to do the
 right thing and always have docstrings ."""

implementation:
for raw_setting_name , value in six . iteritems ( new_settings ) :
    setting_name = raw_setting_name . replace ( "_" , "-" )
    setting_already_exists = setting_name in self . _instance_settings
    value_is_list_len_2 = isinstance ( value , list ) and len ( value ) == 2
    treat_as_tuple = not setting_already_exists and value_is_list_len_2
    if isinstance ( value , tuple ) or treat_as_tuple :
        self . _instance_settings [ setting_name ] = value
    else :
        if setting_name not in self . _instance_settings :
            if enforce_helpstring :
                msg = "You must specify param '%s' as a tuple of (helpstring, value)"
                raise InternalCashewException ( msg % setting_name )
            else : # Create entry with blank helpstring .
                self . _instance_settings [ setting_name ] = ( '' , value , )
        else : # Save inherited helpstring , replace default value .
            orig = self . _instance_settings [ setting_name ]
            self . _instance_settings [ setting_name ] = ( orig [ 0 ] , value , )


signature:
def settings_and_attributes ( self ) :
    """Return a combined dictionary of setting values and attribute values ."""

implementation:
attrs = self . setting_values ( )
attrs . update ( self . __dict__ )
skip = [ "_instance_settings" , "aliases" ]
for a in skip :
    del attrs [ a ]
return attrs


signature:
def get_reference_to_class ( cls , class_or_class_name ) :
    """Detect if we get a class or a name , convert a name to a class ."""

implementation:
if isinstance ( class_or_class_name , type ) :
    return class_or_class_name
elif isinstance ( class_or_class_name , string_types ) :
    if ":" in class_or_class_name :
        mod_name , class_name = class_or_class_name . split ( ":" )
        if not mod_name in sys . modules :
            __import__ ( mod_name )
        mod = sys . modules [ mod_name ]
        return mod . __dict__ [ class_name ]
    else :
        return cls . load_class_from_locals ( class_or_class_name )
else :
    msg = "Unexpected Type '%s'" % type ( class_or_class_name )
    raise InternalCashewException ( msg )


signature:
def check_docstring ( cls ) :
    """Asserts that the class has a docstring , returning it if successful ."""

implementation:
docstring = inspect . getdoc ( cls )
if not docstring :
    breadcrumbs = " -> " . join ( t . __name__ for t in inspect . getmro ( cls ) [ : - 1 ] [ : : - 1 ] )
    msg = "docstring required for plugin '%s' (%s, defined in %s)"
    args = ( cls . __name__ , breadcrumbs , cls . __module__ )
    raise InternalCashewException ( msg % args )
max_line_length = cls . _class_settings . get ( 'max-docstring-length' )
if max_line_length :
    for i , line in enumerate ( docstring . splitlines ( ) ) :
        if len ( line ) > max_line_length :
            msg = "docstring line %s of %s is %s chars too long"
            args = ( i , cls . __name__ , len ( line ) - max_line_length )
            raise Exception ( msg % args )
return docstring


signature:
def resourcePath ( self , relative_path ) :
    """Get absolute path to resource , works for dev and for PyInstaller"""

implementation:
from os import path
import sys
try : # PyInstaller creates a temp folder and stores path in _ MEIPASS
    base_path = sys . _MEIPASS
except Exception :
    base_path = path . dirname ( path . abspath ( __file__ ) )
return path . join ( base_path , relative_path )


signature:
def addLogbook ( self , physDef = "LCLS" , mccDef = "MCC" , initialInstance = False ) :
    '''Add new block of logbook selection windows . Only 5 allowed .'''

implementation:
if self . logMenuCount < 5 :
    self . logMenus . append ( LogSelectMenu ( self . logui . multiLogLayout , initialInstance ) )
    self . logMenus [ - 1 ] . addLogbooks ( self . logTypeList [ 1 ] , self . physics_programs , physDef )
    self . logMenus [ - 1 ] . addLogbooks ( self . logTypeList [ 0 ] , self . mcc_programs , mccDef )
    self . logMenus [ - 1 ] . show ( )
    self . logMenuCount += 1
    if initialInstance : # Initial logbook menu can add additional menus , all others can only remove themselves .
        QObject . connect ( self . logMenus [ - 1 ] . logButton , SIGNAL ( "clicked()" ) , self . addLogbook )
    else :
        from functools import partial
        QObject . connect ( self . logMenus [ - 1 ] . logButton , SIGNAL ( "clicked()" ) , partial ( self . removeLogbook , self . logMenus [ - 1 ] ) )


signature:
def removeLogbook ( self , menu = None ) :
    '''Remove logbook menu set .'''

implementation:
if self . logMenuCount > 1 and menu is not None :
    menu . removeMenu ( )
    self . logMenus . remove ( menu )
    self . logMenuCount -= 1


signature:
def selectedLogs ( self ) :
    '''Return selected log books by type .'''

implementation:
mcclogs = [ ]
physlogs = [ ]
for i in range ( len ( self . logMenus ) ) :
    logType = self . logMenus [ i ] . selectedType ( )
    log = self . logMenus [ i ] . selectedProgram ( )
    if logType == "MCC" :
        if log not in mcclogs :
            mcclogs . append ( log )
    elif logType == "Physics" :
        if log not in physlogs :
            physlogs . append ( log )
return mcclogs , physlogs


signature:
def acceptedUser ( self , logType ) :
    '''Verify enetered user name is on accepted MCC logbook list .'''

implementation:
from urllib2 import urlopen , URLError , HTTPError
import json
isApproved = False
userName = str ( self . logui . userName . text ( ) )
if userName == "" :
    return False
# Must have a user name to submit entry
if logType == "MCC" :
    networkFault = False
    data = [ ]
    log_url = "https://mccelog.slac.stanford.edu/elog/dev/mgibbs/dev_json_user_list.php/?username=" + userName
    try :
        data = urlopen ( log_url , None , 5 ) . read ( )
        data = json . loads ( data )
    except URLError as error :
        print ( "URLError: " + str ( error . reason ) )
        networkFault = True
    except HTTPError as error :
        print ( "HTTPError: " + str ( error . reason ) )
        networkFault = True
    # If network fails , ask user to verify
    if networkFault :
        msgBox = QMessageBox ( )
        msgBox . setText ( "Cannot connect to MCC Log Server!" )
        msgBox . setInformativeText ( "Use entered User name anyway?" )
        msgBox . setStandardButtons ( QMessageBox . Ok | QMessageBox . Cancel )
        msgBox . setDefaultButton ( QMessageBox . Ok )
        if msgBox . exec_ ( ) == QMessageBox . Ok :
            isApproved = True
    if data != [ ] and ( data is not None ) :
        isApproved = True
else :
    isApproved = True
return isApproved


signature:
def xmlSetup ( self , logType , logList ) :
    """Create xml file with fields from logbook form ."""

implementation:
from xml . etree . ElementTree import Element , SubElement , ElementTree
from datetime import datetime
curr_time = datetime . now ( )
if logType == "MCC" : # Set up xml tags
    log_entry = Element ( 'log_entry' )
    title = SubElement ( log_entry , 'title' )
    program = SubElement ( log_entry , 'program' )
    timestamp = SubElement ( log_entry , 'timestamp' )
    priority = SubElement ( log_entry , 'priority' )
    os_user = SubElement ( log_entry , 'os_user' )
    hostname = SubElement ( log_entry , 'hostname' )
    text = SubElement ( log_entry , 'text' )
    log_user = SubElement ( log_entry , 'log_user' )
    # Check for multiple logbooks and parse into seperate tags
    logbook = [ ]
    for i in range ( len ( logList ) ) :
        logbook . append ( SubElement ( log_entry , 'logbook' ) )
        logbook [ i ] . text = logList [ i ] . lower ( )
    # Take care of dummy , unchanging tags first
    log_entry . attrib [ 'type' ] = "LOGENTRY"
    program . text = "152"
    priority . text = "NORMAL"
    os_user . text = "nobody"
    hostname . text = "mccelog"
    text . attrib [ 'type' ] = "text/plain"
    # Handle attachment if image exists
    if not self . imagePixmap . isNull ( ) :
        attachment = SubElement ( log_entry , 'attachment' )
        attachment . attrib [ 'name' ] = "Figure 1"
        attachment . attrib [ 'type' ] = "image/" + self . imageType
        attachment . text = curr_time . strftime ( "%Y%m%d_%H%M%S_" ) + str ( curr_time . microsecond ) + "." + self . imageType
    # Set timestamp format
    timestamp . text = curr_time . strftime ( "%Y/%m/%d %H:%M:%S" )
    fileName = "/tmp/" + curr_time . strftime ( "%Y%m%d_%H%M%S_" ) + str ( curr_time . microsecond ) + ".xml"
else : # If using Physics logbook
    timeString = curr_time . strftime ( "%Y-%m-%dT%H:%M:%S" )
    # Set up xml tags
    log_entry = Element ( None )
    severity = SubElement ( log_entry , 'severity' )
    location = SubElement ( log_entry , 'location' )
    keywords = SubElement ( log_entry , 'keywords' )
    time = SubElement ( log_entry , 'time' )
    isodate = SubElement ( log_entry , 'isodate' )
    log_user = SubElement ( log_entry , 'author' )
    category = SubElement ( log_entry , 'category' )
    title = SubElement ( log_entry , 'title' )
    metainfo = SubElement ( log_entry , 'metainfo' )
    # Handle attachment if image exists
    if not self . imagePixmap . isNull ( ) :
        imageFile = SubElement ( log_entry , 'link' )
        imageFile . text = timeString + "-00." + self . imageType
        thumbnail = SubElement ( log_entry , 'file' )
        thumbnail . text = timeString + "-00.png"
    text = SubElement ( log_entry , 'text' )
    # Logbook expects Text tag to come last ( for some strange reason )
    # Take care of dummy , unchanging tags first
    log_entry . attrib [ 'type' ] = "LOGENTRY"
    category . text = "USERLOG"
    location . text = "not set"
    severity . text = "NONE"
    keywords . text = "none"
    time . text = curr_time . strftime ( "%H:%M:%S" )
    isodate . text = curr_time . strftime ( "%Y-%m-%d" )
    metainfo . text = timeString + "-00.xml"
    fileName = "/tmp/" + metainfo . text
# Fill in user inputs
log_user . text = str ( self . logui . userName . text ( ) )
title . text = str ( self . logui . titleEntry . text ( ) )
if title . text == "" :
    QMessageBox ( ) . warning ( self , "No Title entered" , "Please enter a title for the entry..." )
    return None
text . text = str ( self . logui . textEntry . toPlainText ( ) )
# If text field is truly empty , ElementTree leaves off tag entirely which causes logbook parser to fail
if text . text == "" :
    text . text = " "
# Create xml file
xmlFile = open ( fileName , "w" )
if logType == "MCC" :
    ElementTree ( log_entry ) . write ( xmlFile )
else :
    xmlString = self . prettify ( log_entry )
    xmlFile . write ( xmlString )
xmlFile . write ( "\n" )
# Close with newline so cron job parses correctly
xmlFile . close ( )
return fileName . rstrip ( ".xml" )


signature:
def prettify ( self , elem ) :
    """Parse xml elements for pretty printing"""

implementation:
from xml . etree import ElementTree
from re import sub
rawString = ElementTree . tostring ( elem , 'utf-8' )
parsedString = sub ( r'(?=<[^/].*>)' , '\n' , rawString )
# Adds newline after each closing tag
return parsedString [ 1 : ]


signature:
def prepareImages ( self , fileName , logType ) :
    """Convert supplied QPixmap object to image file ."""

implementation:
import subprocess
if self . imageType == "png" :
    self . imagePixmap . save ( fileName + ".png" , "PNG" , - 1 )
    if logType == "Physics" :
        makePostScript = "convert " + fileName + ".png " + fileName + ".ps"
        process = subprocess . Popen ( makePostScript , shell = True )
        process . wait ( )
        thumbnailPixmap = self . imagePixmap . scaled ( 500 , 450 , Qt . KeepAspectRatio )
        thumbnailPixmap . save ( fileName + ".png" , "PNG" , - 1 )
else :
    renameImage = "cp " + self . image + " " + fileName + ".gif"
    process = subprocess . Popen ( renameImage , shell = True )
    process . wait ( )
    if logType == "Physics" :
        thumbnailPixmap = self . imagePixmap . scaled ( 500 , 450 , Qt . KeepAspectRatio )
        thumbnailPixmap . save ( fileName + ".png" , "PNG" , - 1 )


signature:
def submitEntry ( self ) :
    """Process user inputs and subit logbook entry when user clicks Submit button"""

implementation:
# logType = self . logui . logType . currentText ( )
mcclogs , physlogs = self . selectedLogs ( )
success = True
if mcclogs != [ ] :
    if not self . acceptedUser ( "MCC" ) :
        QMessageBox ( ) . warning ( self , "Invalid User" , "Please enter a valid user name!" )
        return
    fileName = self . xmlSetup ( "MCC" , mcclogs )
    if fileName is None :
        return
    if not self . imagePixmap . isNull ( ) :
        self . prepareImages ( fileName , "MCC" )
    success = self . sendToLogbook ( fileName , "MCC" )
if physlogs != [ ] :
    for i in range ( len ( physlogs ) ) :
        fileName = self . xmlSetup ( "Physics" , physlogs [ i ] )
        if fileName is None :
            return
        if not self . imagePixmap . isNull ( ) :
            self . prepareImages ( fileName , "Physics" )
        success_phys = self . sendToLogbook ( fileName , "Physics" , physlogs [ i ] )
        success = success and success_phys
self . done ( success )


signature:
def sendToLogbook ( self , fileName , logType , location = None ) :
    '''Process log information and push to selected logbooks .'''

implementation:
import subprocess
success = True
if logType == "MCC" :
    fileString = ""
    if not self . imagePixmap . isNull ( ) :
        fileString = fileName + "." + self . imageType
    logcmd = "xml2elog " + fileName + ".xml " + fileString
    process = subprocess . Popen ( logcmd , shell = True )
    process . wait ( )
    if process . returncode != 0 :
        success = False
else :
    from shutil import copy
    path = "/u1/" + location . lower ( ) + "/physics/logbook/data/"
    # Prod path
    # path = " / home / softegr / alverson / log _ test / " # Dev path
    try :
        if not self . imagePixmap . isNull ( ) :
            copy ( fileName + ".png" , path )
            if self . imageType == "png" :
                copy ( fileName + ".ps" , path )
            else :
                copy ( fileName + "." + self . imageType , path )
        # Copy . xml file last to ensure images will be picked up by cron job
        # print ( " Copying file " + fileName + " to path " + path )
        copy ( fileName + ".xml" , path )
    except IOError as error :
        print ( error )
        success = False
return success


signature:
def clearForm ( self ) :
    """Clear all form fields ( except author ) ."""

implementation:
self . logui . titleEntry . clear ( )
self . logui . textEntry . clear ( )
# Remove all log selection menus except the first
while self . logMenuCount > 1 :
    self . removeLogbook ( self . logMenus [ - 1 ] )


signature:
def setupUI ( self ) :
    '''Create graphical objects for menus .'''

implementation:
labelSizePolicy = QSizePolicy ( QSizePolicy . Fixed , QSizePolicy . Fixed )
labelSizePolicy . setHorizontalStretch ( 0 )
labelSizePolicy . setVerticalStretch ( 0 )
menuSizePolicy = QSizePolicy ( QSizePolicy . Expanding , QSizePolicy . Fixed )
menuSizePolicy . setHorizontalStretch ( 0 )
menuSizePolicy . setVerticalStretch ( 0 )
logTypeLayout = QHBoxLayout ( )
logTypeLayout . setSpacing ( 0 )
typeLabel = QLabel ( "Log Type:" )
typeLabel . setMinimumSize ( QSize ( 65 , 0 ) )
typeLabel . setMaximumSize ( QSize ( 65 , 16777215 ) )
typeLabel . setSizePolicy ( labelSizePolicy )
logTypeLayout . addWidget ( typeLabel )
self . logType = QComboBox ( self )
self . logType . setMinimumSize ( QSize ( 100 , 0 ) )
self . logType . setMaximumSize ( QSize ( 150 , 16777215 ) )
menuSizePolicy . setHeightForWidth ( self . logType . sizePolicy ( ) . hasHeightForWidth ( ) )
self . logType . setSizePolicy ( menuSizePolicy )
logTypeLayout . addWidget ( self . logType )
logTypeLayout . setStretch ( 1 , 6 )
programLayout = QHBoxLayout ( )
programLayout . setSpacing ( 0 )
programLabel = QLabel ( "Program:" )
programLabel . setMinimumSize ( QSize ( 60 , 0 ) )
programLabel . setMaximumSize ( QSize ( 60 , 16777215 ) )
programLabel . setSizePolicy ( labelSizePolicy )
programLayout . addWidget ( programLabel )
self . programName = QComboBox ( self )
self . programName . setMinimumSize ( QSize ( 100 , 0 ) )
self . programName . setMaximumSize ( QSize ( 150 , 16777215 ) )
menuSizePolicy . setHeightForWidth ( self . programName . sizePolicy ( ) . hasHeightForWidth ( ) )
self . programName . setSizePolicy ( menuSizePolicy )
programLayout . addWidget ( self . programName )
programLayout . setStretch ( 1 , 6 )
# Initial instance allows adding additional menus , all following menus can only remove themselves .
if self . initialInstance :
    self . logButton = QPushButton ( "+" , self )
    self . logButton . setToolTip ( "Add logbook" )
else :
    self . logButton = QPushButton ( "-" )
    self . logButton . setToolTip ( "Remove logbook" )
self . logButton . setMinimumSize ( QSize ( 16 , 16 ) )
# 24x24
self . logButton . setMaximumSize ( QSize ( 16 , 16 ) )
# 24x24
self . logButton . setObjectName ( "roundButton" )
# self . logButton . setAutoFillBackground ( True )
# region = QRegion ( QRect ( self . logButton . x ( ) + 15 , self . logButton . y ( ) + 14 , 20 , 20 ) , QRegion . Ellipse )
# self . logButton . setMask ( region )
self . logButton . setStyleSheet ( "QPushButton {border-radius: 8px;}" )
self . _logSelectLayout = QHBoxLayout ( )
self . _logSelectLayout . setSpacing ( 6 )
self . _logSelectLayout . addLayout ( logTypeLayout )
self . _logSelectLayout . addLayout ( programLayout )
self . _logSelectLayout . addWidget ( self . logButton )
self . _logSelectLayout . setStretch ( 0 , 6 )
self . _logSelectLayout . setStretch ( 1 , 6 )


signature:
def show ( self ) :
    '''Display menus and connect even signals .'''

implementation:
self . parent . addLayout ( self . _logSelectLayout )
self . menuCount += 1
self . _connectSlots ( )


signature:
def addLogbooks ( self , type = None , logs = [ ] , default = "" ) :
    '''Add or change list of logbooks .'''

implementation:
if type is not None and len ( logs ) != 0 :
    if type in self . logList :
        for logbook in logs :
            if logbook not in self . logList . get ( type ) [ 0 ] : # print ( " Adding log " + " to " + type + " log type . " )
                self . logList . get ( type ) [ 0 ] . append ( logbook )
    else : # print ( " Adding log type : " + type )
        self . logList [ type ] = [ ]
        self . logList [ type ] . append ( logs )
    # If default given , auto - select upon menu creation
    if len ( self . logList [ type ] ) > 1 and default != "" :
        self . logList . get ( type ) [ 1 ] == default
    else :
        self . logList . get ( type ) . append ( default )
    self . logType . clear ( )
    self . logType . addItems ( list ( self . logList . keys ( ) ) )
    self . changeLogType ( )


signature:
def removeLogbooks ( self , type = None , logs = [ ] ) :
    '''Remove unwanted logbooks from list .'''

implementation:
if type is not None and type in self . logList :
    if len ( logs ) == 0 or logs == "All" :
        del self . logList [ type ]
    else :
        for logbook in logs :
            if logbook in self . logList [ type ] :
                self . logList [ type ] . remove ( logbook )
    self . changeLogType ( )


signature:
def changeLogType ( self ) :
    '''Populate log program list to correspond with log type selection .'''

implementation:
logType = self . selectedType ( )
programs = self . logList . get ( logType ) [ 0 ]
default = self . logList . get ( logType ) [ 1 ]
if logType in self . logList :
    self . programName . clear ( )
    self . programName . addItems ( programs )
    self . programName . setCurrentIndex ( programs . index ( default ) )


signature:
def addMenu ( self ) :
    '''Add menus to parent gui .'''

implementation:
self . parent . multiLogLayout . addLayout ( self . logSelectLayout )
self . getPrograms ( logType , programName )


signature:
def addlabel ( ax = None , toplabel = None , xlabel = None , ylabel = None , zlabel = None , clabel = None , cb = None , windowlabel = None , fig = None , axes = None ) :
    """Adds labels to a plot ."""

implementation:
if ( axes is None ) and ( ax is not None ) :
    axes = ax
if ( windowlabel is not None ) and ( fig is not None ) :
    fig . canvas . set_window_title ( windowlabel )
if fig is None :
    fig = _plt . gcf ( )
if fig is not None and axes is None :
    axes = fig . get_axes ( )
    if axes == [ ] :
        logger . error ( 'No axes found!' )
if axes is not None :
    if toplabel is not None :
        axes . set_title ( toplabel )
    if xlabel is not None :
        axes . set_xlabel ( xlabel )
    if ylabel is not None :
        axes . set_ylabel ( ylabel )
    if zlabel is not None :
        axes . set_zlabel ( zlabel )
if ( clabel is not None ) or ( cb is not None ) :
    if ( clabel is not None ) and ( cb is not None ) :
        cb . set_label ( clabel )
    else :
        if clabel is None :
            logger . error ( 'Missing colorbar label' )
        else :
            logger . error ( 'Missing colorbar instance' )


signature:
def linkcode_resolve ( domain , info ) :
    """Determine the URL corresponding to Python object"""

implementation:
if domain != 'py' :
    return None
modname = info [ 'module' ]
fullname = info [ 'fullname' ]
submod = sys . modules . get ( modname )
if submod is None :
    return None
obj = submod
for part in fullname . split ( '.' ) :
    try :
        obj = getattr ( obj , part )
    except :
        return None
try :
    fn = inspect . getsourcefile ( obj )
except :
    fn = None
if not fn :
    return None
try :
    source , lineno = inspect . getsourcelines ( obj )
except :
    lineno = None
if lineno :
    linespec = "#L%d-L%d" % ( lineno , lineno + len ( source ) - 1 )
else :
    linespec = ""
fn = relpath ( fn , start = dirname ( scisalt . __file__ ) )
if 'dev' in scisalt . __version__ :
    return "http://github.com/joelfrederico/SciSalt/blob/master/scisalt/%s%s" % ( fn , linespec )
else :
    return "http://github.com/joelfrederico/SciSalt/blob/v%s/scisalt/%s%s" % ( scisalt . __version__ , fn , linespec )


signature:
def call_manage ( cmd , capture = False , ignore_error = False ) :
    """Utility function to run commands against Django ' s ` django - admin . py ` / ` manage . py ` .
 ` options . paved . django . project ` : the path to the django project
 files ( where ` settings . py ` typically resides ) .
 Will fall back to a DJANGO _ SETTINGS _ MODULE environment variable .
 ` options . paved . django . manage _ py ` : the path where the django
 project ' s ` manage . py ` resides ."""

implementation:
settings = ( options . paved . django . settings or os . environ . get ( 'DJANGO_SETTINGS_MODULE' ) )
if settings is None :
    raise BuildFailure ( "No settings path defined. Use: options.paved.django.settings = 'path.to.project.settings'" )
manage_py = options . paved . django . manage_py
if manage_py is None :
    manage_py = 'django-admin.py'
else :
    manage_py = path ( manage_py )
    manage_py = 'cd {manage_py.parent}; python ./{manage_py.name}' . format ( ** locals ( ) )
return util . shv ( '{manage_py} {cmd} --settings={settings}' . format ( ** locals ( ) ) , capture = capture , ignore_error = ignore_error )


signature:
def syncdb ( args ) :
    """Update the database with model schema . Shorthand for ` paver manage syncdb ` ."""

implementation:
cmd = args and 'syncdb %s' % ' ' . join ( options . args ) or 'syncdb --noinput'
call_manage ( cmd )
for fixture in options . paved . django . syncdb . fixtures :
    call_manage ( "loaddata %s" % fixture )