# Common operations documentation

Various useful functions.

poezio.common.find_argument(pos: int, text: str, quoted: bool = True) → int

  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 (bool) -- Whether to take quotes into account or not.

  Return type:

    int

poezio.common.find_delayed_tag(message: Message) → Tuple[bool, datetime | None]

  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`

poezio.common.format_gaming_string(infos: Dict[str, str]) → str

  Construct a string from a dict containing "user gaming" information. (for now, only use address and name)

  Parameters:

    infos (dict) -- Gaming information

  Returns:

    The formatted string

  Return type:

    `str`

poezio.common.format_tune_string(infos: Dict[str, str]) → str

  Construct a string from a dict created from an "User tune" event.

  Parameters:

    infos (dict) -- Tune information

  Returns:

    The formatted string

  Return type:

    `str`

poezio.common.get_error_message(stanza: Message, deprecated: bool = False) → str

  Takes a stanza of the form <message type='error'><error/></message> and return a well formed string containing error information

poezio.common.get_local_time(utc_time: datetime) → datetime

  Get the local time from an UTC time

poezio.common.get_os_info() → str

  Returns a detailed and well formatted string containing information about the operating system

  Return type:

    str

poezio.common.get_utc_time(local_time: datetime | None = None) → datetime

  Get the current UTC time

  Parameters:

    local_time (datetime) -- The current local time

  Returns:

    The current UTC time

poezio.common.parse_secs_to_str(duration: int = 0) → str

  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'

poezio.common.parse_str_to_secs(duration: str = '') → int

  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

poezio.common.shell_split(st: str) → List[str]

  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']

poezio.common.to_utc(time_: datetime) → datetime

  Convert a datetime-aware time zone into raw UTC

poezio.common.unique_prefix_of(a: str, b: str) → str

  Return the unique prefix of a with b.

  Corner cases:

  - If a and b share no prefix, the first letter of a is returned.

  - If a and b are equal, a is returned.

  - If a is a prefix of b, a is returned.

  - If b is a prefix of a, b plus the first letter of a after the common prefix is returned.