signature:
def start ( info ) :
    """Run the dev server .
 Uses ` django _ extensions < http : / / pypi . python . org / pypi / django - extensions / 0.5 > ` , if
 available , to provide ` runserver _ plus ` .
 Set the command to use with ` options . paved . django . runserver `
 Set the port to use with ` options . paved . django . runserver _ port `"""

implementation:
cmd = options . paved . django . runserver
if cmd == 'runserver_plus' :
    try :
        import django_extensions
    except ImportError :
        info ( "Could not import django_extensions. Using default runserver." )
        cmd = 'runserver'
port = options . paved . django . runserver_port
if port :
    cmd = '%s %s' % ( cmd , port )
call_manage ( cmd )


signature:
def schema ( args ) :
    """Run South ' s schemamigration command ."""

implementation:
try :
    import south
    cmd = args and 'schemamigration %s' % ' ' . join ( options . args ) or 'schemamigration'
    call_manage ( cmd )
except ImportError :
    error ( 'Could not import south.' )


signature:
def validate ( cls , definition ) :
    '''This static method validates a BioMapMapper definition .
 It returns None on success and throws an exception otherwise .'''

implementation:
schema_path = os . path . join ( os . path . dirname ( __file__ ) , '../../schema/mapper_definition_schema.json' )
with open ( schema_path , 'r' ) as jsonfp :
    schema = json . load ( jsonfp )
# Validation of JSON schema
jsonschema . validate ( definition , schema )
# Validation of JSON properties relations
assert definition [ 'main_key' ] in definition [ 'supported_keys' ] , '\'main_key\' must be contained in \'supported_keys\''
assert set ( definition . get ( 'list_valued_keys' , [ ] ) ) <= set ( definition [ 'supported_keys' ] ) , '\'list_valued_keys\' must be a subset of \'supported_keys\''
assert set ( definition . get ( 'disjoint' , [ ] ) ) <= set ( definition . get ( 'list_valued_keys' , [ ] ) ) , '\'disjoint\' must be a subset of \'list_valued_keys\''
assert set ( definition . get ( 'key_synonyms' , { } ) . values ( ) ) <= set ( definition [ 'supported_keys' ] ) , '\'The values of the \'key_synonyms\' mapping must be in \'supported_keys\''


signature:
def get_all ( self , key = None ) :
    '''Returns all data entries for a particular key . Default is the main key .
 Args :
 key ( str ) : key whose values to return ( default : main key )
 Returns :
 List of all data entries for the key'''

implementation:
key = self . definition . main_key if key is None else key
key = self . definition . key_synonyms . get ( key , key )
entries = self . _get_all ( key )
if key in self . definition . scalar_nonunique_keys :
    return set ( entries )
return entries


signature:
def get_requests ( self , params = { } ) :
    """List requests
 http : / / dev . wheniwork . com / # listing - requests"""

implementation:
if "status" in params :
    params [ 'status' ] = ',' . join ( map ( str , params [ 'status' ] ) )
requests = [ ]
users = { }
messages = { }
params [ 'page' ] = 0
while True :
    param_list = [ ( k , params [ k ] ) for k in sorted ( params ) ]
    url = "/2/requests/?%s" % urlencode ( param_list )
    data = self . _get_resource ( url )
    for entry in data [ "users" ] :
        user = Users . user_from_json ( entry )
        users [ user . user_id ] = user
    for entry in data [ "requests" ] :
        request = self . request_from_json ( entry )
        requests . append ( request )
    for entry in data [ "messages" ] :
        message = Messages . message_from_json ( entry )
        if message . request_id not in messages :
            messages [ message . request_id ] = [ ]
        messages [ message . request_id ] . append ( message )
    if not data [ 'more' ] :
        break
    params [ 'page' ] += 1
for request in requests :
    request . user = users . get ( request . user_id , None )
    request . messages = messages . get ( request . request_id , [ ] )
return requests


signature:
def guess ( self , * args ) :
    """Make a guess , comparing the hidden object to a set of provided digits . The digits should
 be passed as a set of arguments , e . g :
 * for a normal game : 0 , 1 , 2 , 3
 * for a hex game : 0xA , 0xB , 5 , 4
 * alternate for hex game : ' A ' , ' b ' , 5 , 4
 : param args : An iterable of digits ( int or str )
 : return : A dictionary object detailing the analysis and results of the guess"""

implementation:
if self . game is None :
    raise ValueError ( "The Game is unexpectedly undefined!" )
response_object = { "bulls" : None , "cows" : None , "analysis" : None , "status" : None }
if self . game . status == self . GAME_WON :
    response_object [ "status" ] = self . _start_again_message ( "You already won!" )
elif self . game . status == self . GAME_LOST :
    response_object [ "status" ] = self . _start_again_message ( "You already lost!" )
elif self . game . guesses_remaining < 1 :
    response_object [ "status" ] = self . _start_again_message ( "You've made too many guesses" )
else :
    guess_made = DigitWord ( * args , wordtype = self . game . mode . digit_type )
    comparison = self . game . answer . compare ( guess_made )
    self . game . guesses_made += 1
    response_object [ "bulls" ] = 0
    response_object [ "cows" ] = 0
    response_object [ "analysis" ] = [ ]
    for comparison_object in comparison :
        if comparison_object . match :
            response_object [ "bulls" ] += 1
        elif comparison_object . in_word :
            response_object [ "cows" ] += 1
        response_object [ "analysis" ] . append ( comparison_object . get_object ( ) )
    if response_object [ "bulls" ] == self . game . mode . digits :
        self . game . status = self . GAME_WON
        self . game . guesses_made = self . game . mode . guesses_allowed
        response_object [ "status" ] = self . _start_again_message ( "Congratulations, you win!" )
    elif self . game . guesses_remaining < 1 :
        self . game . status = self . GAME_LOST
        response_object [ "status" ] = self . _start_again_message ( "Sorry, you lost!" )
return response_object


signature:
def load ( self , game_json = None , mode = None ) :
    """Load a game from a serialized JSON representation . The game expects a well defined
 structure as follows ( Note JSON string format ) :
 " guesses _ made " : int ,
 " key " : " str : a 4 word " ,
 " status " : " str : one of playing , won , lost " ,
 " mode " : {
 " digits " : int ,
 " digit _ type " : DigitWord . DIGIT | DigitWord . HEXDIGIT ,
 " mode " : GameMode ( ) ,
 " priority " : int ,
 " help _ text " : str ,
 " instruction _ text " : str ,
 " guesses _ allowed " : int
 " ttl " : int ,
 " answer " : [ int | str0 , int | str1 , . . . , int | strN ]
 * " mode " will be cast to a GameMode object
 * " answer " will be cast to a DigitWord object
 : param game _ json : The source JSON - MUST be a string
 : param mode : A mode ( str or GameMode ) for the game being loaded
 : return : A game object"""

implementation:
if game_json is None : # New game _ json
    if mode is not None :
        if isinstance ( mode , str ) :
            _game_object = GameObject ( mode = self . _match_mode ( mode = mode ) )
        elif isinstance ( mode , GameMode ) :
            _game_object = GameObject ( mode = mode )
        else :
            raise TypeError ( "Game mode must be a GameMode or string" )
    else :
        _game_object = GameObject ( mode = self . _game_modes [ 0 ] )
    _game_object . status = self . GAME_PLAYING
else :
    if not isinstance ( game_json , str ) :
        raise TypeError ( "Game must be passed as a serialized JSON string." )
    game_dict = json . loads ( game_json )
    if not 'mode' in game_dict :
        raise ValueError ( "Mode is not provided in JSON; game_json cannot be loaded!" )
    _mode = GameMode ( ** game_dict [ "mode" ] )
    _game_object = GameObject ( mode = _mode , source_game = game_dict )
self . game = copy . deepcopy ( _game_object )


signature:
def load_modes ( self , input_modes = None ) :
    """Loads modes ( GameMode objects ) to be supported by the game object . Four default
 modes are provided ( normal , easy , hard , and hex ) but others could be provided
 either by calling load _ modes directly or passing a list of GameMode objects to
 the instantiation call .
 : param input _ modes : A list of GameMode objects ; nb : even if only one new GameMode
 object is provided , it MUST be passed as a list - for example , passing GameMode gm1
 would require passing [ gm1 ] NOT gm1.
 : return : A list of GameMode objects ( both defaults and any added ) ."""

implementation:
# Set default game modes
_modes = [ GameMode ( mode = "normal" , priority = 2 , digits = 4 , digit_type = DigitWord . DIGIT , guesses_allowed = 10 ) , GameMode ( mode = "easy" , priority = 1 , digits = 3 , digit_type = DigitWord . DIGIT , guesses_allowed = 6 ) , GameMode ( mode = "hard" , priority = 3 , digits = 6 , digit_type = DigitWord . DIGIT , guesses_allowed = 6 ) , GameMode ( mode = "hex" , priority = 4 , digits = 4 , digit_type = DigitWord . HEXDIGIT , guesses_allowed = 10 ) ]
if input_modes is not None :
    if not isinstance ( input_modes , list ) :
        raise TypeError ( "Expected list of input_modes" )
    for mode in input_modes :
        if not isinstance ( mode , GameMode ) :
            raise TypeError ( "Expected list to contain only GameMode objects" )
        _modes . append ( mode )
self . _game_modes = copy . deepcopy ( _modes )


signature:
def _start_again_message ( self , message = None ) :
    """Simple method to form a start again message and give the answer in readable form ."""

implementation:
logging . debug ( "Start again message delivered: {}" . format ( message ) )
the_answer = ', ' . join ( [ str ( d ) for d in self . game . answer ] [ : - 1 ] ) + ', and ' + [ str ( d ) for d in self . game . answer ] [ - 1 ]
return "{0}{1} The correct answer was {2}. Please start a new game." . format ( message , "." if message [ - 1 ] not in [ "." , "," , ";" , ":" , "!" ] else "" , the_answer )


signature:
def line ( self , line ) :
    """Returns list of strings split by input delimeter
 Argument :
 line - Input line to cut"""

implementation:
# Remove empty strings in case of multiple instances of delimiter
return [ x for x in re . split ( self . delimiter , line . rstrip ( ) ) if x != '' ]


signature:
def get_message ( self , message_id ) :
    """Get Existing Message
 http : / / dev . wheniwork . com / # get - existing - message"""

implementation:
url = "/2/messages/%s" % message_id
return self . message_from_json ( self . _get_resource ( url ) [ "message" ] )


signature:
def get_messages ( self , params = { } ) :
    """List messages
 http : / / dev . wheniwork . com / # listing - messages"""

implementation:
param_list = [ ( k , params [ k ] ) for k in sorted ( params ) ]
url = "/2/messages/?%s" % urlencode ( param_list )
data = self . _get_resource ( url )
messages = [ ]
for entry in data [ "messages" ] :
    messages . append ( self . message_from_json ( entry ) )
return messages


signature:
def create_message ( self , params = { } ) :
    """Creates a message
 http : / / dev . wheniwork . com / # create / update - message"""

implementation:
url = "/2/messages/"
body = params
data = self . _post_resource ( url , body )
return self . message_from_json ( data [ "message" ] )


signature:
def update_message ( self , message ) :
    """Modify an existing message .
 http : / / dev . wheniwork . com / # create / update - message"""

implementation:
url = "/2/messages/%s" % message . message_id
data = self . _put_resource ( url , message . json_data ( ) )
return self . message_from_json ( data )


signature:
def delete_messages ( self , messages ) :
    """Delete existing messages .
 http : / / dev . wheniwork . com / # delete - existing - message"""

implementation:
url = "/2/messages/?%s" % urlencode ( [ ( 'ids' , "," . join ( messages ) ) ] )
data = self . _delete_resource ( url )
return data


signature:
def get_site ( self , site_id ) :
    """Returns site data .
 http : / / dev . wheniwork . com / # get - existing - site"""

implementation:
url = "/2/sites/%s" % site_id
return self . site_from_json ( self . _get_resource ( url ) [ "site" ] )


signature:
def get_sites ( self ) :
    """Returns a list of sites .
 http : / / dev . wheniwork . com / # listing - sites"""

implementation:
url = "/2/sites"
data = self . _get_resource ( url )
sites = [ ]
for entry in data [ 'sites' ] :
    sites . append ( self . site_from_json ( entry ) )
return sites


signature:
def create_site ( self , params = { } ) :
    """Creates a site
 http : / / dev . wheniwork . com / # create - update - site"""

implementation:
url = "/2/sites/"
body = params
data = self . _post_resource ( url , body )
return self . site_from_json ( data [ "site" ] )


