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)] #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.
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='', postfix='', 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.