Utility Functions

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


Tries to convert the input into a proper URL.

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
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.


Takes a list of strings and extracts a common prefix delimited by a dot, for example:

extract_prefix(["entity.bang", "entity.bar", "entity.bat"])



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.

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

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


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


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


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


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


Returns the dictionary of properties of the given Entity.


Tries to derive a filename from an arbitrary string.


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

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

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

  • url1 – a URL
  • url2 – a second URL



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


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

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

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


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

>>> list(itersubclasses(int)) == [bool]
>>> 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__)
>>> # get ALL (new-style) classes currently defined
>>> [cls.__name__ for cls in itersubclasses(object)] #doctest: +ELLIPSIS
['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.

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

The name of the file

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

Calculates the MD5 of the given file. See source.

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

The MD5


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


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

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

Prints a progress bar

  • 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

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/


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


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


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.


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