signature:
def admin_link_move_up ( obj , link_text = 'up' ) :
    """Returns a link to a view that moves the passed in object up in rank .
 : param obj :
 Object to move
 : param link _ text :
 Text to display in the link . Defaults to " up "
 : returns :
 HTML link code to view for moving the object"""

implementation:
if obj . rank == 1 :
    return ''
content_type = ContentType . objects . get_for_model ( obj )
link = reverse ( 'awl-rankedmodel-move' , args = ( content_type . id , obj . id , obj . rank - 1 ) )
return '%s' % ( link , link_text )


signature:
def admin_link_move_down ( obj , link_text = 'down' ) :
    """Returns a link to a view that moves the passed in object down in rank .
 : param obj :
 Object to move
 : param link _ text :
 Text to display in the link . Defaults to " down "
 : returns :
 HTML link code to view for moving the object"""

implementation:
if obj . rank == obj . grouped_filter ( ) . count ( ) :
    return ''
content_type = ContentType . objects . get_for_model ( obj )
link = reverse ( 'awl-rankedmodel-move' , args = ( content_type . id , obj . id , obj . rank + 1 ) )
return '%s' % ( link , link_text )


signature:
def showfig ( fig , aspect = "auto" ) :
    """Shows a figure with a typical orientation so that x and y axes are set up as expected ."""

implementation:
ax = fig . gca ( )
# Swap y axis if needed
alim = list ( ax . axis ( ) )
if alim [ 3 ] < alim [ 2 ] :
    temp = alim [ 2 ]
    alim [ 2 ] = alim [ 3 ]
    alim [ 3 ] = temp
    ax . axis ( alim )
ax . set_aspect ( aspect )
fig . show ( )


signature:
def _setup_index ( index ) :
    """Shifts indicies as needed to account for one based indexing
 Positive indicies need to be reduced by one to match with zero based
 indexing .
 Zero is not a valid input , and as such will throw a value error .
 Arguments :
 index - index to shift"""

implementation:
index = int ( index )
if index > 0 :
    index -= 1
elif index == 0 : # Zero indicies should not be allowed by default .
    raise ValueError
return index


signature:
def cut ( self , line ) :
    """Returns selected positions from cut input source in desired
 arrangement .
 Argument :
 line - input to cut"""

implementation:
result = [ ]
line = self . line ( line )
for i , field in enumerate ( self . positions ) :
    try :
        index = _setup_index ( field )
        try :
            result += line [ index ]
        except IndexError :
            result . append ( self . invalid_pos )
    except ValueError :
        result . append ( str ( field ) )
    except TypeError :
        result . extend ( self . _cut_range ( line , int ( field [ 0 ] ) , i ) )
return '' . join ( result )


signature:
def _setup_positions ( self , positions ) :
    """Processes positions to account for ranges
 Arguments :
 positions - list of positions and / or ranges to process"""

implementation:
updated_positions = [ ]
for i , position in enumerate ( positions ) :
    ranger = re . search ( r'(?P<start>-?\d*):(?P<end>\d*)' , position )
    if ranger :
        if i > 0 :
            updated_positions . append ( self . separator )
        start = group_val ( ranger . group ( 'start' ) )
        end = group_val ( ranger . group ( 'end' ) )
        if start and end :
            updated_positions . extend ( self . _extendrange ( start , end + 1 ) )
        # Since the number of positions on a line is unknown ,
        # send input to cause exception that can be caught and call
        # _ cut _ range helper function
        elif ranger . group ( 'start' ) :
            updated_positions . append ( [ start ] )
        else :
            updated_positions . extend ( self . _extendrange ( 1 , end + 1 ) )
    else :
        updated_positions . append ( positions [ i ] )
        try :
            if int ( position ) and int ( positions [ i + 1 ] ) :
                updated_positions . append ( self . separator )
        except ( ValueError , IndexError ) :
            pass
return updated_positions


signature:
def _cut_range ( self , line , start , current_position ) :
    """Performs cut for range from start position to end
 Arguments :
 line - input to cut
 start - start of range
 current _ position - current position in main cut function"""

implementation:
result = [ ]
try :
    for j in range ( start , len ( line ) ) :
        index = _setup_index ( j )
        try :
            result . append ( line [ index ] )
        except IndexError :
            result . append ( self . invalid_pos )
        finally :
            result . append ( self . separator )
    result . append ( line [ - 1 ] )
except IndexError :
    pass
try :
    int ( self . positions [ current_position + 1 ] )
    result . append ( self . separator )
except ( ValueError , IndexError ) :
    pass
return result


signature:
def _extendrange ( self , start , end ) :
    """Creates list of values in a range with output delimiters .
 Arguments :
 start - range start
 end - range end"""

implementation:
range_positions = [ ]
for i in range ( start , end ) :
    if i != 0 :
        range_positions . append ( str ( i ) )
    if i < end :
        range_positions . append ( self . separator )
return range_positions


signature:
def lock_file ( filename ) :
    """Locks the file by writing a ' . lock ' file .
 Returns True when the file is locked and
 False when the file was locked already"""

implementation:
lockfile = "%s.lock" % filename
if isfile ( lockfile ) :
    return False
else :
    with open ( lockfile , "w" ) :
        pass
return True


signature:
def unlock_file ( filename ) :
    """Unlocks the file by remove a ' . lock ' file .
 Returns True when the file is unlocked and
 False when the file was unlocked already"""

implementation:
lockfile = "%s.lock" % filename
if isfile ( lockfile ) :
    os . remove ( lockfile )
    return True
else :
    return False


signature:
def copy_smart_previews ( local_catalog , cloud_catalog , local2cloud = True ) :
    """Copy Smart Previews from local to cloud or
 vica versa when ' local2cloud = = False '
 NB : nothing happens if source dir doesn ' t exist"""

implementation:
lcat_noext = local_catalog [ 0 : local_catalog . rfind ( ".lrcat" ) ]
ccat_noext = cloud_catalog [ 0 : cloud_catalog . rfind ( ".lrcat" ) ]
lsmart = join ( dirname ( local_catalog ) , "%s Smart Previews.lrdata" % basename ( lcat_noext ) )
csmart = join ( dirname ( cloud_catalog ) , "%s Smart Previews.lrdata" % basename ( ccat_noext ) )
if local2cloud and os . path . isdir ( lsmart ) :
    logging . info ( "Copy Smart Previews - local to cloud: %s => %s" % ( lsmart , csmart ) )
    distutils . dir_util . copy_tree ( lsmart , csmart , update = 1 )
elif os . path . isdir ( csmart ) :
    logging . info ( "Copy Smart Previews - cloud to local: %s => %s" % ( csmart , lsmart ) )
    distutils . dir_util . copy_tree ( csmart , lsmart , update = 1 )


signature:
def hashsum ( filename ) :
    """Return a hash of the file From < http : / / stackoverflow . com / a / 7829658 >"""

implementation:
with open ( filename , mode = 'rb' ) as f :
    d = hashlib . sha1 ( )
    for buf in iter ( partial ( f . read , 2 ** 20 ) , b'' ) :
        d . update ( buf )
return d . hexdigest ( )


signature:
def cmd_init_push_to_cloud ( args ) :
    """Initiate the local catalog and push it the cloud"""

implementation:
( lcat , ccat ) = ( args . local_catalog , args . cloud_catalog )
logging . info ( "[init-push-to-cloud]: %s => %s" % ( lcat , ccat ) )
if not isfile ( lcat ) :
    args . error ( "[init-push-to-cloud] The local catalog does not exist: %s" % lcat )
if isfile ( ccat ) :
    args . error ( "[init-push-to-cloud] The cloud catalog already exist: %s" % ccat )
( lmeta , cmeta ) = ( "%s.lrcloud" % lcat , "%s.lrcloud" % ccat )
if isfile ( lmeta ) :
    args . error ( "[init-push-to-cloud] The local meta-data already exist: %s" % lmeta )
if isfile ( cmeta ) :
    args . error ( "[init-push-to-cloud] The cloud meta-data already exist: %s" % cmeta )
# Let ' s " lock " the local catalog
logging . info ( "Locking local catalog: %s" % ( lcat ) )
if not lock_file ( lcat ) :
    raise RuntimeError ( "The catalog %s is locked!" % lcat )
# Copy catalog from local to cloud , which becomes the new " base " changeset
util . copy ( lcat , ccat )
# Write meta - data both to local and cloud
mfile = MetaFile ( lmeta )
utcnow = datetime . utcnow ( ) . strftime ( DATETIME_FORMAT ) [ : - 4 ]
mfile [ 'catalog' ] [ 'hash' ] = hashsum ( lcat )
mfile [ 'catalog' ] [ 'modification_utc' ] = utcnow
mfile [ 'catalog' ] [ 'filename' ] = lcat
mfile [ 'last_push' ] [ 'filename' ] = ccat
mfile [ 'last_push' ] [ 'hash' ] = hashsum ( lcat )
mfile [ 'last_push' ] [ 'modification_utc' ] = utcnow
mfile . flush ( )
mfile = MetaFile ( cmeta )
mfile [ 'changeset' ] [ 'is_base' ] = True
mfile [ 'changeset' ] [ 'hash' ] = hashsum ( lcat )
mfile [ 'changeset' ] [ 'modification_utc' ] = utcnow
mfile [ 'changeset' ] [ 'filename' ] = basename ( ccat )
mfile . flush ( )
# Let ' s copy Smart Previews
if not args . no_smart_previews :
    copy_smart_previews ( lcat , ccat , local2cloud = True )
# Finally , let ' s unlock the catalog files
logging . info ( "Unlocking local catalog: %s" % ( lcat ) )
unlock_file ( lcat )
logging . info ( "[init-push-to-cloud]: Success!" )


signature:
def cmd_init_pull_from_cloud ( args ) :
    """Initiate the local catalog by downloading the cloud catalog"""

implementation:
( lcat , ccat ) = ( args . local_catalog , args . cloud_catalog )
logging . info ( "[init-pull-from-cloud]: %s => %s" % ( ccat , lcat ) )
if isfile ( lcat ) :
    args . error ( "[init-pull-from-cloud] The local catalog already exist: %s" % lcat )
if not isfile ( ccat ) :
    args . error ( "[init-pull-from-cloud] The cloud catalog does not exist: %s" % ccat )
( lmeta , cmeta ) = ( "%s.lrcloud" % lcat , "%s.lrcloud" % ccat )
if isfile ( lmeta ) :
    args . error ( "[init-pull-from-cloud] The local meta-data already exist: %s" % lmeta )
if not isfile ( cmeta ) :
    args . error ( "[init-pull-from-cloud] The cloud meta-data does not exist: %s" % cmeta )
# Let ' s " lock " the local catalog
logging . info ( "Locking local catalog: %s" % ( lcat ) )
if not lock_file ( lcat ) :
    raise RuntimeError ( "The catalog %s is locked!" % lcat )
# Copy base from cloud to local
util . copy ( ccat , lcat )
# Apply changesets
cloudDAG = ChangesetDAG ( ccat )
path = cloudDAG . path ( cloudDAG . root . hash , cloudDAG . leafs [ 0 ] . hash )
util . apply_changesets ( args , path , lcat )
# Write meta - data both to local and cloud
mfile = MetaFile ( lmeta )
utcnow = datetime . utcnow ( ) . strftime ( DATETIME_FORMAT ) [ : - 4 ]
mfile [ 'catalog' ] [ 'hash' ] = hashsum ( lcat )
mfile [ 'catalog' ] [ 'modification_utc' ] = utcnow
mfile [ 'catalog' ] [ 'filename' ] = lcat
mfile [ 'last_push' ] [ 'filename' ] = cloudDAG . leafs [ 0 ] . mfile [ 'changeset' ] [ 'filename' ]
mfile [ 'last_push' ] [ 'hash' ] = cloudDAG . leafs [ 0 ] . mfile [ 'changeset' ] [ 'hash' ]
mfile [ 'last_push' ] [ 'modification_utc' ] = cloudDAG . leafs [ 0 ] . mfile [ 'changeset' ] [ 'modification_utc' ]
mfile . flush ( )
# Let ' s copy Smart Previews
if not args . no_smart_previews :
    copy_smart_previews ( lcat , ccat , local2cloud = False )
# Finally , let ' s unlock the catalog files
logging . info ( "Unlocking local catalog: %s" % ( lcat ) )
unlock_file ( lcat )
logging . info ( "[init-pull-from-cloud]: Success!" )


signature:
def cmd_normal ( args ) :
    """Normal procedure :
 * Pull from cloud ( if necessary )
 * Run Lightroom
 * Push to cloud"""

