0
# Date, Time, and Number Formatting
1

2
Locale-aware formatting functions for dates, times, numbers, and currencies with timezone support.
3

4
## Capabilities
5

6
### Date and Time Formatting
7

8
Format date and time values according to current locale with automatic timezone conversion.
9

10
```python { .api }
11
def format_datetime(datetime=None, format=None, rebase=True):
12
    """
13
    Format datetime according to current locale.
14
    
15
    Parameters:
16
    - datetime: datetime object (uses current time if None)
17
    - format: Format string ('short', 'medium', 'long', 'full') or custom Babel format
18
    - rebase: Whether to convert to user's timezone (default: True)
19
    
20
    Returns:
21
    Formatted datetime string
22
    """
23

24
def format_date(date=None, format=None, rebase=True):
25
    """
26
    Format date according to current locale.
27
    
28
    Parameters:
29
    - date: datetime or date object (uses current date if None)
30
    - format: Format string ('short', 'medium', 'long', 'full') or custom Babel format
31
    - rebase: Whether to convert to user's timezone for datetime objects (default: True)
32
    
33
    Returns:
34
    Formatted date string
35
    """
36

37
def format_time(time=None, format=None, rebase=True):
38
    """
39
    Format time according to current locale.
40
    
41
    Parameters:
42
    - time: datetime object (uses current time if None)
43
    - format: Format string ('short', 'medium', 'long', 'full') or custom Babel format
44
    - rebase: Whether to convert to user's timezone (default: True)
45
    
46
    Returns:
47
    Formatted time string
48
    """
49

50
def format_timedelta(datetime_or_timedelta, granularity: str = 'second', add_direction=False, threshold=0.85):
51
    """
52
    Format elapsed time from date to now or format timedelta.
53
    
54
    Parameters:
55
    - datetime_or_timedelta: datetime or timedelta object
56
    - granularity: Granularity level ('year', 'month', 'week', 'day', 'hour', 'minute', 'second')
57
    - add_direction: Whether to add directional words like 'ago' or 'in'
58
    - threshold: Threshold for rounding to next unit (0.0-1.0)
59
    
60
    Returns:
61
    Formatted time difference string
62
    """
63
```
64

65
### Timezone Utilities
66

67
Convert between timezones for proper locale handling.
68

69
```python { .api }
70
def to_user_timezone(datetime):
71
    """
72
    Convert datetime to user's timezone.
73
    
74
    Parameters:
75
    - datetime: datetime object
76
    
77
    Returns:
78
    datetime object in user's timezone
79
    """
80

81
def to_utc(datetime):
82
    """
83
    Convert datetime to UTC and remove timezone info.
84
    
85
    Parameters:
86
    - datetime: datetime object
87
    
88
    Returns:
89
    datetime object in UTC without tzinfo
90
    """
91
```
92

93
### Number Formatting
94

95
Format numbers according to current locale.
96

97
```python { .api }
98
def format_number(number):
99
    """
100
    Format number for current locale.
101
    
102
    Parameters:
103
    - number: Number to format
104
    
105
    Returns:
106
    Formatted number string
107
    """
108

109
def format_decimal(number, format=None):
110
    """
111
    Format decimal number for current locale.
112
    
113
    Parameters:
114
    - number: Number to format
115
    - format: Decimal format pattern (optional)
116
    
117
    Returns:
118
    Formatted decimal string
119
    """
120

121
def format_percent(number, format=None):
122
    """
123
    Format percentage for current locale.
124
    
125
    Parameters:
126
    - number: Number to format as percentage (0.25 = 25%)
127
    - format: Percentage format pattern (optional)
128
    
129
    Returns:
130
    Formatted percentage string
131
    """
132

133
def format_scientific(number, format=None):
134
    """
135
    Format number in scientific notation for current locale.
136
    
137
    Parameters:
138
    - number: Number to format
139
    - format: Scientific format pattern (optional)
140
    
141
    Returns:
142
    Formatted scientific notation string
143
    """
144
```
145

146
### Currency Formatting
147

148
Format currency values with proper locale-specific symbols and positioning.
149

