diff options
Diffstat (limited to 'docs/docs/duration.md')
-rw-r--r-- | docs/docs/duration.md | 177 |
1 files changed, 177 insertions, 0 deletions
diff --git a/docs/docs/duration.md b/docs/docs/duration.md new file mode 100644 index 0000000..0801d9e --- /dev/null +++ b/docs/docs/duration.md @@ -0,0 +1,177 @@ +# Duration + +The `Duration` class is inherited from the native `timedelta` class. +It has many improvements over the base class. + +!!!note + + Even though, it inherits from the `timedelta` class, its behavior is slightly different. + The more important to notice is that the native normalization does not happen, this is so that + it feels more intuitive. + + ```python + >>> import pendulum + >>> from datetime import datetime + + >>> d1 = datetime(2012, 1, 1, 1, 2, 3, tzinfo=pytz.UTC) + >>> d2 = datetime(2011, 12, 31, 22, 2, 3, tzinfo=pytz.UTC) + >>> delta = d2 - d1 + >>> delta.days + -1 + >>> delta.seconds + 75600 + + >>> d1 = pendulum.datetime(2012, 1, 1, 1, 2, 3) + >>> d2 = pendulum.datetime(2011, 12, 31, 22, 2, 3) + >>> delta = d2 - d1 + >>> delta.days + 0 + >>> delta.hours + -3 + ``` + +## Instantiation + +To create a `Duration` instance, you can use the `duration()` helper: + +```python +>>> import pendulum + +>>> it = pendulum.duration(days=1177, seconds=7284, microseconds=1234) +``` + +!!!note + + Unlike the native `timedelta` class, durations support specifying + years and months. + + ```python + >>> import pendulum + + >>> it = pendulum.duration(years=2, months=3) + ``` + + However, to maintain compatibility, native methods and properties will + make approximations: + + ```python + >>> it.days + 820 + + >>> it.total_seconds() + 70848000.0 + ``` + +## Properties and Duration Methods + +The `Duration` class brings more properties than the default `days`, `seconds` and +`microseconds`. + +```python +>>> import pendulum + +>>> it = pendulum.duration( +... years=2, months=3, +... days=1177, seconds=7284, microseconds=1234 +... ) + +>>> it.years +2 +>>> it.months +3 + +# Weeks are based on the total of days +# It does not take into account years and months +>>> it.weeks +168 + +# Days, just like in timedelta, represents the total of days +# in the duration. If years and/or months are specified +# it will use an approximation +>>> it.days +1997 + +# If you want the remaining days not included in full weeks +>>> it.remaining_days +1 + +>>> # The remaining number in each unit +>>> it.hours +2 +>>> it.minutes +1 + +# Seconds are, like days, a special case and the default +# property will return the whole value of remaining +# seconds just like the timedelta class for compatibility +>>> it.seconds +7284 + +# If you want the number of seconds not included +# in hours and minutes +>>> it.remaining_seconds +24 + +>>> it.microseconds +1234 +``` + +If you want to get the duration in each supported unit +you can use the appropriate methods. + +```python +# Each method returns a float like the native +# total_seconds() method +>>> it.total_weeks() +168.15490079569113 + +>>> it.total_days() +1177.0843055698379 + +>>> it.total_hours() +28250.02333367611 + +>>> it.total_minutes() +1695001.4000205665 + +>>> it.total_seconds() +101700084.001234 +``` + +Similarly, the `in_xxx()` methods return the total duration in each +supported unit as a truncated integer. + +```python +>>> it.in_weeks() +168 + +>>> it.in_days() +1997 + +>>> it.in_hours() +28250 + +>>> it.in_minutes() +1695001 + +>>> it.in_seconds() +101700084 +``` + +It also has a handy `in_words()` method, which determines the duration representation when printed. + +```python +>>> import pendulum + +>>> pendulum.set_locale('fr') + +>>> it = pendulum.duration(days=1177, seconds=7284, microseconds=1234) +>>> it.in_words() +'168 semaines 1 jour 2 heures 1 minute 24 secondes' + +>>> print(it) +'168 semaines 1 jour 2 heures 1 minute 24 secondes' + +>>> it.in_words(locale='de') +'168 Wochen 1 Tag 2 Stunden 1 Minute 24 Sekunden' +``` |