implementation:
logging . info ( "cmd_normal" )
( lcat , ccat ) = ( args . local_catalog , args . cloud_catalog )
( lmeta , cmeta ) = ( "%s.lrcloud" % lcat , "%s.lrcloud" % ccat )
if not isfile ( lcat ) :
    args . error ( "The local catalog does not exist: %s" % lcat )
if not isfile ( ccat ) :
    args . error ( "The cloud catalog does not exist: %s" % ccat )
# Let ' s " lock " the local catalog
logging . info ( "Locking local catalog: %s" % ( lcat ) )
if not lock_file ( lcat ) :
    raise RuntimeError ( "The catalog %s is locked!" % lcat )
# Backup the local catalog ( overwriting old backup )
logging . info ( "Removed old backup: %s.backup" % lcat )
util . remove ( "%s.backup" % lcat )
util . copy ( lcat , "%s.backup" % lcat )
lmfile = MetaFile ( lmeta )
cmfile = MetaFile ( cmeta )
# Apply changesets
cloudDAG = ChangesetDAG ( ccat )
path = cloudDAG . path ( lmfile [ 'last_push' ] [ 'hash' ] , cloudDAG . leafs [ 0 ] . hash )
util . apply_changesets ( args , path , lcat )
# Let ' s copy Smart Previews
if not args . no_smart_previews :
    copy_smart_previews ( lcat , ccat , local2cloud = False )
# Backup the local catalog ( overwriting old backup )
logging . info ( "Removed old backup: %s.backup" % lcat )
util . remove ( "%s.backup" % lcat )
util . copy ( lcat , "%s.backup" % lcat )
# Let ' s unlock the local catalog so that Lightroom can read it
logging . info ( "Unlocking local catalog: %s" % ( lcat ) )
unlock_file ( lcat )
# Now we can start Lightroom
if args . lightroom_exec_debug :
    logging . info ( "Debug Lightroom appending '%s' to %s" % ( args . lightroom_exec_debug , lcat ) )
    with open ( lcat , "a" ) as f :
        f . write ( "%s\n" % args . lightroom_exec_debug )
elif args . lightroom_exec :
    logging . info ( "Starting Lightroom: %s %s" % ( args . lightroom_exec , lcat ) )
    subprocess . call ( [ args . lightroom_exec , lcat ] )
tmpdir = tempfile . mkdtemp ( )
tmp_patch = join ( tmpdir , "tmp.patch" )
diff_cmd = args . diff_cmd . replace ( "$in1" , "%s.backup" % lcat ) . replace ( "$in2" , lcat ) . replace ( "$out" , tmp_patch )
logging . info ( "Diff: %s" % diff_cmd )
subprocess . call ( diff_cmd , shell = True )
patch = "%s_%s.zip" % ( ccat , hashsum ( tmp_patch ) )
util . copy ( tmp_patch , patch )
# Write cloud meta - data
mfile = MetaFile ( "%s.lrcloud" % patch )
utcnow = datetime . utcnow ( ) . strftime ( DATETIME_FORMAT ) [ : - 4 ]
mfile [ 'changeset' ] [ 'is_base' ] = False
mfile [ 'changeset' ] [ 'hash' ] = hashsum ( tmp_patch )
mfile [ 'changeset' ] [ 'modification_utc' ] = utcnow
mfile [ 'changeset' ] [ 'filename' ] = basename ( patch )
mfile [ 'parent' ] [ 'is_base' ] = cloudDAG . leafs [ 0 ] . mfile [ 'changeset' ] [ 'is_base' ]
mfile [ 'parent' ] [ 'hash' ] = cloudDAG . leafs [ 0 ] . mfile [ 'changeset' ] [ 'hash' ]
mfile [ 'parent' ] [ 'modification_utc' ] = cloudDAG . leafs [ 0 ] . mfile [ 'changeset' ] [ 'modification_utc' ]
mfile [ 'parent' ] [ 'filename' ] = basename ( cloudDAG . leafs [ 0 ] . mfile [ 'changeset' ] [ 'filename' ] )
mfile . flush ( )
# Write local meta - data
mfile = MetaFile ( lmeta )
mfile [ 'catalog' ] [ 'hash' ] = hashsum ( lcat )
mfile [ 'catalog' ] [ 'modification_utc' ] = utcnow
mfile [ 'last_push' ] [ 'filename' ] = patch
mfile [ 'last_push' ] [ 'hash' ] = hashsum ( tmp_patch )
mfile [ 'last_push' ] [ 'modification_utc' ] = utcnow
mfile . flush ( )
shutil . rmtree ( tmpdir , ignore_errors = True )
# Let ' s copy Smart Previews
if not args . no_smart_previews :
    copy_smart_previews ( lcat , ccat , local2cloud = True )
# Finally , let ' s unlock the catalog files
logging . info ( "Unlocking local catalog: %s" % ( lcat ) )
unlock_file ( lcat )


signature:
def path ( self , a_hash , b_hash ) :
    """Return nodes in the path between ' a ' and ' b ' going from
 parent to child NOT including ' a '"""

implementation:
def _path ( a , b ) :
    if a is b :
        return [ a ]
    else :
        assert len ( a . children ) == 1
        return [ a ] + _path ( a . children [ 0 ] , b )
a = self . nodes [ a_hash ]
b = self . nodes [ b_hash ]
return _path ( a , b ) [ 1 : ]


signature:
def _rindex ( mylist : Sequence [ T ] , x : T ) -> int :
    """Index of the last occurrence of x in the sequence ."""

implementation: return len ( mylist ) - mylist [ : : - 1 ] . index ( x ) - 1


signature:
def raw_to_delimited ( header : Header , raw_payload : RawPayload ) -> DelimitedMsg :
    """Returns a message consisting of header frames , delimiter frame , and payload frames .
 The payload frames may be given as sequences of bytes ( raw ) or as ` Message ` s ."""

implementation: return tuple ( header ) + ( b'' , ) + tuple ( raw_payload )


signature:
def to_delimited ( header : Header , payload : Payload , side : CommSide ) -> DelimitedMsg :
    """Returns a message consisting of header frames , delimiter frame , and payload frames .
 The payload frames may be given as sequences of bytes ( raw ) or as ` Message ` s ."""

implementation: return raw_to_delimited ( header , [ side . serialize ( msg ) for msg in payload ] )


signature:
def raw_from_delimited ( msgs : DelimitedMsg ) -> RawMsgs :
    """From a message consisting of header frames , delimiter frame , and payload frames , return a tuple ` ( header , payload ) ` .
 The payload frames may be returned as sequences of bytes ( raw ) or as ` Message ` s ."""

implementation:
delim = _rindex ( msgs , b'' )
return tuple ( msgs [ : delim ] ) , tuple ( msgs [ delim + 1 : ] )


signature:
def from_delimited ( msgs : DelimitedMsg , side : CommSide ) -> Msgs :
    """From a message consisting of header frames , delimiter frame , and payload frames , return a tuple ` ( header , payload ) ` .
 The payload frames may be returned as sequences of bytes ( raw ) or as ` Message ` s ."""

implementation:
header , raw_payload = raw_from_delimited ( msgs )
return header , tuple ( side . parse ( msg_raw ) for msg_raw in raw_payload )


signature:
def figure ( title = None , ** kwargs ) :
    """Creates a figure with * \ * \ * kwargs * with a window title * title * .
 Returns class : class : ` matplotlib . figure . Figure ` ."""

implementation:
fig = _figure ( ** kwargs )
if title is not None :
    fig . canvas . set_window_title ( title )
return fig


signature:
def create_admin ( username = 'admin' , email = 'admin@admin.com' , password = 'admin' ) :
    """Create and save an admin user .
 : param username :
 Admin account ' s username . Defaults to ' admin '
 : param email :
 Admin account ' s email address . Defaults to ' admin @ admin . com '
 : param password :
 Admin account ' s password . Defaults to ' admin '
 : returns :
 Django user with staff and superuser privileges"""

implementation:
admin = User . objects . create_user ( username , email , password )
admin . is_staff = True
admin . is_superuser = True
admin . save ( )
return admin


signature:
def messages_from_response ( response ) :
    """Returns a list of the messages from the django MessageMiddleware
 package contained within the given response . This is to be used during
 unit testing when trying to see if a message was set properly in a view .
 : param response : HttpResponse object , likely obtained through a
 test client . get ( ) or client . post ( ) call
 : returns : a list of tuples ( message _ string , message _ level ) , one for each
 message in the response context"""

implementation:
messages = [ ]
if hasattr ( response , 'context' ) and response . context and 'messages' in response . context :
    messages = response . context [ 'messages' ]
elif hasattr ( response , 'cookies' ) : # no " context " set - up or no messages item , check for message info in
# the cookies
    morsel = response . cookies . get ( 'messages' )
    if not morsel :
        return [ ]
    # use the decoder in the CookieStore to process and get a list of
    # messages
    from django . contrib . messages . storage . cookie import CookieStorage
    store = CookieStorage ( FakeRequest ( ) )
    messages = store . _decode ( morsel . value )
else :
    return [ ]
return [ ( m . message , m . level ) for m in messages ]


signature:
def initiate ( self ) :
    """Sets up the : class : ` AdminSite ` and creates a user with the
 appropriate privileges . This should be called from the inheritor ' s
 : class : ` TestCase . setUp ` method ."""

implementation:
self . site = admin . sites . AdminSite ( )
self . admin_user = create_admin ( self . USERNAME , self . EMAIL , self . PASSWORD )
self . authed = False


signature:
def authorize ( self ) :
    """Authenticates the superuser account via the web login ."""

implementation:
response = self . client . login ( username = self . USERNAME , password = self . PASSWORD )
self . assertTrue ( response )
self . authed = True


signature:
def authed_get ( self , url , response_code = 200 , headers = { } , follow = False ) :
    """Does a django test client ` ` get ` ` against the given url after
 logging in the admin first .
 : param url :
 URL to fetch
 : param response _ code :
 Expected response code from the URL fetch . This value is
 asserted . Defaults to 200
 : param headers :
 Optional dictionary of headers to send in the request
 : param follow :
 When True , the get call will follow any redirect requests .
 Defaults to False .
 : returns :
 Django testing ` ` Response ` ` object"""

implementation:
if not self . authed :
    self . authorize ( )
response = self . client . get ( url , follow = follow , ** headers )
self . assertEqual ( response_code , response . status_code )
return response


signature:
def authed_post ( self , url , data , response_code = 200 , follow = False , headers = { } ) :
    """Does a django test client ` ` post ` ` against the given url after
 logging in the admin first .
 : param url :
 URL to fetch
 : param data :
 Dictionary to form contents to post
 : param response _ code :
 Expected response code from the URL fetch . This value is
 asserted . Defaults to 200
 : param headers :
 Optional dictionary of headers to send in with the request
 : returns :
 Django testing ` ` Response ` ` object"""

implementation:
if not self . authed :
    self . authorize ( )
response = self . client . post ( url , data , follow = follow , ** headers )
self . assertEqual ( response_code , response . status_code )
return response


signature:
def visit_admin_link ( self , admin_model , instance , field_name , response_code = 200 , headers = { } ) :
    """This method is used for testing links that are in the change list
 view of the django admin . For the given instance and field name , the
 HTML link tags in the column are parsed for a URL and then invoked
 with : class : ` AdminToolsMixin . authed _ get ` .
 : param admin _ model :
 Instance of a : class : ` admin . ModelAdmin ` object that is responsible
 for displaying the change list
 : param instance :
 Object instance that is the row in the admin change list
 : param field _ name :
 Name of the field / column to containing the HTML link to get a URL
 from to visit
 : param response _ code :
 Expected HTTP status code resulting from the call . The value of
 this is asserted . Defaults to 200.
 : param headers :
 Optional dictionary of headers to send in the request
 : returns :
 Django test ` ` Response ` ` object
 : raises AttributeError :
 If the column does not contain a URL that can be parsed"""

implementation:
html = self . field_value ( admin_model , instance , field_name )
url , text = parse_link ( html )
if not url :
    raise AttributeError ( 'href could not be parsed from *%s*' % html )
return self . authed_get ( url , response_code = response_code , headers = headers )


signature:
def field_value ( self , admin_model , instance , field_name ) :
    """Returns the value displayed in the column on the web interface for
 a given instance .
 : param admin _ model :
 Instance of a : class : ` admin . ModelAdmin ` object that is responsible
 for displaying the change list
 : param instance :
 Object instance that is the row in the admin change list
 : field _ name :
 Name of the field / column to fetch"""

implementation:
_ , _ , value = lookup_field ( field_name , instance , admin_model )
return value


signature:
def field_names ( self , admin_model ) :
    """Returns the names of the fields / columns used by the given admin
 model .
 : param admin _ model :
 Instance of a : class : ` admin . ModelAdmin ` object that is responsible
 for displaying the change list
 : returns :
 List of field names"""

