"""Functions for reporting filesizes. Borrowed from https://github.com/PyFilesystem/pyfilesystem2 The functions declared in this module should cover the different use cases needed to generate a string representation of a file size using several different units. Since there are many standards regarding file size units, three different functions have been implemented. See Also: * `Wikipedia: Binary prefix <https://en.wikipedia.org/wiki/Binary_prefix>`_ """ __all__ = ["decimal"] from typing import Iterable, List, Optional, Tuple def _to_str( size: int, suffixes: Iterable[str], base: int, *, precision: Optional[int] = 1, separator: Optional[str] = " ", ) -> str: if size == 1: return "1 byte" elif size < base: return f"{size:,} bytes" for i, suffix in enumerate(suffixes, 2): # noqa: B007 unit = base**i if size < unit: break return "{:,.{precision}f}{separator}{}".format( (base * size / unit), suffix, precision=precision, separator=separator, ) def pick_unit_and_suffix(size: int, suffixes: List[str], base: int) -> Tuple[int, str]: """Pick a suffix and base for the given size.""" for i, suffix in enumerate(suffixes): unit = base**i if size < unit * base: break return unit, suffix def decimal( size: int, *, precision: Optional[int] = 1, separator: Optional[str] = " ", ) -> str: """Convert a filesize in to a string (powers of 1000, SI prefixes). In this convention, ``1000 B = 1 kB``. This is typically the format used to advertise the storage capacity of USB flash drives and the like (*256 MB* meaning actually a storage capacity of more than *256 000 000 B*), or used by **Mac OS X** since v10.6 to report file sizes. Arguments: int (size): A file size. int (precision): The number of decimal places to include (default = 1). str (separator): The string to separate the value from the units (default = " "). Returns: `str`: A string containing a abbreviated file size and units. Example: >>> filesize.decimal(30000) '30.0 kB' >>> filesize.decimal(30000, precision=2, separator="") '30.00kB' """ return _to_str( size, ("kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"), 1000, precision=precision, separator=separator, )