Source code for fs.filesize

# coding: utf-8
"""Functions for reporting filesizes.

The functions declared in this module should cover the different
usecases 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>`_

"""

from __future__ import division
from __future__ import unicode_literals

import typing

if False:  # typing.TYPE_CHECKING
    from typing import Iterable, SupportsInt, Text


__all__ = ["traditional", "decimal", "binary"]


def _to_str(size, suffixes, base):
    # type: (SupportsInt, Iterable[Text], int) -> Text
    try:
        size = int(size)
    except ValueError:
        raise TypeError("filesize requires a numeric value, not {!r}".format(size))
    if size == 1:
        return "1 byte"
    elif size < base:
        return "{:,} bytes".format(size)

    for i, suffix in enumerate(suffixes, 2):
        unit = base ** i
        if size < unit:
            break
    return "{:,.1f} {}".format((base * size / unit), suffix)


[docs]def traditional(size): # type: (SupportsInt) -> Text """Convert a filesize in to a string (powers of 1024, JDEC prefixes). In this convention, ``1024 B = 1 KB``. This is the format that was used to display the size of DVDs (*700 MB* meaning actually about *734 003 200 bytes*) before standardisation of IEC units among manufacturers, and still used by **Windows** to report the storage capacity of hard drives (*279.4 GB* meaning *279.4 × 1024³ bytes*). Arguments: size (int): A file size. Returns: `str`: A string containing an abbreviated file size and units. Example: >>> filesize.traditional(30000) '29.3 KB' """ return _to_str(size, ("KB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"), 1024)
[docs]def binary(size): # type: (SupportsInt) -> Text """Convert a filesize in to a string (powers of 1024, IEC prefixes). In this convention, ``1024 B = 1 KiB``. This is the format that has gained adoption among manufacturers to avoid ambiguity regarding size units, since it explicitly states using a binary base (*KiB = kibi bytes = kilo binary bytes*). This format is notably being used by the **Linux** kernel (see ``man 7 units``). Arguments: int (size): A file size. Returns: `str`: A string containing a abbreviated file size and units. Example: >>> filesize.binary(30000) '29.3 KiB' """ return _to_str(size, ("KiB", "MiB", "GiB", "TiB", "PiB", "EiB", "ZiB", "YiB"), 1024)
[docs]def decimal(size): # type: (SupportsInt) -> Text """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. Returns: `str`: A string containing a abbreviated file size and units. Example: >>> filesize.decimal(30000) '30.0 kB' """ return _to_str(size, ("kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"), 1000)