implementation:
request = FakeRequest ( user = self . admin_user )
return admin_model . get_list_display ( request )


signature:
def githubtunnel ( user1 , server1 , user2 , server2 , port , verbose , stanford = False ) :
    """Opens a nested tunnel , first to * user1 * @ * server1 * , then to * user2 * @ * server2 * , for accessing on * port * .
 If * verbose * is true , prints various ssh commands .
 If * stanford * is true , shifts ports up by 1.
 Attempts to get * user1 * , * user2 * from environment variable ` ` USER _ NAME ` ` if called from the command line ."""

implementation:
if stanford :
    port_shift = 1
else :
    port_shift = 0
# command1 = ' ssh - nNf - L { } : quickpicmac3 . slac . stanford . edu : 22 { } @ { } ' . format ( port , user , server )
command1 = 'ssh -nNf -L {}:{}:22 {}@{}' . format ( port - 1 - port_shift , server2 , user1 , server1 )
command2 = 'ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -nNf -L {}:cardinal.stanford.edu:22 -p {} {}@localhost' . format ( port - port_shift , port - port_shift - 1 , user2 )
command3 = 'ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -nNf -L {}:github.com:22 -p {} {}@localhost' . format ( port , port - 1 , user2 )
if verbose :
    print ( command1 )
    if stanford :
        print ( command2 )
    print ( command3 )
try :
    call ( shlex . split ( command1 ) )
    if stanford :
        call ( shlex . split ( command2 ) )
    call ( shlex . split ( command3 ) )
except :
    print ( 'Failure!' )
    pass


signature:
def imgmax ( self ) :
    """Highest value of input image ."""

implementation:
if not hasattr ( self , '_imgmax' ) :
    imgmax = _np . max ( self . images [ 0 ] )
    for img in self . images :
        imax = _np . max ( img )
        if imax > imgmax :
            imgmax = imax
    self . _imgmax = imgmax
return self . _imgmax


signature:
def imgmin ( self ) :
    """Lowest value of input image ."""

implementation:
if not hasattr ( self , '_imgmin' ) :
    imgmin = _np . min ( self . images [ 0 ] )
    for img in self . images :
        imin = _np . min ( img )
        if imin > imgmin :
            imgmin = imin
    self . _imgmin = imgmin
return _np . min ( self . image )


signature:
def spawn ( func , * args , ** kwargs ) :
    """spawns a greenlet that does not print exceptions to the screen .
 if you use this function you MUST use this module ' s join or joinall otherwise the exception will be lost"""

implementation: return gevent . spawn ( wrap_uncaught_greenlet_exceptions ( func ) , * args , ** kwargs )


signature:
def _usage ( prog_name = os . path . basename ( sys . argv [ 0 ] ) ) :
    '''Returns usage string with no trailing whitespace .'''

implementation:
spacer = ' ' * len ( 'usage: ' )
usage = prog_name + ' -b LIST [-S SEPARATOR] [file ...]\n' + spacer + prog_name + ' -c LIST [-S SEPERATOR] [file ...]\n' + spacer + prog_name + ' -f LIST [-d DELIM] [-e] [-S SEPERATOR] [-s] [file ...]'
# Return usage message with trailing whitespace removed .
return "usage: " + usage . rstrip ( )


signature:
def _parse_args ( args ) :
    """Setup argparser to process arguments and generate help"""

implementation:
# parser uses custom usage string , with ' usage : ' removed , as it is
# added automatically via argparser .
parser = argparse . ArgumentParser ( description = "Remove and/or rearrange " + "sections from each line of a file(s)." , usage = _usage ( ) [ len ( 'usage: ' ) : ] )
parser . add_argument ( '-b' , "--bytes" , action = 'store' , type = lst , default = [ ] , help = "Bytes to select" )
parser . add_argument ( '-c' , "--chars" , action = 'store' , type = lst , default = [ ] , help = "Character to select" )
parser . add_argument ( '-f' , "--fields" , action = 'store' , type = lst , default = [ ] , help = "Fields to select" )
parser . add_argument ( '-d' , "--delimiter" , action = 'store' , default = "\t" , help = "Sets field delimiter(default is TAB)" )
parser . add_argument ( '-e' , "--regex" , action = 'store_true' , help = 'Enable regular expressions to be used as input ' + 'delimiter' )
parser . add_argument ( '-s' , '--skip' , action = 'store_true' , help = "Skip lines that do not contain input delimiter." )
parser . add_argument ( '-S' , "--separator" , action = 'store' , default = "\t" , help = "Sets field separator for output." )
parser . add_argument ( 'file' , nargs = '*' , default = "-" , help = "File(s) to cut" )
return parser . parse_args ( args )


signature:
def main ( args = sys . argv [ 1 : ] ) :
    '''Processes command line arguments and file i / o'''

implementation:
if not args :
    sys . stderr . write ( _usage ( ) + '\n' )
    sys . exit ( 4 )
else :
    parsed = _parse_args ( args )
# Set delim based on whether or not regex is desired by user
delim = parsed . delimiter if parsed . regex else re . escape ( parsed . delimiter )
# Keep track of number of cutters used to allow error handling if
# multiple options selected ( only one at a time is accepted )
num_cutters = 0
# Read mode will be used as file read mode later . ' r ' is default , changed
# to ' rb ' in the event that binary read mode is selected by user
read_mode = 'r'
if parsed . bytes :
    positions = parsed . bytes
    cutter = ByteCutter ( positions )
    num_cutters += 1
    read_mode = 'rb'
if parsed . chars :
    positions = parsed . chars
    cutter = CharCutter ( positions )
    num_cutters += 1
if parsed . fields :
    positions = parsed . fields
    cutter = FieldCutter ( positions , delim , parsed . separator )
    num_cutters += 1
# Make sure only one option of - b , - c , or - f is used
if num_cutters > 1 :
    sys . stderr . write ( 'Only one option permitted of -b, -c, -f.\n' )
    sys . stderr . write ( _usage ( ) + '\n' )
    sys . exit ( 1 )
# Check for possible specification of zero index , which is not allowed .
# Regular expression checks for zero by itself , or in range specification
if [ n for n in positions if re . search ( "0:?|0$" , n ) ] :
    sys . stderr . write ( 'Zero is an invalid position.\n' )
    sys . stderr . write ( _usage ( ) + '\n' )
    sys . exit ( 2 )
try :
    for line in fileinput . input ( parsed . file , mode = read_mode ) :
        if parsed . skip and not re . search ( parsed . delimiter , line ) :
            pass
        else : # Using sys . stdout . write for consistency between Py 2 and 3,
        # keeping linter happy
            print ( cutter . cut ( line ) )
except IOError :
    sys . stderr . write ( 'File \'' + fileinput . filename ( ) + '\' could not be found.\n' )
    sys . exit ( 3 )
fileinput . close ( )


signature:
def NonUniformImage_axes ( img ) :
    """Returns axes * x , y * for a given image * img * to be used with : func : ` scisalt . matplotlib . NonUniformImage ` .
 Returns
 x , y : float , float"""

implementation:
xmin = 0
xmax = img . shape [ 1 ] - 1
ymin = 0
ymax = img . shape [ 0 ] - 1
x = _np . linspace ( xmin , xmax , img . shape [ 1 ] )
y = _np . linspace ( ymin , ymax , img . shape [ 0 ] )
return x , y


signature:
def move ( request , content_type_id , obj_id , rank ) :
    """View to be used in the django admin for changing a : class : ` RankedModel `
 object ' s rank . See : func : ` admin _ link _ move _ up ` and
 : func : ` admin _ link _ move _ down ` for helper functions to incoroprate in your
 admin models .
 Upon completion this view sends the caller back to the referring page .
 : param content _ type _ id :
 ` ` ContentType ` ` id of object being moved
 : param obj _ id :
 ID of object being moved
 : param rank :
 New rank of the object"""

implementation:
content_type = ContentType . objects . get_for_id ( content_type_id )
obj = get_object_or_404 ( content_type . model_class ( ) , id = obj_id )
obj . rank = int ( rank )
obj . save ( )
return HttpResponseRedirect ( request . META [ 'HTTP_REFERER' ] )


signature:
def open_s3 ( bucket ) :
    """Opens connection to S3 returning bucket and key"""

implementation:
conn = boto . connect_s3 ( options . paved . s3 . access_id , options . paved . s3 . secret )
try :
    bucket = conn . get_bucket ( bucket )
except boto . exception . S3ResponseError :
    bucket = conn . create_bucket ( bucket )
return bucket


signature:
def upload_s3 ( file_path , bucket_name , file_key , force = False , acl = 'private' ) :
    """Upload a local file to S3."""

implementation:
file_path = path ( file_path )
bucket = open_s3 ( bucket_name )
if file_path . isdir ( ) : # Upload the contents of the dir path .
    paths = file_path . listdir ( )
    paths_keys = list ( zip ( paths , [ '%s/%s' % ( file_key , p . name ) for p in paths ] ) )
else : # Upload just the given file path .
    paths_keys = [ ( file_path , file_key ) ]
for p , k in paths_keys :
    headers = { }
    s3_key = bucket . get_key ( k )
    if not s3_key :
        from boto . s3 . key import Key
        s3_key = Key ( bucket , k )
    content_type = mimetypes . guess_type ( p ) [ 0 ]
    if content_type :
        headers [ 'Content-Type' ] = content_type
    file_size = p . stat ( ) . st_size
    file_data = p . bytes ( )
    file_md5 , file_md5_64 = s3_key . get_md5_from_hexdigest ( hashlib . md5 ( file_data ) . hexdigest ( ) )
    # Check the hash .
    if s3_key . etag :
        s3_md5 = s3_key . etag . replace ( '"' , '' )
        if s3_md5 == file_md5 :
            info ( 'Hash is the same. Skipping %s' % file_path )
            continue
        elif not force : # Check if file on S3 is older than local file .
            s3_datetime = datetime . datetime ( * time . strptime ( s3_key . last_modified , '%a, %d %b %Y %H:%M:%S %Z' ) [ 0 : 6 ] )
            local_datetime = datetime . datetime . utcfromtimestamp ( p . stat ( ) . st_mtime )
            if local_datetime < s3_datetime :
                info ( "File %s hasn't been modified since last " "being uploaded" % ( file_key ) )
                continue
    # File is newer , let ' s process and upload
    info ( "Uploading %s..." % ( file_key ) )
    try :
        s3_key . set_contents_from_string ( file_data , headers , policy = acl , replace = True , md5 = ( file_md5 , file_md5_64 ) )
    except Exception as e :
        error ( "Failed: %s" % e )
        raise


signature:
def download_s3 ( bucket_name , file_key , file_path , force = False ) :
    """Download a remote file from S3."""

implementation:
file_path = path ( file_path )
bucket = open_s3 ( bucket_name )
file_dir = file_path . dirname ( )
file_dir . makedirs ( )
s3_key = bucket . get_key ( file_key )
if file_path . exists ( ) :
    file_data = file_path . bytes ( )
    file_md5 , file_md5_64 = s3_key . get_md5_from_hexdigest ( hashlib . md5 ( file_data ) . hexdigest ( ) )
    # Check the hash .
    try :
        s3_md5 = s3_key . etag . replace ( '"' , '' )
    except KeyError :
        pass
    else :
        if s3_md5 == file_md5 :
            info ( 'Hash is the same. Skipping %s' % file_path )
            return
        elif not force : # Check if file on S3 is older than local file .
            s3_datetime = datetime . datetime ( * time . strptime ( s3_key . last_modified , '%a, %d %b %Y %H:%M:%S %Z' ) [ 0 : 6 ] )
            local_datetime = datetime . datetime . utcfromtimestamp ( file_path . stat ( ) . st_mtime )
            if s3_datetime < local_datetime :
                info ( "File at %s is less recent than the local version." % ( file_key ) )
                return
# If it is newer , let ' s process and upload
info ( "Downloading %s..." % ( file_key ) )
try :
    with open ( file_path , 'w' ) as fo :
        s3_key . get_contents_to_file ( fo )
except Exception as e :
    error ( "Failed: %s" % e )
    raise


signature:
def create_ical ( request , slug ) :
    """Creates an ical . ics file for an event using python - card - me ."""

implementation:
event = get_object_or_404 ( Event , slug = slug )
# convert dates to datetimes .
# when we change code to datetimes , we won ' t have to do this .
start = event . start_date
start = datetime . datetime ( start . year , start . month , start . day )
if event . end_date :
    end = event . end_date
    end = datetime . datetime ( end . year , end . month , end . day )
