maestral.utils
==============

.. py:module:: maestral.utils

.. autoapi-nested-parse::

   Utility modules and functions



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/maestral/utils/appdirs/index
   /autoapi/maestral/utils/caches/index
   /autoapi/maestral/utils/hashing/index
   /autoapi/maestral/utils/integration/index
   /autoapi/maestral/utils/path/index




Package Contents
----------------

.. py:function:: natural_size(num, unit = 'B', sep = True)

   Convert number to a human-readable string with decimal prefix.

   :param float num: Value in given unit.
   :param unit: Unit suffix.
   :param sep: Whether to separate unit and value with a space.
   :returns: Human-readable string with decimal prefixes.


.. py:function:: chunks(lst, n, consume = False)

   Partitions a list into chunks of length ``n``.

   :param lst: Iterable to partition.
   :param n: Chunk size.
   :param consume: If True, the list will be consumed (emptied) during the iteration.
   :returns: Iterator over chunks.


.. py:function:: clamp(n, minn, maxn)

   Clamps a number between a minimum and maximum value.

   :param n: Original value.
   :param minn: Minimum allowed value.
   :param maxn: Maximum allowed value.
   :returns: Clamped value.


.. py:function:: get_newer_version(version, releases)

   Checks a given release version against a version list of releases to see if an
   update is available. Only offers newer versions if they are not a prerelease.

   :param version: The current version.
   :param releases: A list of valid cleaned releases.
   :returns: The version string of the latest release if a newer release is available.


.. py:function:: removeprefix(string, prefix, case_sensitive = True)

   Removes the given prefix from a string. Only the first instance of the prefix is
   removed. The original string is returned if it does not start with the given prefix.

   This follows the Python 3.9 implementation of ``str.removeprefix``.

   :param string: Original string.
   :param prefix: Prefix to remove.
   :param case_sensitive: Whether to do case-sensitive prefix removal.
   :returns: String without prefix.


.. py:function:: sanitize_string(string)

   Converts a string provided by file system APIs, which may contain surrogate escapes
   for bytes with unknown encoding, to a string which can always be displayed or
   printed. This is done by replacing invalid characters with "�".

   :param string: Original string.
   :returns: Sanitised path where all surrogate escapes have been replaced with "�".


.. py:function:: exc_info_tuple(exc)

   Creates an exc-info tuple from an exception.