Utility Functions

Utility functions useful in the implementation and testing of the Synapse client.

synapseclient.utils.as_url(s)

Tries to convert the input into a proper URL.

synapseclient.utils.caller_module_name(current_frame)
Parameters:current_frame – use inspect.currentframe().
Returns:the name of the module calling the function, foo(), in which this calling_module() is invoked. Ignores callers that belong in the same module as foo()
synapseclient.utils.download_file(url, localFilepath=None)

Downloads a remote file.

Parameters:localFilePath – May be None, in which case a temporary file is created
Returns:localFilePath
synapseclient.utils.equal_paths(path1, path2)

Compare file paths in a platform neutral way

synapseclient.utils.extract_filename(content_disposition_header, default_filename=None)

Extract a filename from an HTTP content-disposition header field.

See this memo and this package for cryptic details.

synapseclient.utils.extract_prefix(keys)

Takes a list of strings and extracts a common prefix delimited by a dot, for example: >>> extract_prefix([“entity.bang”, “entity.bar”, “entity.bat”]) entity.

synapseclient.utils.extract_user_name(profile)

Extract a displayable user name from a user’s profile

synapseclient.utils.file_url_to_path(url, verify_exists=False)

Convert a file URL to a path, handling some odd cases around Windows paths.

Parameters:
  • url – a file URL
  • verify_exists – If true, return an populated dict only if the resulting file path exists on the local file system.
Returns:

a path or None if the URL is not a file URL.

synapseclient.utils.find_data_file_handle(bundle)

Return the fileHandle whose ID matches the dataFileHandleId in an entity bundle

synapseclient.utils.format_time_interval(seconds)

Format a time interval given in seconds to a readable value, e.g. “5 minutes, 37 seconds”.

synapseclient.utils.from_unix_epoch_time(ms)

Returns a Datetime object given milliseconds since midnight Jan 1, 1970.

synapseclient.utils.from_unix_epoch_time_secs(secs)

Returns a Datetime object given milliseconds since midnight Jan 1, 1970.

synapseclient.utils.get_properties(entity)

Returns the dictionary of properties of the given Entity.

synapseclient.utils.guess_file_name(string)

Tries to derive a filename from an arbitrary string.

synapseclient.utils.id_of(obj)

Try to figure out the Synapse ID of the given object.

Parameters:obj – May be a string, Entity object, or dictionary
Returns:The ID or throws an exception
synapseclient.utils.is_in_path(id, path)

Determines whether id is in the path as returned from /entity/{id}/path

Parameters:
  • id – synapse id string
  • path – object as returned from ‘/entity/{id}/path’
Returns:

True or False

synapseclient.utils.is_same_base_url(url1, url2)

Compares two urls to see if they are the same excluding up to the base path

Parameters:
  • url1 – a URL
  • url2 – a second URL
Returns:

Boolean

synapseclient.utils.is_synapse_id(obj)

If the input is a Synapse ID return it, otherwise return None

synapseclient.utils.is_url(s)

Return True if the string appears to be a valid URL.

synapseclient.utils.itersubclasses(cls, _seen=None)

http://code.activestate.com/recipes/576949/ (r3)

itersubclasses(cls)

Generator over all subclasses of a given class, in depth first order.

>>> list(itersubclasses(int)) == [bool]
True
>>> class A(object): pass
>>> class B(A): pass
>>> class C(A): pass
>>> class D(B,C): pass
>>> class E(D): pass
>>>
>>> for cls in itersubclasses(A):
...     print(cls.__name__)
B
D
E
C
>>> # get ALL (new-style) classes currently defined
>>> [cls.__name__ for cls in itersubclasses(object)] 
['type', ...'tuple', ...]
synapseclient.utils.make_bogus_binary_file(n=1048576, filepath=None, printprogress=False)

Makes a bogus binary data file for testing. It is the caller’s responsibility to clean up the file when finished.

Parameters:n – How many bytes to write
Returns:The name of the file
synapseclient.utils.make_bogus_data_file(n=100, seed=None)

Makes a bogus data file for testing. It is the caller’s responsibility to clean up the file when finished.

Parameters:
  • n – How many random floating point numbers to be written into the file, separated by commas
  • seed – Random seed for the random numbers
Returns:

The name of the file

synapseclient.utils.md5_for_file(filename, block_size=2097152)

Calculates the MD5 of the given file. See source.

Parameters:
  • filename – The file to read in
  • block_size – How much of the file to read in at once (bytes). Defaults to 2 MB
Returns:

The MD5

synapseclient.utils.normalize_path(path)

Transforms a path into an absolute path with forward slashes only.

synapseclient.utils.normalize_whitespace(s)

Strips the string and replace all whitespace sequences and other non-printable characters with a single space.

synapseclient.utils.printTransferProgress(transferred, toBeTransferred, prefix=u'', postfix=u'', isBytes=True, dt=None, previouslyTransferred=0)

Prints a progress bar

Parameters:
  • transferred – a number of items/bytes completed
  • toBeTransferred – total number of items/bytes when completed
  • prefix – String printed before progress bar
  • prefix – String printed after progress bar
  • isBytes – A boolean indicating whether to convert bytes to kB, MB, GB etc.
  • dt – The time in seconds that has passed since transfer started is used to calculate rate.
  • previouslyTransferred – the number of bytes that were already transferred before this transfer began( e.g. someone ctrl+c’d out of an upload and restarted it later)
synapseclient.utils.query_limit_and_offset(query, hard_limit=1000)

Extract limit and offset from the end of a query string.

Returns:A triple containing the query with limit and offset removed, the limit at most equal to the hard_limit, and the offset which defaults to 1
synapseclient.utils.threadsafe_generator(f)

A decorator that takes a generator function and makes it thread-safe. See: http://anandology.com/blog/using-iterators-and-generators/

class synapseclient.utils.threadsafe_iter(it)

Takes an iterator/generator and makes it thread-safe by serializing call to the next method of given iterator/generator. See: http://anandology.com/blog/using-iterators-and-generators/

synapseclient.utils.to_unix_epoch_time(dt)

Convert either datetime.date or datetime.datetime objects to UNIX time.

synapseclient.utils.to_unix_epoch_time_secs(dt)

Convert either datetime.date or datetime.datetime objects to UNIX time.

synapseclient.utils.topolgical_sort(graph)

Given a graph in the form of a dictionary returns a sorted list

Adapted from: http://blog.jupo.org/2012/04/06/topological-sorting-acyclic-directed-graphs/

Parameters:graph – a dictionary with values containing lists of keys referencing back into the dictionary
Returns:sorted list of items
synapseclient.utils.touch(path, times=None)

Make sure a file exists. Update its access and modified times.

synapseclient.utils.unique_filename(path)

Returns a unique path by appending (n) for some number n to the end of the filename.