else :
    end = start
cal = card_me . iCalendar ( )
cal . add ( 'method' ) . value = 'PUBLISH'
vevent = cal . add ( 'vevent' )
vevent . add ( 'dtstart' ) . value = start
vevent . add ( 'dtend' ) . value = end
vevent . add ( 'dtstamp' ) . value = datetime . datetime . now ( )
vevent . add ( 'summary' ) . value = event . name
response = HttpResponse ( cal . serialize ( ) , content_type = 'text/calendar' )
response [ 'Filename' ] = 'filename.ics'
response [ 'Content-Disposition' ] = 'attachment; filename=filename.ics'
return response


signature:
def event_all_comments_list ( request , slug ) :
    """Returns a list view of all comments for a given event .
 Combines event comments and update comments in one list ."""

implementation:
event = get_object_or_404 ( Event , slug = slug )
comments = event . all_comments
page = int ( request . GET . get ( 'page' , 99999 ) )
# feed empty page by default to push to last page
is_paginated = False
if comments :
    paginator = Paginator ( comments , 50 )
    # Show 50 comments per page
    try :
        comments = paginator . page ( page )
    except EmptyPage : # If page is out of range ( e . g . 9999 ) , deliver last page of results .
        comments = paginator . page ( paginator . num_pages )
    is_paginated = comments . has_other_pages ( )
return render ( request , 'happenings/event_comments.html' , { "event" : event , "comment_list" : comments , "object_list" : comments , "page_obj" : comments , "page" : page , "is_paginated" : is_paginated , "key" : key } )


signature:
def event_update_list ( request , slug ) :
    """Returns a list view of updates for a given event .
 If the event is over , it will be in chronological order .
 If the event is upcoming or still going ,
 it will be in reverse chronological order ."""

implementation:
event = get_object_or_404 ( Event , slug = slug )
updates = Update . objects . filter ( event__slug = slug )
if event . recently_ended ( ) : # if the event is over , use chronological order
    updates = updates . order_by ( 'id' )
else : # if not , use reverse chronological
    updates = updates . order_by ( '-id' )
return render ( request , 'happenings/updates/update_list.html' , { 'event' : event , 'object_list' : updates , } )


signature:
def video_list ( request , slug ) :
    """Displays list of videos for given event ."""

implementation:
event = get_object_or_404 ( Event , slug = slug )
return render ( request , 'video/video_list.html' , { 'event' : event , 'video_list' : event . eventvideo_set . all ( ) } )


signature:
def add_event ( request ) :
    """Public form to add an event ."""

implementation:
form = AddEventForm ( request . POST or None )
if form . is_valid ( ) :
    instance = form . save ( commit = False )
    instance . sites = settings . SITE_ID
    instance . submitted_by = request . user
    instance . approved = True
    instance . slug = slugify ( instance . name )
    instance . save ( )
    messages . success ( request , 'Your event has been added.' )
    return HttpResponseRedirect ( reverse ( 'events_index' ) )
return render ( request , 'happenings/event_form.html' , { 'form' : form , 'form_title' : 'Add an event' } )


signature:
def add_memory ( request , slug ) :
    """Adds a memory to an event ."""

implementation:
event = get_object_or_404 ( Event , slug = slug )
form = MemoryForm ( request . POST or None , request . FILES or None )
if form . is_valid ( ) :
    instance = form . save ( commit = False )
    instance . user = request . user
    instance . event = event
    instance . save ( )
    msg = "Your thoughts were added. "
    if request . FILES :
        photo_list = request . FILES . getlist ( 'photos' )
        photo_count = len ( photo_list )
        for upload_file in photo_list :
            process_upload ( upload_file , instance , form , event , request )
        if photo_count > 1 :
            msg += "{} images were added and should appear soon." . format ( photo_count )
        else :
            msg += "{} image was added and should appear soon." . format ( photo_count )
    messages . success ( request , msg )
    return HttpResponseRedirect ( '../' )
return render ( request , 'happenings/add_memories.html' , { 'form' : form , 'event' : event } )


signature:
def process_upload ( upload_file , instance , form , event , request ) :
    """Helper function that actually processes and saves the upload ( s ) .
 Segregated out for readability ."""

implementation:
caption = form . cleaned_data . get ( 'caption' )
upload_name = upload_file . name . lower ( )
if upload_name . endswith ( '.jpg' ) or upload_name . endswith ( '.jpeg' ) :
    try :
        upload = Image ( event = event , image = upload_file , caption = caption , )
        upload . save ( )
        instance . photos . add ( upload )
    except Exception as error :
        messages . error ( request , 'Error saving image: {}.' . format ( error ) )


signature:
def _get_search_path ( main_file_dir , sys_path ) :
    '''Find the parent python path that contains the _ _ main _ _ ' s file directory
 : param main _ file _ dir : _ _ main _ _ ' s file directory
 : param sys _ path : paths list to match directory against ( like sys . path )'''

implementation:
# List to gather candidate parent paths
paths = [ ]
# look for paths containing the directory
for pth in sys_path : # convert relative path to absolute
    pth = path . abspath ( pth )
    # filter out _ _ main _ _ ' s file directory , it will be in the sys . path
    # filter in parent paths containing the package
    if ( pth != main_file_dir and pth == path . commonprefix ( ( pth , main_file_dir ) ) ) :
        paths . append ( pth )
# check if we have results
if paths : # we found candidates , look for the largest ( closest ) parent search path
    paths . sort ( )
    return paths [ - 1 ]


signature:
def _try_search_paths ( main_globals ) :
    '''Try different strategies to found the path containing the _ _ main _ _ ' s file .
 Will try strategies , in the following order :
 1 . Building file ' s path with PWD env var .
 2 . Building file ' s path from absolute file ' s path .
 3 . Buidling file ' s path from real file ' s path .
 : param main _ globals : globals dictionary in _ _ main _ _'''

implementation:
# try with abspath
fl = main_globals [ '__file__' ]
search_path = None
if not path . isabs ( fl ) and os . getenv ( 'PWD' ) : # Build absolute path from PWD if possible
    cwd_fl = path . abspath ( path . join ( os . getenv ( 'PWD' ) , fl ) )
    main_dir = path . dirname ( cwd_fl )
    search_path = _get_search_path ( main_dir , sys . path )
if not search_path : # try absolute strategy ( will fail on some symlinks configs )
    main_dir = path . dirname ( path . abspath ( fl ) )
    search_path = _get_search_path ( main_dir , sys . path )
if not search_path : # try real path strategy
    main_dir = path . dirname ( path . realpath ( fl ) )
    sys_path = [ path . realpath ( p ) for p in sys . path ]
    search_path = _get_search_path ( main_dir , sys_path )
return main_dir , search_path


signature:
def _solve_pkg ( main_globals ) :
    '''Find parent python path of _ _ main _ _ . From there solve the package
 containing _ _ main _ _ , import it and set _ _ package _ _ variable .
 : param main _ globals : globals dictionary in _ _ main _ _'''

implementation:
# find _ _ main _ _ ' s file directory and search path
main_dir , search_path = _try_search_paths ( main_globals )
if not search_path :
    _log_debug ( 'Could not solve parent python path for %r' % main_dir )
    # no candidates for search path , return
    return
# solve package name from search path
pkg_str = path . relpath ( main_dir , search_path ) . replace ( path . sep , '.' )
# Remove wrong starting string for site - packages
site_pkgs = 'site-packages.'
if pkg_str . startswith ( site_pkgs ) :
    pkg_str = pkg_str [ len ( site_pkgs ) : ]
assert pkg_str
_log_debug ( 'pkg_str=%r' % pkg_str )
# import the package in order to set _ _ package _ _ value later
try :
    if '__init__.py' in main_globals [ '__file__' ] :
        _log_debug ( '__init__ script. This module is its own package' )
        # The _ _ main _ _ is _ _ init _ _ . py = > its own package
        # If we treat it as a normal module it would be imported twice
        # So we simply reuse it
        sys . modules [ pkg_str ] = sys . modules [ '__main__' ]
        # We need to set _ _ path _ _ because its needed for
        # relative importing
        sys . modules [ pkg_str ] . __path__ = [ main_dir ]
        # We need to import parent package , something that would
        # happen automatically in non - faked import
        parent_pkg_str = '.' . join ( pkg_str . split ( '.' ) [ : - 1 ] )
        if parent_pkg_str :
            importlib . import_module ( parent_pkg_str )
    else :
        _log_debug ( 'Importing package %r' % pkg_str )
        # we need to import the package to be available
        importlib . import_module ( pkg_str )
    # finally enable relative import
    main_globals [ '__package__' ] = pkg_str
    return pkg_str
except ImportError as e : # In many situations we won ' t care if it fails , simply report error
# main will fail anyway if finds an explicit relative import
    _print_exc ( e )


signature:
def _log_debug ( msg ) :
    '''Log at debug level
 : param msg : message to log'''

implementation:
if _log_level <= DEBUG :
    if _log_level == TRACE :
        traceback . print_stack ( )
    _log ( msg )


signature:
def init ( log_level = ERROR ) :
    '''Enables explicit relative import in sub - modules when ran as _ _ main _ _
 : param log _ level : module ' s inner logger level ( equivalent to logging pkg )'''

implementation:
global _initialized
if _initialized :
    return
else :
    _initialized = True
# find caller ' s frame
frame = currentframe ( )
# go 1 frame back to find who imported us
frame = frame . f_back
_init ( frame , log_level )


signature:
def _init ( frame , log_level = ERROR ) :
    '''Enables explicit relative import in sub - modules when ran as _ _ main _ _
 : param log _ level : module ' s inner logger level ( equivalent to logging pkg )'''

implementation:
global _log_level
_log_level = log_level
# now we have access to the module globals
main_globals = frame . f_globals
# If _ _ package _ _ set or it isn ' t the _ _ main _ _ , stop and return .
# ( in some cases relative _ import could be called once from outside
# _ _ main _ _ if it was not called in _ _ main _ _ )
# ( also a reload of relative _ import could trigger this function )
pkg = main_globals . get ( '__package__' )
file_ = main_globals . get ( '__file__' )
if pkg or not file_ :
    _log_debug ( 'Package solved or init was called from interactive ' 'console. __package__=%r, __file__=%r' % ( pkg , file_ ) )
    return
try :
    _solve_pkg ( main_globals )
except Exception as e :
    _print_exc ( e )


signature:
def curve_fit_unscaled ( * args , ** kwargs ) :
    """Use the reduced chi square to unscale : mod : ` scipy ` ' s scaled : func : ` scipy . optimize . curve _ fit ` . * \ * args * and * \ * \ * kwargs * are passed through to : func : ` scipy . optimize . curve _ fit ` . The tuple * popt , pcov , chisq _ red * is returned , where * popt * is the optimal values for the parameters , * pcov * is the estimated covariance of * popt * , and * chisq _ red * is the reduced chi square . See http : / / docs . scipy . org / doc / scipy - 0.15.1 / reference / generated / scipy . optimize . curve _ fit . html ."""

implementation:
# Extract verbosity
verbose = kwargs . pop ( 'verbose' , False )
# Do initial fit
popt , pcov = _spopt . curve_fit ( * args , ** kwargs )
# Expand positional arguments
func = args [ 0 ]
x = args [ 1 ]
y = args [ 2 ]
ddof = len ( popt )
# Try to use sigma to unscale pcov
try :
    sigma = kwargs [ 'sigma' ]
    if sigma is None :
        sigma = _np . ones ( len ( y ) )
    # Get reduced chi - square
    y_expect = func ( x , * popt )
    chisq_red = _chisquare ( y , y_expect , sigma , ddof , verbose = verbose )
    # Correct scaled covariance matrix
    pcov = pcov / chisq_red
    return popt , pcov , chisq_red
except ValueError :
    print ( 'hello' )


signature:
def fitimageslice ( img , res_x , res_y , xslice , yslice , avg_e_func = None , h5file = None , plot = False ) :
    """Fits a gaussian to a slice of an image * img * specified by * xslice * x - coordinates and * yslice * y - coordinates . * res _ x * and * res _ y * specify image resolution in x and y . * avg _ e _ func * is a function that returns the energy of the image as a function of x . It should have the form :
 * avg _ e _ func ( x _ 1 , x _ 2 , h5file , res _ y ) *
 Fits a gaussian to a slice of an image .
 Parameters
 img : array
 Image to be fitted .
 res _ x : int
 Image resolution in : math : ` x ` .
 res _ y : int
 Image resolution in : math : ` y ` .
 xslice : ( int , int )
 Slice coordinates in : math : ` x `
 yslice : ( int , int )
 Slice coordinates in : math : ` y `
 avg _ e _ func : function
 Of the form * avg _ e _ func ( x _ 1 , x _ 2 , h5file , res _ y ) * , returns the energy of the image as a function of : math : ` x ` .
 h5file : h5file
 Instance from dataset .
 plot : boolean
 Whether to plot or not ."""

