0
# File Size Formatting
1

2
Convert byte counts into human-readable file size representations with support for decimal (SI), binary (IEC), and GNU-style formatting options.
3

4
## Capabilities
5

6
### Natural Size
7

8
Formats byte counts into human-readable file size strings with automatic unit selection and customizable formatting options.
9

10
```python { .api }
11
def naturalsize(
12
    value: float | str,
13
    binary: bool = False,
14
    gnu: bool = False,
15
    format: str = "%.1f"
16
) -> str:
17
    """
18
    Format a number of bytes like a human-readable filesize.
19
    
20
    Args:
21
        value: Number of bytes (int, float, or string)
22
        binary: Use binary suffixes (KiB, MiB) with base 2^10 instead of 10^3
23
        gnu: Use GNU-style prefixes (K, M) with 2^10 definition, ignores binary
24
        format: Custom formatter for the numeric portion
25
    
26
    Returns:
27
        Human readable representation of a filesize
28
    
29
    Examples:
30
        >>> naturalsize(3000000)
31
        '3.0 MB'
32
        >>> naturalsize(3000, binary=True)
33
        '2.9 KiB'
34
        >>> naturalsize(3000, gnu=True)
35
        '2.9K'
36
        >>> naturalsize(10**28)
37
        '10.0 RB'
38
    """
39
```
40

41
## Size Unit Systems
42

43
The function supports three different unit systems:
44

45
### Decimal (SI) Units - Default
46
Uses base 1000 with decimal prefixes:
47
- **B** (Bytes)
48
- **kB** (kilobytes) = 1,000 bytes
49
- **MB** (megabytes) = 1,000,000 bytes  
50
- **GB** (gigabytes) = 1,000,000,000 bytes
51
- **TB, PB, EB, ZB, YB, RB, QB** (continuing the pattern)
52

53
### Binary (IEC) Units
54
Uses base 1024 with binary prefixes when `binary=True`:
55
- **B** (Bytes)
56
- **KiB** (kibibytes) = 1,024 bytes
57
- **MiB** (mebibytes) = 1,048,576 bytes
58
- **GiB** (gibibytes) = 1,073,741,824 bytes
59
- **TiB, PiB, EiB, ZiB, YiB, RiB, QiB** (continuing the pattern)
60

61
### GNU Style Units
62
Uses base 1024 with single-character prefixes when `gnu=True`:
63
- **B** (Bytes)
64
- **K** (kilobytes) = 1,024 bytes
65
- **M** (megabytes) = 1,048,576 bytes
66
- **G, T, P, E, Z, Y, R, Q** (continuing the pattern)
67

68
## Constants
69

70
```python { .api }
71
# Suffix mappings for different size formats
72
suffixes: dict[str, tuple[str, ...] | str] = {
73
    "decimal": (" kB", " MB", " GB", " TB", " PB", " EB", " ZB", " YB", " RB", " QB"),
74
    "binary": (" KiB", " MiB", " GiB", " TiB", " PiB", " EiB", " ZiB", " YiB", " RiB", " QiB"),
75
    "gnu": "KMGTPEZYRQ"
76
}
77
```
78

79
## Usage Examples
80

81
### Basic File Size Formatting
82

83
```python
84
import humanize
85

86
# Default decimal (SI) units
87
print(humanize.naturalsize(1024))        # "1.0 kB"
88
print(humanize.naturalsize(1048576))     # "1.0 MB"
89
print(humanize.naturalsize(1073741824))  # "1.1 GB"
90

91
# Binary (IEC) units - more accurate for computer storage
92
print(humanize.naturalsize(1024, binary=True))        # "1.0 KiB"
93
print(humanize.naturalsize(1048576, binary=True))     # "1.0 MiB"
94
print(humanize.naturalsize(1073741824, binary=True))  # "1.0 GiB"
95

96
# GNU-style units - compact representation
97
print(humanize.naturalsize(1024, gnu=True))        # "1.0K"
98
print(humanize.naturalsize(1048576, gnu=True))     # "1.0M"
99
print(humanize.naturalsize(1073741824, gnu=True))  # "1.0G"
100
```
101

102
### Custom Formatting
103

104
```python
105
import humanize
106

107
# Custom precision
108
print(humanize.naturalsize(1234567, format="%.3f"))  # "1.235 MB"
109
print(humanize.naturalsize(1024, format="%.0f"))     # "1 kB"
110

111
# Very large numbers
112
print(humanize.naturalsize(10**28))    # "10.0 RB" (ronnabytes)
113
print(humanize.naturalsize(10**31))    # "100.0 RB"
114
print(humanize.naturalsize(10**34))    # "100.0 QB" (quettabytes)
115
```
116

117
### Special Cases
118

119
```python
120
import humanize
121

122
# Single byte
123
print(humanize.naturalsize(1))        # "1 Byte"
124
print(humanize.naturalsize(1, gnu=True))  # "1B"
125

126
# Zero bytes
127
print(humanize.naturalsize(0))        # "0 Bytes"
128
print(humanize.naturalsize(0, gnu=True))  # "0B"
129

130
# Negative values
131
print(humanize.naturalsize(-4096, binary=True))  # "-4.0 KiB"
132

133
# String input
134
print(humanize.naturalsize("1048576"))  # "1.0 MB"
135
```
136

137
## Compatibility
138

139
The non-GNU modes are compatible with Jinja2's `filesizeformat` filter, making this function suitable for use in web templates and similar contexts where consistent file size formatting is needed.
140

141
## Error Handling
142

143
- Invalid numeric strings return the original string unchanged
144
- Non-convertible values return their string representation
145
- The function handles very large numbers gracefully up to quettabyte scale
146
- Negative values are properly handled with negative signs preserved