0
# Humanize
1

2
A comprehensive Python library that transforms machine-readable data into human-friendly formats. Humanize provides utilities for converting numbers into readable formats, dates and times into natural language expressions, file sizes into human-readable units, and includes extensive localization support for over 25 languages.
3

4
## Package Information
5

6
- **Package Name**: humanize
7
- **Language**: Python
8
- **Installation**: `pip install humanize`
9
- **Minimum Python Version**: 3.9+
10

11
## Core Imports
12

13
```python
14
import humanize
15
```
16

17
Import specific functions:
18

19
```python
20
from humanize import naturalsize, intcomma, naturaltime
21
```
22

23
Import from submodules:
24

25
```python
26
from humanize.time import naturaldelta, precisedelta
27
from humanize.number import intword, ordinal
28
```
29

30
## Basic Usage
31

32
```python
33
import humanize
34
import datetime as dt
35

36
# Format numbers with commas
37
print(humanize.intcomma(1000000))  # "1,000,000"
38

39
# Convert numbers to words  
40
print(humanize.intword(1200000))   # "1.2 million"
41

42
# Format file sizes
43
print(humanize.naturalsize(1024))  # "1.0 kB"
44

45
# Natural time expressions
46
now = dt.datetime.now()
47
past = now - dt.timedelta(minutes=30)
48
print(humanize.naturaltime(past))  # "30 minutes ago"
49

50
# Create natural lists
51
items = ["apples", "oranges", "bananas"]
52
print(humanize.natural_list(items))  # "apples, oranges and bananas"
53
```
54

55
## Architecture
56

57
The humanize library is organized into focused modules:
58

59
- **Number Module**: Comprehensive number formatting utilities including comma separation, word conversion, ordinals, fractions, scientific notation, and metric prefixes
60
- **Time Module**: Natural language time and date formatting with relative expressions, precision control, and internationalization
61
- **File Size Module**: Human-readable file size formatting with binary/decimal unit support
62
- **Lists Module**: Natural language list formatting with proper conjunction usage
63
- **Internationalization Module**: Locale activation, deactivation, and formatting customization for 25+ languages
64

65
All functions handle edge cases gracefully, support various input types, and provide consistent error handling by returning string representations of invalid inputs.
66

67
## Capabilities
68

69
### Number Formatting
70

71
Convert numbers into human-readable formats including comma separation, word conversion, ordinals, fractions, scientific notation, and metric prefixes with SI units.
72

73
```python { .api }
74
def intcomma(value: float | str, ndigits: int | None = None) -> str: ...
75
def intword(value: float | str, format: str = "%.1f") -> str: ...
76
def ordinal(value: float | str, gender: str = "male") -> str: ...
77
def apnumber(value: float | str) -> str: ...
78
def fractional(value: float | str) -> str: ...
79
def scientific(value: float | str, precision: int = 2) -> str: ...
80
def clamp(value: float, format: str = "{:}", floor: float | None = None, ceil: float | None = None, floor_token: str = "<", ceil_token: str = ">") -> str: ...
81
def metric(value: float, unit: str = "", precision: int = 3) -> str: ...
82
```
83

84
[Number Formatting](./number-formatting.md)
85

86
### Time and Date Formatting
87

88
Natural language time and date formatting with relative expressions, precision control, and support for various input types including datetime objects, timedeltas, and seconds.
89

90
```python { .api }
91
def naturaltime(value: dt.datetime | dt.timedelta | float, future: bool = False, months: bool = True, minimum_unit: str = "seconds", when: dt.datetime | None = None) -> str: ...
92
def naturaldelta(value: dt.timedelta | float, months: bool = True, minimum_unit: str = "seconds") -> str: ...
93
def naturaldate(value: dt.date | dt.datetime) -> str: ...
94
def naturalday(value: dt.date | dt.datetime, format: str = "%b %d") -> str: ...
95
def precisedelta(value: dt.timedelta | float | None, minimum_unit: str = "seconds", suppress: Iterable[str] = (), format: str = "%0.2f") -> str: ...
96
```
97

98
[Time and Date Formatting](./time-formatting.md)
99

100
### File Size Formatting
101

102
Convert byte counts into human-readable file size representations with support for decimal (SI) and binary (IEC) units, plus GNU-style formatting.
103

104
```python { .api }
105
def naturalsize(value: float | str, binary: bool = False, gnu: bool = False, format: str = "%.1f") -> str: ...
106
```
107

108
[File Size Formatting](./filesize-formatting.md)
109

110
### List Formatting
111

112
Convert Python lists into natural language with proper comma placement and conjunction usage.
113

114
```python { .api }
115
def natural_list(items: list[Any]) -> str: ...
116
```
117

118
[List Formatting](./list-formatting.md)
119

120
### Internationalization
121

122
Activate and manage localization for 25+ supported languages, with locale-specific number and date formatting.
123

124
```python { .api }
125
def activate(locale: str | None, path: str | os.PathLike[str] | None = None) -> gettext.NullTranslations: ...
126
def deactivate() -> None: ...
127
def thousands_separator() -> str: ...
128
def decimal_separator() -> str: ...
129
```
130

131
[Internationalization](./internationalization.md)
132

133
## Common Types
134

135
```python { .api }
136
# Type aliases used throughout the library
137
NumberOrString = float | str
138

139
# Datetime/time types
140
import datetime as dt
141
from typing import Any, Iterable
142
import os
143
import gettext
144
```