diff options
Diffstat (limited to 'src/common.py')
| -rw-r--r-- | src/common.py | 105 |
1 files changed, 65 insertions, 40 deletions
diff --git a/src/common.py b/src/common.py index e4e3a52d..1a3027e7 100644 --- a/src/common.py +++ b/src/common.py @@ -6,7 +6,7 @@ # it under the terms of the zlib license. See the COPYING file. """ -various useful functions +Various useful functions. """ from datetime import datetime, timedelta @@ -29,6 +29,13 @@ ROOM_STATE_HL = 13 def get_base64_from_file(path): """ Convert the content of a file to base64 + + :param str path: The path of the file to convert. + :return: A tuple of (encoded data, mime type, sha1 hash) if + the file exists and does not exceeds the upper size limit of 16384. + :return: (None, None, error message) if it fails + :rtype: :py:class:`tuple` + """ if not os.path.isfile(path): return (None, None, "File does not exist") @@ -44,7 +51,11 @@ def get_base64_from_file(path): def get_output_of_command(command): """ - Runs a command and returns its output + Runs a command and returns its output. + + :param str command: The command to run. + :return: The output or None + :rtype: :py:class:`str` """ try: return subprocess.check_output(command.split()).decode('utf-8').split('\n') @@ -53,9 +64,14 @@ def get_output_of_command(command): def is_in_path(command, return_abs_path=False): """ - Return True if 'command' is found in one of the directories in the user's - path. If 'return_abs_path' is True, return the absolute path of the first - found command instead. Return False otherwise and on errors + Check if *command* is in the $PATH or not. + + :param str command: The command to be checked. + :param bool return_abs_path: Return the absolute path of the command instead + of True if the command is found. + :return: True if the command is found, the command path if the command is found + and *return_abs_path* is True, otherwise False. + """ for directory in os.getenv('PATH').split(os.pathsep): try: @@ -95,6 +111,8 @@ def get_os_info(): """ Returns a detailed and well formated string containing informations about the operating system + + :rtype: str """ if os.name == 'posix': executable = 'lsb_release' @@ -151,14 +169,21 @@ def get_os_info(): def datetime_tuple(timestamp): """ - Convert timestamp using strptime and the format: %Y%m%dT%H:%M:%S + Convert a timestamp using strptime and the format: %Y%m%dT%H:%M:%S. - Because of various datetime formats are used the following exceptions + Because various datetime formats are used, the following exceptions are handled: - - Optional milliseconds appened to the string are removed - - Optional Z (that means UTC) appened to the string are removed - - XEP-082 datetime strings have all '-' cahrs removed to meet - the above format. + + * Optional milliseconds appened to the string are removed + * Optional Z (that means UTC) appened to the string are removed + * XEP-082 datetime strings have all '-' chars removed to meet the above format. + + :param str timestamp: The string containing the formatted date. + :return: The date. + :rtype: :py:class:`datetime.datetime` + + >>> common.datetime_tuple('20130226T06:23:12') + datetime.datetime(2013, 2, 26, 8, 23, 12) """ timestamp = timestamp.split('.')[0] timestamp = timestamp.replace('-', '') @@ -172,6 +197,17 @@ def datetime_tuple(timestamp): return ret def shell_split(st): + """ + Split a string correctly according to the quotes + around the elements. + + :param str st: The string to split. + :return: A list of the different of the string. + :rtype: :py:class:`list` + + >>> shell_split('"sdf 1" "toto 2"') + ['sdf 1', 'toto 2'] + """ sh = shlex.shlex(st, posix=True) sh.commenters = '' sh.whitespace_split = True @@ -188,7 +224,12 @@ def shell_split(st): def parse_str_to_secs(duration=''): """ - Parse a string of with a number of d, h, m, s + Parse a string of with a number of d, h, m, s. + + :param str duration: The formatted string. + :return: The number of seconds represented by the string + :rtype: :py:class:`int` + >>> parse_str_to_secs("1d3m1h") 90180 """ @@ -210,8 +251,15 @@ def parse_str_to_secs(duration=''): def parse_secs_to_str(duration=0): """ + Do the reverse operation of :py:func:`parse_str_to_secs`. + Parse a number of seconds to a human-readable string. The string has the form XdXhXmXs. 0 units are removed. + + :param int duration: The duration, in seconds. + :return: A formatted string containing the duration. + :rtype: :py:class:`str` + >>> parse_secs_to_str(3601) 1h1s """ @@ -230,36 +278,13 @@ def parse_secs_to_str(duration=0): result = '0s' return result -def parse_command_args_to_alias(arg, strto): - """ - Parse command parameters. - Numbers can be from 0 to 9. - >>> parse_command_args_to_alias('sdf koin', '%1 %0') - "koin sdf" +def safeJID(*args, **kwargs): """ - if '%' not in strto: - return strto + arg - args = shell_split(arg) - l = len(args) - dest = '' - var_num = False - for i in strto: - if i != '%': - if not var_num: - dest += i - elif i in string.digits: - if 0 <= int(i) < l: - dest += args[int(i)] - var_num = False - elif i == '%': - if var_num: - dest += '%' - var_num = False - else: - var_num = True - return dest + Construct a :py:class:`sleekxmpp.JID` object from a string. -def safeJID(*args, **kwargs): + Used to avoid tracebacks during is stringprep fails + (fall back to a JID with an empty string). + """ try: return JID(*args, **kwargs) except InvalidJID: |