implementation:
# Extract start and end values
# ( NOT necessarily indices ! )
x_start = xslice [ 0 ]
x_end = xslice [ 1 ]
y_start = yslice [ 0 ]
y_end = yslice [ 1 ]
# Round to pixel edges . Pixel edges in
# px units are at 0.5 , 1.5 , 2.5 , etc .
y_low = _np . round ( y_start - 0.5 ) + 0.5
y_high = _np . round ( y_end - 0.5 ) + 0.5
# Take a strip between edges
y_px = linspacestep ( 1 , img . shape [ 0 ] )
y_bool = _np . logical_and ( y_low < y_px , y_px < y_high )
strip = img [ y_bool , x_start : x_end ]
# Sum over the strip to get an average
histdata = _np . sum ( strip , 0 )
xbins = len ( histdata )
x = _np . linspace ( 1 , xbins , xbins ) * res_x
# Fit with a Gaussian to find spot size
# plotbool = True
# plotbool = False
# varbool = False
varbool = True
gaussout = _sp . GaussResults ( x , histdata , sigma_y = _np . ones ( xbins ) , variance = varbool , background = True , p0 = [ 16000 , 0.003 , 1e-6 , 0 ] )
if avg_e_func is not None : # Get average energy of strip
# Sum to get relative counts of pixels
    relcounts = _np . sum ( strip , 1 ) / _np . float ( _np . sum ( strip ) )
    # Integrate each pixel strip
    Eavg = 0
    for i , val in enumerate ( linspacestep ( y_low , y_high - 1 ) ) :
        Eavg = Eavg + avg_e_func ( val , val + 1 , h5file , res_y ) * relcounts [ i ]
    return Eavg , gaussout
else :
    return gaussout


signature:
def encode ( python_object , indent = None , large_object = False ) :
    """: returns : a JSON - representation of the object"""

implementation:
# sorted keys is easier to read ; however , Python - 2.7.2 does not have this feature
kwargs = dict ( indent = indent )
if can_dumps_sort_keys ( ) :
    kwargs . update ( sort_keys = True )
try :
    if large_object :
        out = GreenletFriendlyStringIO ( )
        json . dump ( python_object , out , ** kwargs )
        return out . getvalue ( )
    else :
        return json . dumps ( python_object , ** kwargs )
except Exception :
    logger . exception ( )
    raise EncodeError ( 'Cannot encode {!r}' , python_object )


signature:
def __register_library ( self , module_name : str , attr : str , fallback : str = None ) :
    """Inserts Interpreter Library of imports into sketch in a very non - consensual way"""

implementation:
# Import the module Named in the string
try :
    module = importlib . import_module ( module_name )
# If module is not found it checks if an alternative is is listed
# If it is then it substitutes it , just so that the code can run
except ImportError :
    if fallback is not None :
        module = importlib . import_module ( fallback )
        self . __logger . warn ( module_name + " not available: Replaced with " + fallback )
    else :
        self . __logger . warn ( module_name + " not available: No Replacement Specified" )
# Cram the module into the _ _ sketch in the form of module - > " attr "
# AKA the same as ` import module as attr `
if not attr in dir ( self . __sketch ) :
    setattr ( self . __sketch , attr , module )
else :
    self . __logger . warn ( attr + " could not be imported as it's label is already used in the sketch" )


signature:
def set_moments ( self , sx , sxp , sxxp ) :
    """Sets the beam moments directly .
 Parameters
 sx : float
 Beam moment where : math : ` \\ text { sx } ^ 2 = \\ langle x ^ 2 \\ rangle ` .
 sxp : float
 Beam moment where : math : ` \\ text { sxp } ^ 2 = \\ langle x ' ^ 2 \\ rangle ` .
 sxxp : float
 Beam moment where : math : ` \\ text { sxxp } = \\ langle x x ' \\ rangle ` ."""

implementation:
self . _sx = sx
self . _sxp = sxp
self . _sxxp = sxxp
emit = _np . sqrt ( sx ** 2 * sxp ** 2 - sxxp ** 2 )
self . _store_emit ( emit = emit )


signature:
def set_Courant_Snyder ( self , beta , alpha , emit = None , emit_n = None ) :
    """Sets the beam moments indirectly using Courant - Snyder parameters .
 Parameters
 beta : float
 Courant - Snyder parameter : math : ` \\ beta ` .
 alpha : float
 Courant - Snyder parameter : math : ` \\ alpha ` .
 emit : float
 Beam emittance : math : ` \\ epsilon ` .
 emit _ n : float
 Normalized beam emittance : math : ` \\ gamma \\ epsilon ` ."""

implementation:
self . _store_emit ( emit = emit , emit_n = emit_n )
self . _sx = _np . sqrt ( beta * self . emit )
self . _sxp = _np . sqrt ( ( 1 + alpha ** 2 ) / beta * self . emit )
self . _sxxp = - alpha * self . emit


signature:
def beta ( self ) :
    """Courant - Snyder parameter : math : ` \\ beta ` ."""

implementation:
beta = _np . sqrt ( self . sx ) / self . emit
return beta


signature:
def normalize_slice ( slice_obj , length ) :
    """Given a slice object , return appropriate values for use in the range function
 : param slice _ obj : The slice object or integer provided in the ` [ ] ` notation
 : param length : For negative indexing we need to know the max length of the object ."""

implementation:
if isinstance ( slice_obj , slice ) :
    start , stop , step = slice_obj . start , slice_obj . stop , slice_obj . step
    if start is None :
        start = 0
    if stop is None :
        stop = length
    if step is None :
        step = 1
    if start < 0 :
        start += length
    if stop < 0 :
        stop += length
elif isinstance ( slice_obj , int ) :
    start = slice_obj
    if start < 0 :
        start += length
    stop = start + 1
    step = 1
else :
    raise TypeError
if ( 0 <= start <= length ) and ( 0 <= stop <= length ) :
    return start , stop , step
raise IndexError


signature:
def error ( self , error_code , value , ** kwargs ) :
    """Helper to add error to messages field . It fills placeholder with extra call parameters
 or values from message _ value map .
 : param error _ code : Error code to use
 : rparam error _ code : str
 : param value : Value checked
 : param kwargs : Map of values to use in placeholders"""

implementation:
code = self . error_code_map . get ( error_code , error_code )
try :
    message = Template ( self . error_messages [ code ] )
except KeyError :
    message = Template ( self . error_messages [ error_code ] )
placeholders = { "value" : self . hidden_value if self . hidden else value }
placeholders . update ( kwargs )
placeholders . update ( self . message_values )
self . messages [ code ] = message . safe_substitute ( placeholders )


signature:
def copy ( src , dst ) :
    """File copy that support compress and decompress of zip files"""

implementation:
( szip , dzip ) = ( src . endswith ( ".zip" ) , dst . endswith ( ".zip" ) )
logging . info ( "Copy: %s => %s" % ( src , dst ) )
if szip and dzip : # If both zipped , we can simply use copy
    shutil . copy2 ( src , dst )
elif szip :
    with zipfile . ZipFile ( src , mode = 'r' ) as z :
        tmpdir = tempfile . mkdtemp ( )
        try :
            z . extractall ( tmpdir )
            if len ( z . namelist ( ) ) != 1 :
                raise RuntimeError ( "The zip file '%s' should only have one " "compressed file" % src )
            tmpfile = join ( tmpdir , z . namelist ( ) [ 0 ] )
            try :
                os . remove ( dst )
            except OSError :
                pass
            shutil . move ( tmpfile , dst )
        finally :
            shutil . rmtree ( tmpdir , ignore_errors = True )
elif dzip :
    with zipfile . ZipFile ( dst , mode = 'w' , compression = ZIP_DEFLATED ) as z :
        z . write ( src , arcname = basename ( src ) )
else : # None of them are zipped
    shutil . copy2 ( src , dst )


signature:
def apply_changesets ( args , changesets , catalog ) :
    """Apply to the ' catalog ' the changesets in the metafile list ' changesets '"""

implementation:
tmpdir = tempfile . mkdtemp ( )
tmp_patch = join ( tmpdir , "tmp.patch" )
tmp_lcat = join ( tmpdir , "tmp.lcat" )
for node in changesets :
    remove ( tmp_patch )
    copy ( node . mfile [ 'changeset' ] [ 'filename' ] , tmp_patch )
    logging . info ( "mv %s %s" % ( catalog , tmp_lcat ) )
    shutil . move ( catalog , tmp_lcat )
    cmd = args . patch_cmd . replace ( "$in1" , tmp_lcat ) . replace ( "$patch" , tmp_patch ) . replace ( "$out" , catalog )
    logging . info ( "Patch: %s" % cmd )
    subprocess . check_call ( cmd , shell = True )
shutil . rmtree ( tmpdir , ignore_errors = True )


signature:
def clean ( self ) :
    """Validate that an event with this name on this date does not exist ."""

implementation:
cleaned = super ( EventForm , self ) . clean ( )
if Event . objects . filter ( name = cleaned [ 'name' ] , start_date = cleaned [ 'start_date' ] ) . count ( ) :
    raise forms . ValidationError ( u'This event appears to be in the database already.' )
return cleaned


signature:
def loop_in_background ( interval , callback ) :
    """When entering the context , spawns a greenlet that sleeps for ` interval ` seconds between ` callback ` executions .
 When leaving the context stops the greenlet .
 The yielded object is the ` GeventLoop ` object so the loop can be stopped from within the context .
 For example :
 with loop _ in _ background ( 60.0 , purge _ cache ) as purge _ cache _ job :
 if should _ stop _ cache ( ) :
 purge _ cache _ job . stop ( )"""

implementation:
loop = GeventLoop ( interval , callback )
loop . start ( )
try :
    yield loop
finally :
    if loop . has_started ( ) :
        loop . stop ( )


signature:
def _loop ( self ) :
    """Main loop - used internally ."""

implementation:
while True :
    try :
        with uncaught_greenlet_exception_context ( ) :
            self . _loop_callback ( )
    except gevent . GreenletExit :
        break
    if self . _stop_event . wait ( self . _interval ) :
        break
self . _clear ( )


signature:
def start ( self ) :
    """Starts the loop . Calling a running loop is an error ."""

implementation:
assert not self . has_started ( ) , "called start() on an active GeventLoop"
self . _stop_event = Event ( )
# note that we don ' t use safe _ greenlets . spawn because we take care of it in _ loop by ourselves
self . _greenlet = gevent . spawn ( self . _loop )


signature:
def stop ( self , timeout = None ) :
    """Stops a running loop and waits for it to end if timeout is set . Calling a non - running loop is an error .
 : param timeout : time ( in seconds ) to wait for the loop to end after signalling it . ` ` None ` ` is to block till it
 ends .
 : return : True if the loop stopped , False if still stopping ."""

implementation:
assert self . has_started ( ) , "called stop() on a non-active GeventLoop"
greenlet = self . _greenlet if gevent . getcurrent ( ) != self . _greenlet else None
self . _stop_event . set ( )
if greenlet is not None and timeout is not None :
    greenlet . join ( timeout )
    return greenlet . ready
else :
    return True


signature:
def kill ( self ) :
    """Kills the running loop and waits till it gets killed ."""

implementation:
assert self . has_started ( ) , "called kill() on a non-active GeventLoop"
self . _stop_event . set ( )
self . _greenlet . kill ( )
self . _clear ( )


signature:
def NonUniformImage ( x , y , z , ax = None , fig = None , cmap = None , alpha = None , scalex = True , scaley = True , add_cbar = True , ** kwargs ) :
    """Used to plot a set of coordinates .
 Parameters
 x , y : : class : ` numpy . ndarray `
 1 - D ndarrays of lengths N and M , respectively , specifying pixel centers
 z : : class : ` numpy . ndarray `
 An ( M , N ) ndarray or masked array of values to be colormapped , or a ( M , N , 3 ) RGB array , or a ( M , N , 4 ) RGBA array .
 ax : : class : ` matplotlib . axes . Axes ` , optional
 The axis to plot to .
 fig : : class : ` matplotlib . figure . Figure ` , optional
 The figure to plot to .
 cmap : : class : ` matplotlib . colors . Colormap ` , optional
 The colormap to use .
 alpha : float , optional
 The transparency to use .
 scalex : bool , optional
 To set the x limits to available data
 scaley : bool , optional
 To set the y limits to available data
 add _ cbar : bool , optional
 Whether ot add a colorbar or not .
 Returns
 img : : class : ` matplotlib . image . NonUniformImage `
 Object representing the : class : ` matplotlib . image . NonUniformImage ` ."""

