# Common operations documentation

Various useful functions.

`common.``datetime_tuple`(timestamp)

  Convert a timestamp using strptime and the format: %Y%m%dT%H:%M:%S.

  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 ‘-‘ chars removed to meet the above format.

  Parameters: | timestamp (str) – The string containing the formatted date.
  Returns: | The date.
  Return type: | `datetime.datetime`

`common.``find_argument`(pos, text, quoted=True)

  Split an input into a list of arguments, return the number of the argument selected by pos.

  If the position searched is outside the string, or in a space between words, then it will return the position of an hypothetical new argument.

  See the doctests of the two methods for example behaviors.

  Parameters:

  - pos (int) – The position to search.
  - text (str) – The text to analyze.
  - quoted – Whether to take quotes into account or not.

  Return type: | int

`common.``find_argument_quoted`(pos, text)

  Get the number of the argument at position pos in a string with possibly quoted text.

`common.``find_argument_unquoted`(pos, text)

  Get the number of the argument at position pos in a string without interpreting quotes.

`common.``find_delayed_tag`(message)

  Check if a message is delayed or not.

  Parameters: | message (slixmpp.Message) – The message to check.
  Returns: | A tuple containing (True, the datetime) or (False, None)
  Return type: | `tuple`

`common.``format_gaming_string`(infos)

  Construct a string from a dict containing the “user gaming” informations. (for now, only use address and name)

  Parameters: | infos (dict) – The informations
  Returns: | The formatted string
  Return type: | `str`

`common.``format_tune_string`(infos)

  Contruct a string from a dict created from an “User tune” event.

  Parameters: | infos (dict) – The informations
  Returns: | The formatted string
  Return type: | `str`

`common.``get_base64_from_file`(path)

  Convert the content of a file to base64

  Parameters: | path (str) – The path of the file to convert.
  Returns: | A tuple of (encoded data, mime type, sha1 hash) if the file exists and does not exceeds the upper size limit of 16384.
  Returns: | (None, None, error message) if it fails
  Return type: | `tuple`

`common.``get_local_time`(utc_time)

  Get the local time from an UTC time

`common.``get_os_info`()

  Returns a detailed and well formated string containing informations about the operating system

  Return type: | str

`common.``get_output_of_command`(command)

  Runs a command and returns its output.

  Parameters: | command (str) – The command to run.
  Returns: | The output or None
  Return type: | `str`

`common.``get_utc_time`(local_time=None)

  Get the current UTC time

  Parameters: | local_time (datetime) – The current local time
  Returns: | The current UTC time

`common.``is_in_path`(command, return_abs_path=False)

  Check if command is in the $PATH or not.

  Parameters:

  - command (str) – The command to be checked.
  - return_abs_path (bool) – Return the absolute path of the command instead of True if the command is found.

  Returns: | True if the command is found, the command path if the command is found and return_abs_path is True, otherwise False.

`common.``parse_secs_to_str`(duration=0)

  Do the reverse operation of `parse_str_to_secs()`.

  Parse a number of seconds to a human-readable string. The string has the form XdXhXmXs. 0 units are removed.

  Parameters: | duration (int) – The duration, in seconds.
  Returns: | A formatted string containing the duration.
  Return type: | `str`

      >>> parse_secs_to_str(3601)
      '1h1s'

`common.``parse_str_to_secs`(duration='')

  Parse a string of with a number of d, h, m, s.

  Parameters: | duration (str) – The formatted string.
  Returns: | The number of seconds represented by the string
  Return type: | `int`

      >>> parse_str_to_secs("1d3m1h")
      90180

`common.``safeJID`(*args, **kwargs)

  Construct a `slixmpp.JID` object from a string.

  Used to avoid tracebacks during is stringprep fails (fall back to a JID with an empty string).

`common.``shell_split`(st)

  Split a string correctly according to the quotes around the elements.

  Parameters: | st (str) – The string to split.
  Returns: | A list of the different of the string.
  Return type: | `list`

      >>> shell_split('"sdf 1" "toto 2"')
      ['sdf 1', 'toto 2']