150
```python { .api }
151
def format_currency(number, currency, format=None, currency_digits=True, format_type='standard'):
152
    """
153
    Format currency for current locale.
154
    
155
    Parameters:
156
    - number: Amount to format
157
    - currency: Currency code (e.g., 'USD', 'EUR', 'GBP')
158
    - format: Currency format pattern (optional)
159
    - currency_digits: Use currency's standard decimal places (default: True)
160
    - format_type: Currency format type ('standard', 'accounting')
161
    
162
    Returns:
163
    Formatted currency string
164
    """
165
```
166

167
## Usage Examples
168

169
### Date and Time Formatting
170

171
```python
172
from datetime import datetime, timedelta
173
from flask_babel import format_datetime, format_date, format_time, format_timedelta
174

175
now = datetime.utcnow()
176

177
# Different format styles
178
short_datetime = format_datetime(now, 'short')     # "12/31/23, 11:59 PM"
179
medium_datetime = format_datetime(now, 'medium')   # "Dec 31, 2023, 11:59:59 PM"
180
long_datetime = format_datetime(now, 'long')       # "December 31, 2023 at 11:59:59 PM UTC"
181

182
# Date only
183
date_str = format_date(now, 'medium')              # "Dec 31, 2023"
184

185
# Time only  
186
time_str = format_time(now, 'short')               # "11:59 PM"
187

188
# Time differences
189
past_time = datetime.utcnow() - timedelta(hours=2)
190
time_ago = format_timedelta(past_time)             # "2 hours ago"
191

192
delta = timedelta(days=3, hours=4)
193
duration = format_timedelta(delta)                 # "3 days"
194
```
195

196
### Custom Date Formats
197

198
```python
199
from flask_babel import format_datetime
200

201
# Custom Babel format patterns
202
custom_format = format_datetime(now, "yyyy-MM-dd HH:mm")  # "2023-12-31 23:59"
203
verbose_format = format_datetime(now, "EEEE, MMMM d, yyyy") # "Sunday, December 31, 2023"
204
```
205

206
### Number Formatting
207

208
```python
209
from flask_babel import format_number, format_decimal, format_percent, format_scientific
210

211
# Numbers
212
large_number = 1234567.89
213
formatted = format_number(large_number)           # "1,234,567.89" (en) or "1.234.567,89" (de)
214

215
# Decimals with custom precision
216
decimal_str = format_decimal(123.456, "#.##")     # "123.46"
217

218
# Percentages
219
percentage = format_percent(0.1575)               # "15.75%" (en) or "15,75 %" (de)
220

221
# Scientific notation
222
scientific = format_scientific(1234567)           # "1.234567E6"
223
```
224

225
### Currency Formatting
226

227
```python
228
from flask_babel import format_currency
229

230
amount = 1234.56
231

232
# Different currencies
233
usd = format_currency(amount, 'USD')               # "$1,234.56" (en) or "1.234,56 $" (de)
234
eur = format_currency(amount, 'EUR')               # "€1,234.56" (en) or "1.234,56 €" (de)
235
gbp = format_currency(amount, 'GBP')               # "£1,234.56" (en)
236

237
# Accounting format (parentheses for negative)
238
negative_amount = -1234.56
239
accounting = format_currency(negative_amount, 'USD', format_type='accounting')  # "($1,234.56)"
240
```
241

242
### Timezone Handling
243

244
```python
245
from datetime import datetime
246
from pytz import timezone
247
from flask_babel import to_user_timezone, to_utc, format_datetime
248

249
# Create UTC datetime
250
utc_time = datetime.utcnow()
251

252
# Convert to user timezone (based on current request context)
253
user_time = to_user_timezone(utc_time)
254

255
# Format in user's timezone
256
formatted = format_datetime(user_time)
257

258
# Convert back to UTC
259
utc_again = to_utc(user_time)
260
```
261

262
### Jinja2 Template Integration
263

264
Flask-Babel automatically provides template filters:
265

266
```html
267
<!-- Date formatting -->
268
<p>Created: {{ post.created_at|datetimeformat('medium') }}</p>
269
<p>Date: {{ post.created_at|dateformat('short') }}</p>
270
<p>Time: {{ post.created_at|timeformat }}</p>
271

272
<!-- Number formatting -->
273
<p>Price: {{ product.price|currencyformat('USD') }}</p>
274
<p>Discount: {{ discount|percentformat }}</p>
275
<p>Views: {{ view_count|numberformat }}</p>
276

277
<!-- Time differences -->
278
<p>Posted {{ post.created_at|timedeltaformat }} ago</p>
279
```