Mercurial > babel > mirror
comparison doc/dates.txt @ 394:0ca28858045e trunk
Doc improvements for the new `format_timedelta` function.
| author | cmlenz |
|---|---|
| date | Tue, 15 Jul 2008 12:53:52 +0000 |
| parents | f9f6f740b595 |
| children | a0457635279d |
comparison
equal
deleted
inserted
replaced
| 393:250c7cba8c12 | 394:0ca28858045e |
|---|---|
| 195 | | | should be used regardless of whether they are in | | 195 | | | should be used regardless of whether they are in | |
| 196 | | | common use by the locale. | | 196 | | | common use by the locale. | |
| 197 +----------+--------+--------------------------------------------------------+ | 197 +----------+--------+--------------------------------------------------------+ |
| 198 | 198 |
| 199 | 199 |
| 200 Time Delta Formatting | |
| 201 ===================== | |
| 202 | |
| 203 In addition to providing functions for formatting localized dates and times, | |
| 204 the ``babel.dates`` module also provides a function to format the difference | |
| 205 between two times, called a ''time delta''. These are usually represented as | |
| 206 ``datetime.timedelta`` objects in Python, and it's also what you get when you | |
| 207 subtract one ``datetime`` object from an other. | |
| 208 | |
| 209 The ``format_timedelta`` function takes a ``timedelta`` object and returns a | |
| 210 human-readable representation. This happens at the cost of precision, as it | |
| 211 chooses only the most significant unit (such as year, week, or hour) of the | |
| 212 difference, and displays that: | |
| 213 | |
| 214 .. code-block:: pycon | |
| 215 | |
| 216 >>> from datetime import timedelta | |
| 217 >>> from babel.dates import format_timedelta | |
| 218 >>> delta = timedelta(days=6) | |
| 219 >>> format_timedelta(delta, locale='en_US') | |
| 220 u'1 week' | |
| 221 | |
| 222 The resulting strings are based from the CLDR data, and are properly | |
| 223 pluralized depending on the plural rules of the locale and the calculated | |
| 224 number of units. | |
| 225 | |
| 226 The function provides parameters for you to influence how this most significant | |
| 227 unit is chosen: with ``threshold`` you set the value after which the | |
| 228 presentation switches to the next larger unit, and with ``granularity`` you | |
| 229 can limit the smallest unit to display: | |
| 230 | |
| 231 .. code-block:: pycon | |
| 232 | |
| 233 >>> delta = timedelta(days=6) | |
| 234 >>> format_timedelta(delta, threshold=1.2, locale='en_US') | |
| 235 u'6 days' | |
| 236 >>> format_timedelta(delta, granularity='month', locale='en_US') | |
| 237 u'0 months' | |
| 238 | |
| 239 | |
| 200 Time-zone Support | 240 Time-zone Support |
| 201 ================= | 241 ================= |
| 202 | 242 |
| 203 Many of the verbose time formats include the time-zone, but time-zone | 243 Many of the verbose time formats include the time-zone, but time-zone |
| 204 information is not by default available for the Python ``datetime`` and | 244 information is not by default available for the Python ``datetime`` and |