implementation:
if ax is None and fig is None :
    fig , ax = _setup_axes ( )
elif ax is None :
    ax = fig . gca ( )
elif fig is None :
    fig = ax . get_figure ( )
norm = kwargs . get ( 'norm' , None )
im = _mplim . NonUniformImage ( ax , ** kwargs )
vmin = kwargs . pop ( 'vmin' , _np . min ( z ) )
vmax = kwargs . pop ( 'vmax' , _np . max ( z ) )
# im . set _ clim ( vmin = vmin , vmax = vmax )
if cmap is not None :
    im . set_cmap ( cmap )
m = _cm . ScalarMappable ( cmap = im . get_cmap ( ) , norm = norm )
m . set_array ( z )
if add_cbar :
    cax , cb = _cb ( ax = ax , im = m , fig = fig )
if alpha is not None :
    im . set_alpha ( alpha )
im . set_data ( x , y , z )
ax . images . append ( im )
if scalex :
    xmin = min ( x )
    xmax = max ( x )
    ax . set_xlim ( xmin , xmax )
if scaley :
    ymin = min ( y )
    ymax = max ( y )
    ax . set_ylim ( ymin , ymax )
return _SI ( im = im , cb = cb , cax = cax )


signature:
def _sentence_to_interstitial_spacing ( self ) :
    """Fix common spacing errors caused by LaTeX ' s habit
 of using an inter - sentence space after any full stop ."""

implementation:
not_sentence_end_chars = [ ' ' ]
abbreviations = [ 'i.e.' , 'e.g.' , ' v.' , ' w.' , ' wh.' ]
titles = [ 'Prof.' , 'Mr.' , 'Mrs.' , 'Messrs.' , 'Mmes.' , 'Msgr.' , 'Ms.' , 'Fr.' , 'Rev.' , 'St.' , 'Dr.' , 'Lieut.' , 'Lt.' , 'Capt.' , 'Cptn.' , 'Sgt.' , 'Sjt.' , 'Gen.' , 'Hon.' , 'Cpl.' , 'L-Cpl.' , 'Pvt.' , 'Dvr.' , 'Gnr.' , 'Spr.' , 'Col.' , 'Lt-Col' , 'Lt-Gen.' , 'Mx.' ]
for abbrev in abbreviations :
    for x in not_sentence_end_chars :
        self . _str_replacement ( abbrev + x , abbrev + '\ ' )
for title in titles :
    for x in not_sentence_end_chars :
        self . _str_replacement ( title + x , title + '~' )


signature:
def _hyphens_to_dashes ( self ) :
    """Transform hyphens to various kinds of dashes"""

implementation:
problematic_hyphens = [ ( r'-([.,!)])' , r'---\1' ) , ( r'(?<=\d)-(?=\d)' , '--' ) , ( r'(?<=\s)-(?=\s)' , '---' ) ]
for problem_case in problematic_hyphens :
    self . _regex_replacement ( * problem_case )


signature:
def _str_replacement ( self , target , replacement ) :
    """Replace target with replacement"""

implementation: self . data = self . data . replace ( target , replacement )


signature:
def _regex_replacement ( self , target , replacement ) :
    """Regex substitute target with replacement"""

implementation:
match = re . compile ( target )
self . data = match . sub ( replacement , self . data )


signature:
def sphinx_make ( * targets ) :
    """Call the Sphinx Makefile with the specified targets .
 ` options . paved . docs . path ` : the path to the Sphinx folder ( where the Makefile resides ) ."""

implementation: sh ( 'make %s' % ' ' . join ( targets ) , cwd = options . paved . docs . path )


signature:
def rsync_docs ( ) :
    """Upload the docs to a remote location via rsync .
 ` options . paved . docs . rsync _ location ` : the target location to rsync files to .
 ` options . paved . docs . path ` : the path to the Sphinx folder ( where the Makefile resides ) .
 ` options . paved . docs . build _ rel ` : the path of the documentation
 build folder , relative to ` options . paved . docs . path ` ."""

implementation:
assert options . paved . docs . rsync_location , "Please specify an rsync location in options.paved.docs.rsync_location."
sh ( 'rsync -ravz %s/ %s/' % ( path ( options . paved . docs . path ) / options . paved . docs . build_rel , options . paved . docs . rsync_location ) )


signature:
def ghpages ( ) :
    '''Push Sphinx docs to github _ gh - pages branch .
 1 . Create file . nojekyll
 2 . Push the branch to origin / gh - pages
 after committing using ghp - import _
 Requirements :
 - easy _ install ghp - import
 Options :
 - ` options . paved . docs . * ` is not used
 - ` options . sphinx . docroot ` is used ( default = docs )
 - ` options . sphinx . builddir ` is used ( default = . build )
 . . warning : :
 This will DESTROY your gh - pages branch .
 If you love it , you ' ll want to take backups
 before playing with this . This script assumes
 that gh - pages is 100 % derivative . You should
 never edit files in your gh - pages branch by hand
 if you ' re using this script because you will
 lose your work .
 . . _ github : https : / / github . com
 . . _ ghp - import : https : / / github . com / davisp / ghp - import'''

implementation:
# copy from paver
opts = options
docroot = path ( opts . get ( 'docroot' , 'docs' ) )
if not docroot . exists ( ) :
    raise BuildFailure ( "Sphinx documentation root (%s) does not exist." % docroot )
builddir = docroot / opts . get ( "builddir" , ".build" )
# end of copy
builddir = builddir / 'html'
if not builddir . exists ( ) :
    raise BuildFailure ( "Sphinx build directory (%s) does not exist." % builddir )
nojekyll = path ( builddir ) / '.nojekyll'
nojekyll . touch ( )
sh ( 'ghp-import -p %s' % ( builddir ) )


signature:
def showhtml ( ) :
    """Open your web browser and display the generated html documentation ."""

implementation:
import webbrowser
# copy from paver
opts = options
docroot = path ( opts . get ( 'docroot' , 'docs' ) )
if not docroot . exists ( ) :
    raise BuildFailure ( "Sphinx documentation root (%s) does not exist." % docroot )
builddir = docroot / opts . get ( "builddir" , ".build" )
# end of copy
builddir = builddir / 'html'
if not builddir . exists ( ) :
    raise BuildFailure ( "Sphinx build directory (%s) does not exist." % builddir )
webbrowser . open ( builddir / 'index.html' )


signature:
def setup_figure ( rows = 1 , cols = 1 , ** kwargs ) :
    """Sets up a figure with a number of rows ( * rows * ) and columns ( * cols * ) , * \ * \ * kwargs * passes through to : class : ` matplotlib . figure . Figure ` .
 . . versionchanged : : 1.3
 Supports * \ * \ * kwargs * pass - through to : class : ` matplotlib . figure . Figure ` .
 . . versionchanged : : 1.2
 Changed * gridspec _ x * to * rows * , * gridspec _ y * to * cols * , added * figsize * control .
 Parameters
 rows : int
 Number of rows to create .
 cols : int
 Number of columns to create .
 Returns
 fig : : class : ` matplotlib . figure . Figure `
 The figure .
 gs : : class : ` matplotlib . gridspec . GridSpec `
 Instance with * gridspec _ x * rows and * gridspec _ y * columns"""

implementation:
fig = _plt . figure ( ** kwargs )
gs = _gridspec . GridSpec ( rows , cols )
return fig , gs


signature:
def guess ( self , * args ) :
    self . _validate ( )
    """guess ( ) allows a guess to be made . Before the guess is made , the method
 checks to see if the game has been won , lost , or there are no tries
 remaining . It then creates a return object stating the number of bulls
 ( direct matches ) , cows ( indirect matches ) , an analysis of the guess ( a
 list of analysis objects ) , and a status .
 : param args : any number of integers ( or string representations of integers )
 to the number of Digits in the answer ; i . e . in normal mode , there would be
 a DigitWord to guess of 4 digits , so guess would expect guess ( 1 , 2 , 3 , 4)
 and a shorter ( guess ( 1 , 2 ) ) or longer ( guess ( 1 , 2 , 3 , 4 , 5 ) ) sequence will
 raise an exception .
 : return : a JSON object containing the analysis of the guess :
 " cows " : { " type " : " integer " } ,
 " bulls " : { " type " : " integer " } ,
 " analysis " : { " type " : " array of DigitWordAnalysis " } ,
 " status " : { " type " : " string " }"""

implementation:
logging . debug ( "guess called." )
logging . debug ( "Validating game object" )
self . _validate ( op = "guess" )
logging . debug ( "Building return object" )
_return_results = { "cows" : None , "bulls" : None , "analysis" : [ ] , "status" : "" }
logging . debug ( "Check if game already won, lost, or too many tries." )
if self . _game . status == GameObject . GAME_WON :
    _return_results [ "message" ] = self . _start_again ( "You already won!" )
elif self . _game . status == GameObject . GAME_LOST :
    _return_results [ "message" ] = self . _start_again ( "You have made too many guesses, you lost!" )
elif self . _game . guesses_remaining < 1 :
    _return_results [ "message" ] = self . _start_again ( "You have run out of tries, sorry!" )
else :
    logging . debug ( "Creating a DigitWord for the guess." )
    _mode = self . _load_mode ( self . _game . mode )
    guess = DigitWord ( * args , wordtype = _mode . digit_type )
    logging . debug ( "Validating guess." )
    self . _game . guesses_remaining -= 1
    self . _game . guesses_made += 1
    logging . debug ( "Initializing return object." )
    _return_results [ "analysis" ] = [ ]
    _return_results [ "cows" ] = 0
    _return_results [ "bulls" ] = 0
    logging . debug ( "Asking the underlying GameObject to compare itself to the guess." )
    for i in self . _game . answer . compare ( guess ) :
        logging . debug ( "Iteration of guesses. Processing guess {}" . format ( i . index ) )
        if i . match is True :
            logging . debug ( "Bull found. +1" )
            _return_results [ "bulls" ] += 1
        elif i . in_word is True :
            logging . debug ( "Cow found. +1" )
            _return_results [ "cows" ] += 1
        logging . debug ( "Add analysis to return object" )
        _return_results [ "analysis" ] . append ( i . get_object ( ) )
    logging . debug ( "Checking if game won or lost." )
    if _return_results [ "bulls" ] == len ( self . _game . answer . word ) :
        logging . debug ( "Game was won." )
        self . _game . status = GameObject . GAME_WON
        self . _game . guesses_remaining = 0
        _return_results [ "message" ] = "Well done! You won the game with your " "answers {}" . format ( self . _game . answer_str )
    elif self . _game . guesses_remaining < 1 :
        logging . debug ( "Game was lost." )
        self . _game . status = GameObject . GAME_LOST
        _return_results [ "message" ] = "Sorry, you lost! The correct answer was " "{}" . format ( self . _game . answer_str )
    _return_results [ "status" ] = self . _game . status
logging . debug ( "Returning results." )
return _return_results


signature:
def _start_again ( self , message = None ) :
    """Simple method to form a start again message and give the answer in readable form ."""

implementation:
logging . debug ( "Start again message delivered: {}" . format ( message ) )
the_answer = self . _game . answer_str
return "{0} The correct answer was {1}. Please start a new game." . format ( message , the_answer )


signature:
def attachments ( value , obj , width = WIDTH ) :
    """Parse the copy inside ` ` value ` ` and look for shortcodes in this format : :
 < p > Here ' s an attachment < / p >
 < p > [ attachment 1 ] < / p >
 Replace the shortcode with a full image , video or audio element , or download link
 : param obj : The object against which attachments are saved
 : param width : The width of images or audio / video tags ( defaults to the ` ` ATTACHMENT _ WIDTH ` ` SETTING )"""

implementation:
match = ATTACHMENT_REGEX . search ( value )
safe = isinstance ( value , ( SafeString , SafeUnicode ) )
while not match is None and match . end ( ) <= len ( value ) :
    start = match . start ( )
    end = match . end ( )
    groups = match . groups ( )
    if len ( groups ) > 0 :
        index = groups [ 0 ]
        options = None
        if len ( groups ) > 1 :
            options = groups [ 1 ]
            if options :
                options = options . strip ( )
                if options :
                    try :
                        options = split ( smart_str ( options ) )
                    except :
                        options = None
        args = [ ]
        kwargs = { 'width' : width }
        if options :
            for option in options :
                key , equals , val = option . partition ( '=' )
                if equals != '=' :
                    if key and not val :
                        args . append ( key )
                    continue
                kwargs [ key ] = val
        try :
            if isinstance ( obj , dict ) :
                inner = Attachment ( ** obj [ 'attachments__attachment' ] [ int ( index ) - 1 ] ) . render ( * args , ** kwargs )
            else :
                inner = obj . attachments . all ( ) [ int ( index ) - 1 ] . render ( * args , ** kwargs )
        except :
            inner = ''
    else :
        inner = ''
    value = value [ : start ] + inner + value [ end : ]
    match = ATTACHMENT_REGEX . search ( value , start + len ( inner ) )
if safe :
    return mark_safe ( value )
else :
    return value


signature:
def minify ( self , css ) :
    """Tries to minimize the length of CSS code passed as parameter . Returns string ."""

implementation:
css = css . replace ( "\r\n" , "\n" )
# get rid of Windows line endings , if they exist
for rule in _REPLACERS [ self . level ] :
    css = re . compile ( rule [ 0 ] , re . MULTILINE | re . UNICODE | re . DOTALL ) . sub ( rule [ 1 ] , css )
return css


signature:
def colorbar ( ax , im , fig = None , loc = "right" , size = "5%" , pad = "3%" ) :
    """Adds a polite colorbar that steals space so : func : ` matplotlib . pyplot . tight _ layout ` works nicely .
 . . versionadded : : 1.3
 Parameters
 ax : : class : ` matplotlib . axis . Axis `
 The axis to plot to .
 im : : class : ` matplotlib . image . AxesImage `
 The plotted image to use for the colorbar .
 fig : : class : ` matplotlib . figure . Figure ` , optional
 The figure to plot to .
 loc : str , optional
 The location to place the axes .
 size : str , optional
 The size to allocate for the colorbar .
 pad : str , optional
 The amount to pad the colorbar ."""

implementation:
if fig is None :
    fig = ax . get_figure ( )
# _ pdb . set _ trace ( )
if loc == "left" or loc == "right" :
    width = fig . get_figwidth ( )
    new = width * ( 1 + _pc2f ( size ) + _pc2f ( pad ) )
    _logger . debug ( 'Setting new figure width: {}' . format ( new ) )
    # fig . set _ size _ inches ( new , fig . get _ figheight ( ) , forward = True )
elif loc == "top" or loc == "bottom" :
    height = fig . get_figheight ( )
    new = height * ( 1 + _pc2f ( size ) + _pc2f ( pad ) )
    _logger . debug ( 'Setting new figure height: {}' . format ( new ) )
    # fig . set _ figheight ( fig . get _ figwidth ( ) , new , forward = True )
divider = _ag1 . make_axes_locatable ( ax )
cax = divider . append_axes ( loc , size = size , pad = pad )
return cax , _plt . colorbar ( im , cax = cax )


signature:
def BDES2K ( bdes , quad_length , energy ) :
    """Converts a quadrupole : math : ` B _ des ` into a geometric focusing strength : math : ` K ` .
 Parameters
 bdes : float
 The magnet value of : math : ` B _ des ` .
 quad _ length : float
 The length of the quadrupole in meters .
 energy : float
 The design energy of the beam in GeV .
 Returns
 K : float
 The geometric focusing strength : math : ` K ` ."""

implementation:
# Make sure everything is float
bdes = _np . float_ ( bdes )
quad_length = _np . float_ ( quad_length )
energy = _np . float_ ( energy )
Brho = energy / _np . float_ ( 0.029979 )
K = bdes / ( Brho * quad_length )
logger . log ( level = loggerlevel , msg = 'Converted BDES: {bdes}, quad length: {quad_length}, energy: {energy} to K: {K}' . format ( bdes = bdes , quad_length = quad_length , energy = energy , K = K ) )
return K


signature:
def get_or_create_index ( self , index_ratio , index_width ) :
    """Return an open file - object to the index file"""

implementation:
if not self . index_path . exists ( ) or not self . filepath . stat ( ) . st_mtime == self . index_path . stat ( ) . st_mtime :
    create_index ( self . filepath , self . index_path , index_ratio = index_ratio , index_width = index_width )
return IndexFile ( str ( self . index_path ) )


signature:
def create ( self , server ) :
    """Create the tasks on the server"""

implementation:
for chunk in self . __cut_to_size ( ) :
    server . post ( 'tasks_admin' , chunk . as_payload ( ) , replacements = { 'slug' : chunk . challenge . slug } )


signature:
def update ( self , server ) :
    """Update existing tasks on the server"""

implementation:
for chunk in self . __cut_to_size ( ) :
    server . put ( 'tasks_admin' , chunk . as_payload ( ) , replacements = { 'slug' : chunk . challenge . slug } )


signature:
def reconcile ( self , server ) :
    """Reconcile this collection with the server ."""

implementation:
if not self . challenge . exists ( server ) :
    raise Exception ( 'Challenge does not exist on server' )
existing = MapRouletteTaskCollection . from_server ( server , self . challenge )
same = [ ]
new = [ ]
changed = [ ]
deleted = [ ]
# reconcile the new tasks with the existing tasks :
for task in self . tasks : # if the task exists on the server . . .
    if task . identifier in [ existing_task . identifier for existing_task in existing . tasks ] : # and they are equal . . .
        if task == existing . get_by_identifier ( task . identifier ) : # add to ' same ' list
            same . append ( task )
            # if they are not equal , add to ' changed ' list
        else :
            changed . append ( task )
    # if the task does not exist on the server , add to ' new ' list
    else :
        new . append ( task )
# next , check for tasks on the server that don ' t exist in the new collection . . .
for task in existing . tasks :
    if task . identifier not in [ task . identifier for task in self . tasks ] : # . . . and add those to the ' deleted ' list .
        deleted . append ( task )
# update the server with new , changed , and deleted tasks
if new :
    newCollection = MapRouletteTaskCollection ( self . challenge , tasks = new )
    newCollection . create ( server )
if changed :
    changedCollection = MapRouletteTaskCollection ( self . challenge , tasks = changed )
    changedCollection . update ( server )
if deleted :
    deletedCollection = MapRouletteTaskCollection ( self . challenge , tasks = deleted )
    for task in deletedCollection . tasks :
        task . status = 'deleted'
    deletedCollection . update ( server )
# return same , new , changed and deleted tasks
return { 'same' : same , 'new' : new , 'changed' : changed , 'deleted' : deleted }


signature:
def yn_prompt ( msg , default = True ) :
    """Prompts the user for yes or no ."""

implementation:
ret = custom_prompt ( msg , [ "y" , "n" ] , "y" if default else "n" )
if ret == "y" :
    return True
return False


signature:
def custom_prompt ( msg , options , default ) :
    """Prompts the user with custom options ."""

implementation:
formatted_options = [ x . upper ( ) if x == default else x . lower ( ) for x in options ]
sure = input ( "{0} [{1}]: " . format ( msg , "/" . join ( formatted_options ) ) )
if len ( sure ) == 0 :
    return default
for option in options :
    if sure . upper ( ) == option . upper ( ) :
        return option
return default


signature:
def read ( args ) :
    """Reading the configure file and adds non - existing attributes to ' args '"""

implementation:
if args . config_file is None or not isfile ( args . config_file ) :
    return
logging . info ( "Reading configure file: %s" % args . config_file )
config = cparser . ConfigParser ( )
config . read ( args . config_file )
if not config . has_section ( 'lrcloud' ) :
    raise RuntimeError ( "Configure file has no [lrcloud] section!" )
for ( name , value ) in config . items ( 'lrcloud' ) :
    if value == "True" :
        value = True
    elif value == "False" :
        value = False
    if getattr ( args , name ) is None :
        setattr ( args , name , value )


signature:
def write ( args ) :
    """Writing the configure file with the attributes in ' args '"""

implementation:
logging . info ( "Writing configure file: %s" % args . config_file )
if args . config_file is None :
    return
# Let ' s add each attribute of ' args ' to the configure file
config = cparser . ConfigParser ( )
config . add_section ( "lrcloud" )
for p in [ x for x in dir ( args ) if not x . startswith ( "_" ) ] :
    if p in IGNORE_ARGS :
        continue
        # We ignore some attributes
    value = getattr ( args , p )
    if value is not None :
        config . set ( 'lrcloud' , p , str ( value ) )
with open ( args . config_file , 'w' ) as f :
    config . write ( f )


signature:
def _spawn_memcached ( sock ) :
    """Helper function for tests . Spawns a memcached process attached to sock .
 Returns Popen instance . Terminate with p . terminate ( ) .
 Note : sock parameter is not checked , and command is executed as shell .
 Use only if you trust that sock parameter . You ' ve been warned ."""

implementation:
p = subprocess . Popen ( 'memcached -s ' + sock , shell = True )
time . sleep ( 0.2 )
# memcached needs to initialize
assert p . poll ( ) is None
# make sure it ' s running
return p


signature:
def dump ( self ) :
    """Dump ( return ) a dict representation of the GameObject . This is a Python
 dict and is NOT serialized . NB : the answer ( a DigitWord object ) and the
 mode ( a GameMode object ) are converted to python objects of a list and
 dict respectively .
 : return : python < dict > of the GameObject as detailed above ."""

implementation: return { "key" : self . _key , "status" : self . _status , "ttl" : self . _ttl , "answer" : self . _answer . word , "mode" : self . _mode . dump ( ) , "guesses_made" : self . _guesses_made }


signature:
def load ( self , source = None ) :
    """Load the representation of a GameObject from a Python < dict > representing
 the game object .
 : param source : a Python < dict > as detailed above .
 : return :"""

implementation:
if not source :
    raise ValueError ( "A valid dictionary must be passed as the source_dict" )
if not isinstance ( source , dict ) :
    raise TypeError ( "A valid dictionary must be passed as the source_dict. {} given." . format ( type ( source ) ) )
required_keys = ( "key" , "status" , "ttl" , "answer" , "mode" , "guesses_made" )
if not all ( key in source for key in required_keys ) :
    raise ValueError ( "The dictionary passed is malformed: {}" . format ( source ) )
_mode = GameMode ( ** source [ "mode" ] )
self . _key = source [ "key" ]
self . _status = source [ "status" ]
self . _ttl = source [ "ttl" ]
self . _answer = DigitWord ( * source [ "answer" ] , wordtype = _mode . digit_type )
self . _mode = _mode
self . _guesses_made = source [ "guesses_made" ]


signature:
def new ( self , mode ) :
    """Create a new instance of a game . Note , a mode MUST be provided and MUST be of
 type GameMode .
 : param mode : < required >"""

implementation:
dw = DigitWord ( wordtype = mode . digit_type )
dw . random ( mode . digits )
self . _key = str ( uuid . uuid4 ( ) )
self . _status = ""
self . _ttl = 3600
self . _answer = dw
self . _mode = mode
self . _guesses_remaining = mode . guesses_allowed
self . _guesses_made = 0


signature:
def emit_measured ( self ) :
    """The beam emittance : math : ` \\ langle x x ' \\ rangle ` ."""

implementation: return _np . sqrt ( self . spotsq * self . divsq - self . xxp ** 2 )


signature:
def bump ( self , target ) :
    """Bumps the Version given a target
 The target can be either MAJOR , MINOR or PATCH"""

implementation:
if target == 'patch' :
    return Version ( self . major , self . minor , self . patch + 1 )
if target == 'minor' :
    return Version ( self . major , self . minor + 1 , 0 )
if target == 'major' :
    return Version ( self . major + 1 , 0 , 0 )
return self . clone ( )


signature:
def clone ( self ) :
    """Returns a copy of this object"""

implementation:
t = Tag ( self . version . major , self . version . minor , self . version . patch )
if self . revision is not None :
    t . revision = self . revision . clone ( )
return t


signature:
def with_revision ( self , label , number ) :
    """Returns a Tag with a given revision"""

implementation:
t = self . clone ( )
t . revision = Revision ( label , number )
return t


signature:
def parse ( s ) :
    """Parses a string into a Tag"""

implementation:
try :
    m = _regex . match ( s )
    t = Tag ( int ( m . group ( 'major' ) ) , int ( m . group ( 'minor' ) ) , int ( m . group ( 'patch' ) ) )
    return t if m . group ( 'label' ) is None else t . with_revision ( m . group ( 'label' ) , int ( m . group ( 'number' ) ) )
except AttributeError :
    return None


signature:
def yield_tag ( self , target = None , label = None ) :
    """Returns a new Tag containing the bumped target and / or the bumped label"""

implementation:
if target is None and label is None :
    raise ValueError ( '`target` and/or `label` must be specified' )
if label is None :
    return self . _yield_from_target ( target )
if target is None :
    return self . _yield_from_label ( label )
return self . _yield_from_target_and_label ( target , label )