Pendulum

https://pendulum.eustace.io/docs/
Admin
Pendulum is a Python package that eases datetime manipulation with drop-in replacements for native...
Tokens:21,072
Snippets:155
Trust Score:7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Pendulum via poetry

Source: https://pendulum.eustace.io/docs

Installation command for users managing dependencies with poetry.

```bash
$ poetry add pendulum
```

--------------------------------

### Install Pendulum with test features via poetry

Source: https://pendulum.eustace.io/docs

Install Pendulum including the optional test helpers using poetry.

```bash
$ poetry add pendulum[test]
```

--------------------------------

### Install Pendulum via pip

Source: https://pendulum.eustace.io/docs

Standard installation command for the Pendulum package.

```bash
$ pip install pendulum
```

--------------------------------

### Install Pendulum with test features via pip

Source: https://pendulum.eustace.io/docs

Install Pendulum including the optional test helpers.

```bash
$ pip install pendulum[test]
```

--------------------------------

### Use helper methods for date checks

Source: https://pendulum.eustace.io/docs

Examples of helper methods like is_past, is_leap_year, and is_birthday. Methods comparing to now() use the instance's timezone.

```python
>>> import pendulum

>>> dt = pendulum.now()

>>> dt.is_past()
>>> dt.is_leap_year()

>>> born = pendulum.datetime(1987, 4, 23)
>>> not_birthday = pendulum.datetime(2014, 9, 26)
>>> birthday = pendulum.datetime(2014, 4, 23)
>>> past_birthday = pendulum.now().subtract(years=50)

>>> born.is_birthday(not_birthday)
False
>>> born.is_birthday(birthday)
True
>>> past_birthday.is_birthday()
# Compares to now by default
True
```

--------------------------------

### Create a DateTime instance for the current time

Source: https://pendulum.eustace.io/docs

Using the now method to get the current time, optionally specifying a timezone.

```python
>>> import pendulum

>>> now = pendulum.now()

>>> now_in_london_tz = pendulum.now('Europe/London')
>>> now_in_london_tz.timezone_name
'Europe/London'
```

--------------------------------

### Calculate total duration in specific units

Source: https://pendulum.eustace.io/docs

Use total methods to get the duration as a float in a specific unit.

```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
```

--------------------------------

### Instantiating an Interval

Source: https://pendulum.eustace.io/docs

Demonstrates creating an Interval instance using the interval() helper.

```python
>>> import pendulum

>>> start = pendulum.datetime(2000, 1, 1)
>>> end = pendulum.datetime(2000, 1, 31)

>>> interval = pendulum.interval(start, end)
```

--------------------------------

### Format DateTime instances as strings

Source: https://pendulum.eustace.io/docs

Demonstrates basic string conversion, common date/time string methods, and custom formatting using format() and strftime().

```python
>>> import pendulum

>>> dt = pendulum.datetime(1975, 12, 25, 14, 15, 16)
>>> print(dt)
'1975-12-25T14:15:16+00:00'

>>> dt.to_date_string()
'1975-12-25'

>>> dt.to_formatted_date_string()
'Dec 25, 1975'

>>> dt.to_time_string()
'14:15:16'

>>> dt.to_datetime_string()
'1975-12-25 14:15:16'

>>> dt.to_day_datetime_string()
'Thu, Dec 25, 1975 2:15 PM'

# You can also use the format() method
>>> dt.format('dddd Do [of] MMMM YYYY HH:mm:ss A')
'Thursday 25th of December 1975 02:15:16 PM'

# Of course, the strftime method is still available
>>> dt.strftime('%A %-d%t of %B %Y %I:%M:%S %p')
'Thursday 25th of December 1975 02:15:16 PM'
```

--------------------------------

### Calculate truncated duration in specific units

Source: https://pendulum.eustace.io/docs

Use in_xxx methods to get the total duration 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
```

--------------------------------

### Create a DateTime instance with datetime()

Source: https://pendulum.eustace.io/docs

Basic usage of the datetime helper to create a UTC instance.

```python
>>> import pendulum

>>> dt = pendulum.datetime(2015, 2, 5)
>>> isinstance(dt, datetime)
True
>>> dt.timezone.name
'UTC'
```

--------------------------------

### Create static date instances

Source: https://pendulum.eustace.io/docs

Using helpers like today, tomorrow, and yesterday to create instances with time set to 00:00:00.

```python
>>> now = pendulum.now()
>>> print(now)
'2016-06-28T16:51:45.978473-05:00'

>>> today = pendulum.today()
>>> print(today)
'2016-06-28T00:00:00-05:00'

>>> tomorrow = pendulum.tomorrow('Europe/London')
>>> print(tomorrow)
'2016-06-29T00:00:00+01:00'

>>> yesterday = pendulum.yesterday()
>>> print(yesterday)
'2016-06-27T00:00:00-05:00'
```

--------------------------------

### Format duration as words

Source: https://pendulum.eustace.io/docs

Use in_words() to get a human-readable string representation of the duration, supporting multiple locales.

```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'
```

--------------------------------

### Creating an inverted Interval

Source: https://pendulum.eustace.io/docs

Shows how to create an inverted interval and how to use the absolute keyword argument to ensure a positive interval.

```python
>>> interval = pendulum.interval(end, start)
>>> interval.remaining_days
-2

>>> interval = pendulum.interval(end, start, absolute=True)
>>> interval.remaining_days
2
```

--------------------------------

### Using dst_rule for transition control

Source: https://pendulum.eustace.io/docs

Shows how to use the dst_rule keyword argument to explicitly handle transition rules instead of relying on the fold attribute.

```python
>>> import pendulum

>>> dt = datetime(2013, 3, 31, 2, 30)
# By default, fold is set to 0
>>> dt = paris.convert(dt, dst_rule=pendulum.PRE_TRANSITION)
>>> dt.isoformat()
'2013-03-31T01:30:00+01:00'

>>> dt = paris.convert(dt, dst_rule=pendulum.POST_TRANSITION)
>>> dt.isoformat()
'2013-03-31T03:30:00+02:00'

>>> paris.convert(dt, dst_rule=pendulum.TRANSITION_ERROR)
# NonExistingTime: The datetime 2013-03-31 02:30:00 does not exist
```

--------------------------------

### Create a local DateTime instance

Source: https://pendulum.eustace.io/docs

The local helper automatically sets the timezone to the system's local timezone.

```python
>>> import pendulum

>>> dt = pendulum.local(2015, 2, 5)
>>> print(dt.timezone.name)
'America/Toronto'
```

--------------------------------

### Controlling Normalization Behavior

Source: https://pendulum.eustace.io/docs

Shows how to use dst_rule parameters like pendulum.PRE_TRANSITION and pendulum.TRANSITION_ERROR to handle non-existent or ambiguous times.

```python
>>> import pendulum

>>> pendulum.datetime(2013, 3, 31, 2, 30, 0, 0, tz='Europe/Paris',
                      dst_rule=pendulum.PRE_TRANSITION)
'2013-03-31T01:30:00+01:00'
>>> pendulum.datetime(2013, 10, 27, 2, 30, 0, 0, tz='Europe/Paris',
                      dst_rule=pendulum.PRE_TRANSITION)
'2013-10-27T02:30:00+02:00'

>>> pendulum.datetime(2013, 3, 31, 2, 30, 0, 0, tz='Europe/Paris',
                      dst_rule=pendulum.TRANSITION_ERROR)
# NonExistingTime: The datetime 2013-03-31 02:30:00 does not exist
>>> pendulum.datetime(2013, 10, 27, 2, 30, 0, 0, tz='Europe/Paris',
                      dst_rule=pendulum.TRANSITION_ERROR)
# AmbiguousTime: The datetime 2013-10-27 02:30:00 is ambiguous.
```

--------------------------------

### Accessing Interval properties

Source: https://pendulum.eustace.io/docs

Demonstrates how subtracting two DateTime instances creates an Interval and how to access its specific properties like years, months, and weeks.

```python
>>> import pendulum

>>> start = pendulum.datetime(2000, 11, 20)
>>> end = pendulum.datetime(2016, 11, 5)

>>> interval = end - start

>>> interval.years
15
>>> interval.months
11
>>> interval.in_years()
15
>>> interval.in_months()
191

# Note that the weeks property
# will change compared to the Duration class
>>> interval.weeks
2 # 832 for the duration

# However the days property will still remain the same
# to keep the compatibility with the timedelta class
>>> interval.days
5829
```

--------------------------------

### Create a DateTime instance from a format string

Source: https://pendulum.eustace.io/docs

Using from_format to parse a string into a DateTime instance based on custom tokens.

```python
>>> dt = pendulum.from_format('1975-05-21 22', 'YYYY-MM-DD HH')
>>> print(dt)
'1975-05-21T22:00:00+00:00'
```

--------------------------------

### Create a naive DateTime instance

Source: https://pendulum.eustace.io/docs

Use the naive helper to create a DateTime object without timezone information.

```python
>>> import pendulum

>>> naive = pendulum.naive(2015, 2, 5)
>>> naive.timezone
None
```

--------------------------------

### Localize date formatting with format()

Source: https://pendulum.eustace.io/docs

Use the locale keyword within the format() method to output dates in specific languages.

```python
>>> import pendulum

>>> dt = pendulum.datetime(1975, 5, 21)
>>> dt.format('dddd DD MMMM YYYY', locale='de')
'Mittwoch 21 Mai 1975'

>>> dt.format('dddd DD MMMM YYYY')
'Wednesday 21 May 1975'
```

--------------------------------

### Use the Pendulum formatter

Source: https://pendulum.eustace.io/docs

The format() method provides an intuitive way to format dates using specific tokens.

```python
>>> import pendulum

>>> dt = pendulum.datetime(1975, 12, 25, 14, 15, 16)
>>> dt.format('YYYY-MM-DD HH:mm:ss')
'1975-12-25 14:15:16'
```

--------------------------------

### Create a DateTime instance from a unix timestamp

Source: https://pendulum.eustace.io/docs

Using from_timestamp to convert a unix timestamp into a DateTime instance.

```python
>>> dt = pendulum.from_timestamp(-1)
>>> print(dt)
'1969-12-31T23:59:59+00:00'

>>> dt  = pendulum.from_timestamp(-1, tz='Europe/London')
>>> print(dt)
'1970-01-01T00:59:59+01:00'
```

--------------------------------

### Create a DateTime instance from a native datetime

Source: https://pendulum.eustace.io/docs

Using the instance function to convert a native datetime.datetime object to a Pendulum DateTime instance.

```python
>>> dt = datetime(2008, 1, 1)
>>> p = pendulum.instance(dt)
>>> print(p)
'2008-01-01T00:00:00+00:00'
```

--------------------------------

### Handling DST transitions with Interval

Source: https://pendulum.eustace.io/docs

Shows how Interval properties like remaining_days account for DST transitions, unlike standard timedelta attributes.

```python
>>> import pendulum

>>> start = pendulum.datetime(2017, 3, 7, tz='America/Toronto')
>>> end = start.add(days=6)

>>> interval = end - start

# timedelta properties
>>> interval.days
5
>>> interval.seconds
82800

# interval properties
>>> interval.remaining_days
6
>>> interval.hours
0
>>> interval.remaining_seconds
0
```

--------------------------------

### Compare datetime instances with operators

Source: https://pendulum.eustace.io/docs

Demonstrates using standard comparison operators on datetime objects. Note that comparisons are performed in the UTC timezone.

```python
>>> import pendulum

>>> first = pendulum.datetime(2012, 9, 5, 23, 26, 11, 0, tz='America/Toronto')
>>> second = pendulum.datetime(2012, 9, 5, 20, 26, 11, 0, tz='America/Vancouver')

>>> first.to_datetime_string()
'2012-09-05 23:26:11'
>>> first.timezone_name
'America/Toronto'
>>> second.to_datetime_string()
'2012-09-05 20:26:11'
>>> second.timezone_name
'America/Vancouver'

>>> first == second
True
>>> first != second
False
>>> first > second
False
>>> first >= second
True
>>> first < second
False
>>> first <= second
True

>>> first = first.on(2012, 1, 1).at(0, 0, 0)
>>> second = second.on(2012, 1, 1).at(0, 0, 0)
# tz is still America/Vancouver for second

>>> first == second
False
>>> first != second
True
>>> first > second
False
>>> first >= second
False
>>> first < second
True
>>> first <= second
True
```

--------------------------------

### Handling timedelta with standard datetime

Source: https://pendulum.eustace.io/docs

Illustrates the limitations of using standard timedelta with converted datetime objects and how to re-normalize.

```python
>>> from datetime import datetime, timedelta
>>> from pendulum import timezone

>>> dt = datetime(2013, 3, 31, 1, 59, 59, 999999)
>>> dt = paris.convert(dt)
>>> dt.isoformat()
'2013-03-31T01:59:59.999999+01:00'
>>> dt = dt + timedelta(microseconds=1)
>>> dt.isoformat()
'2013-03-31T02:00:00+01:00'
```

```python
>>> dt = tz.convert(dt)
>>> dt.isoformat()
'2013-03-31T03:00:00+02:00'
```

--------------------------------

### Iterating over an Interval with range

Source: https://pendulum.eustace.io/docs

Demonstrates using the range() method to iterate over an interval by a specific unit.

```python
>>> import pendulum

>>> start = pendulum.datetime(2000, 1, 1)
>>> end = pendulum.datetime(2000, 1, 10)

>>> interval = pendulum.interval(start, end)

>>> for dt in interval.range('days'):
>>>     print(dt)

'2000-01-01T00:00:00+00:00'
'2000-01-02T00:00:00+00:00'
'2000-01-03T00:00:00+00:00'
'2000-01-04T00:00:00+00:00'
'2000-01-05T00:00:00+00:00'
'2000-01-06T00:00:00+00:00'
'2000-01-07T00:00:00+00:00'
'2000-01-08T00:00:00+00:00'
'2000-01-09T00:00:00+00:00'
'2000-01-10T00:00:00+00:00'
```

--------------------------------

### Shifting time across transitions

Source: https://pendulum.eustace.io/docs

Demonstrates how Pendulum handles time arithmetic across daylight saving time transitions by maintaining context.

```python
>>> import pendulum

>>> dt = pendulum.datetime(2013, 3, 31, 1, 59, 59, 999999,
                           tz='Europe/Paris')
'2013-03-31T01:59:59.999999+01:00'
>>> dt = dt.add(microseconds=1)
'2013-03-31T03:00:00+02:00'
>>> dt.subtract(microseconds=1)
'2013-03-31T01:59:59.999999+01:00'

>>> dt = pendulum.datetime(2013, 10, 27, 2, 59, 59, 999999,
                           tz='Europe/Paris',
                           dst_rule=pendulum.PRE_TRANSITION)
'2013-10-27T02:59:59.999999+02:00'
>>> dt = dt.add(microseconds=1)
'2013-10-27T02:00:00+01:00'
>>> dt = dt.subtract(microseconds=1)
'2013-10-27T02:59:59.999999+02:00'
```

--------------------------------

### Parsing basic date strings with pendulum.parse

Source: https://pendulum.eustace.io/docs

Demonstrates parsing standard ISO 8601 strings and specifying a timezone using the tz keyword.

```python
>>> import pendulum

>>> dt = pendulum.parse('1975-05-21T22:00:00')
>>> print(dt)
'1975-05-21T22:00:00+00:00

# You can pass a tz keyword to specify the timezone
>>> dt = pendulum.parse('1975-05-21T22:00:00', tz='Europe/Paris')
>>> print(dt)
'1975-05-21T22:00:00+01:00'

# Not ISO 8601 compliant but common
>>> dt = pendulum.parse('1975-05-21 22:00:00')
```

--------------------------------

### Access native properties for Duration

Source: https://pendulum.eustace.io/docs

Native methods and properties provide approximations for compatibility when years or months are used.

```python
>>> it.days
820

>>> it.total_seconds()
70848000.0
```

--------------------------------

### Instantiate a Duration

Source: https://pendulum.eustace.io/docs

Create a Duration instance using the pendulum.duration helper.

```python
>>> import pendulum

>>> it = pendulum.duration(days=1177, seconds=7284, microseconds=1234)
```

--------------------------------

### Normalizing datetime with Timezone.datetime

Source: https://pendulum.eustace.io/docs

Shows how to obtain a normalized datetime object directly from a Timezone instance.

```python
>>> import pendulum

>>> tz = pendulum.timezone('Europe/Paris')
>>> dt = tz.datetime(2013, 3, 31, 2, 30)
>>> dt.isoformat()
'2013-03-31T03:30:00+02:00'
```

--------------------------------

### Direct iteration over an Interval

Source: https://pendulum.eustace.io/docs

Demonstrates that iterating directly over an Interval instance defaults to a unit of days.

```python
>>> for dt in interval:
>>>     print(dt)
```

--------------------------------

### Compare datetimes with timezones

Source: https://pendulum.eustace.io/docs

Demonstrates calculating the difference in hours between two datetimes in different timezones.

```python
>>> import pendulum

>>> dt_toronto = pendulum.datetime(2012, 1, 1, tz='America/Toronto')
>>> dt_vancouver = pendulum.datetime(2012, 1, 1, tz='America/Vancouver')

>>> print(dt_vancouver.diff(dt_toronto).in_hours())
3
```

--------------------------------

### Using Pendulum modifier methods

Source: https://pendulum.eustace.io/docs

Demonstrates the use of start_of, end_of, next, previous, and average methods to modify date and time instances.

```python
>>> import pendulum

>>> dt = pendulum.datetime(2012, 1, 31, 12, 0, 0)

>>> dt.start_of('day')
'2012-01-31 00:00:00'

>>> dt.end_of('day')
'2012-01-31 23:59:59'

>>> dt.start_of('month')
'2012-01-01 00:00:00'

>>> dt.end_of('month')
'2012-01-31 23:59:59'

>>> dt.start_of('year')
'2012-01-01 00:00:00'

>>> dt.end_of('year')
'2012-12-31 23:59:59'

>>> dt.start_of('decade')
'2010-01-01 00:00:00'

>>> dt.end_of('decade')
'2019-12-31 23:59:59'

>>> dt.start_of('century')
'2000-01-01 00:00:00'

>>> dt.end_of('century')
'2099-12-31 23:59:59'

>>> dt.start_of('week')
'2012-01-30 00:00:00'
>>> dt.day_of_week == pendulum.MONDAY
True # ISO8601 week starts on Monday

>>> dt.end_of('week')
'2012-02-05 23:59:59'
>>> dt.day_of_week == pendulum.SUNDAY
True # ISO8601 week ends on SUNDAY

>>> dt.next(pendulum.WEDNESDAY)
'2012-02-01 00:00:00'
>>> dt.day_of_week == pendulum.WEDNESDAY
True

>>> dt = pendulum.datetime(2012, 1, 1, 12, 0, 0)
dt.next()
'2012-01-08 00:00:00'
>>> dt.next(keep_time=True)
'2012-01-08T12:00:00+00:00'

>>> dt = pendulum.datetime(2012, 1, 31, 12, 0, 0)
>>> dt.previous(pendulum.WEDNESDAY)
'2012-01-25 00:00:00'
>>> dt.day_of_week == pendulum.WEDNESDAY
True

>>> dt = pendulum.datetime(2012, 1, 1, 12, 0, 0)
>>> dt.previous()
'2011-12-25 00:00:00'
>>> dt.previous(keep_time=True)
'2011-12-25 12:00:00'

>>> start = pendulum.datetime(2014, 1, 1)
>>> end = pendulum.datetime(2014, 1, 30)
>>> start.average(end)
'2014-01-15 12:00:00'

# others that are defined that are similar
# and tha accept month, quarter and year units
# first_of(), last_of(), nth_of()
```

--------------------------------

### Create a DateTime instance from a format string with timezone

Source: https://pendulum.eustace.io/docs

Specifying a timezone when using from_format.

```python
>>> dt = pendulum.from_format('1975-05-21 22', 'YYYY-MM-DD HH', tz='Europe/London')
'1975-05-21T22:00:00+01:00'
```

--------------------------------

### Display common date formats

Source: https://pendulum.eustace.io/docs

Methods to display a DateTime instance using common standard formats like Atom, ISO8601, and RFC variants.

```python
>>> import pendulum

>>> dt = pendulum.now()

>>> dt.to_atom_string()
'1975-12-25T14:15:16-05:00'

>>> dt.to_cookie_string()
'Thursday, 25-Dec-1975 14:15:16 EST'

>>> dt.to_iso8601_string()
'1975-12-25T14:15:16-0500'

>>> dt.to_rfc822_string()
'Thu, 25 Dec 75 14:15:16 -0500'

>>> dt.to_rfc850_string()
'Thursday, 25-Dec-75 14:15:16 EST'

>>> dt.to_rfc1036_string()
'Thu, 25 Dec 75 14:15:16 -0500'

>>> dt.to_rfc1123_string()
'Thu, 25 Dec 1975 14:15:16 -0500'

>>> dt.to_rfc2822_string()
'Thu, 25 Dec 1975 14:15:16 -0500'

>>> dt.to_rfc3339_string()
'1975-12-25T14:15:16-05:00'

>>> dt.to_rss_string()
'Thu, 25 Dec 1975 14:15:16 -0500'

>>> dt.to_w3c_string()
'1975-12-25T14:15:16-05:00'
```

--------------------------------

### Handling non-standard strings with strict=False

Source: https://pendulum.eustace.io/docs

Shows how to use strict=False to fall back on the dateutil parser when encountering non-standard date strings that would otherwise raise a ParserError.

```python
>>> import pendulum

>>> dt = pendulum.parse('31-01-01')
Traceback (most recent call last):
...
ParserError: Unable to parse string [31-01-01]

>>> dt = pendulum.parse('31-01-01', strict=False)
>>> print(dt)
'2031-01-01T00:00:00+00:00'
```

--------------------------------

### Create a DateTime instance with a specific timezone

Source: https://pendulum.eustace.io/docs

Using the tz keyword argument to set a specific timezone using a string or a Timezone instance.

```python
>>> import pendulum

>>> pendulum.datetime(2015, 2, 5, tz='Europe/Paris')
>>> tz = pendulum.timezone('Europe/Paris')
>>> pendulum.datetime(2015, 2, 5, tz=tz)
```

--------------------------------

### Adding and Subtracting Time with Pendulum

Source: https://pendulum.eustace.io/docs

Demonstrates using add() and subtract() with various time units including years, months, days, weeks, hours, minutes, and seconds. Each method returns a new DateTime instance.

```python
>>> import pendulum

>>> dt = pendulum.datetime(2012, 1, 31)

>>> dt.to_datetime_string()
'2012-01-31 00:00:00'

>>> dt = dt.add(years=5)
'2017-01-31 00:00:00'
>>> dt = dt.add(years=1)
'2018-01-31 00:00:00'
>>> dt = dt.subtract(years=1)
'2017-01-31 00:00:00'
>>> dt = dt.subtract(years=5)
'2012-01-31 00:00:00'

>>> dt = dt.add(months=60)
'2017-01-31 00:00:00'
>>> dt = dt.add(months=1)
'2017-02-28 00:00:00'
>>> dt = dt.subtract(months=1)
'2017-01-28 00:00:00'
>>> dt = dt.subtract(months=60)
'2012-01-28 00:00:00'

>>> dt = dt.add(days=29)
'2012-02-26 00:00:00'
>>> dt = dt.add(days=1)
'2012-02-27 00:00:00'
>>> dt = dt.subtract(days=1)
'2012-02-26 00:00:00'
>>> dt = dt.subtract(days=29)
'2012-01-28 00:00:00'

>>> dt = dt.add(weeks=3)
'2012-02-18 00:00:00'
>>> dt = dt.add(weeks=1)
'2012-02-25 00:00:00'
>>> dt = dt.subtract(weeks=1)
'2012-02-18 00:00:00'
>>> dt = dt.subtract(weeks=3)
'2012-01-28 00:00:00'

>>> dt = dt.add(hours=24)
'2012-01-29 00:00:00'
>>> dt = dt.add(hours=1)
'2012-02-25 01:00:00'
>>> dt = dt.subtract(hours=1)
'2012-02-29 00:00:00'
>>> dt = dt.subtract(hours=24)
'2012-01-28 00:00:00'

>>> dt = dt.add(minutes=61)
'2012-01-28 01:01:00'
>>> dt = dt.add(minutes=1)
'2012-01-28 01:02:00'
>>> dt = dt.subtract(minutes=1)
'2012-01-28 01:01:00'
>>> dt = dt.subtract(minutes=24)
'2012-01-28 00:00:00'

>>> dt = dt.add(seconds=61)
'2012-01-28 00:01:01'
>>> dt = dt.add(seconds=1)
'2012-01-28 00:01:02'
>>> dt = dt.subtract(seconds=1)
'2012-01-28 00:01:01'
>>> dt = dt.subtract(seconds=61)
'2012-01-28 00:00:00'

>>> dt = dt.add(years=3, months=2, days=6, hours=12, minutes=31, seconds=43)
'2015-04-03 12:31:43'
>>> dt = dt.subtract(years=3, months=2, days=6, hours=12, minutes=31, seconds=43)
'2012-01-28 00:00:00'
```

--------------------------------

### Using time travel as a context manager

Source: https://pendulum.eustace.io/docs

Use time travel helpers as a context manager to automatically return to the present after the block executes.

```python
>>> import pendulum

>>> now = pendulum.now()
>>> with pendulum.travel(minutes=5, freeze=True):
>>>     pendulum.now().diff_for_humans(now)
"5 minutes after"
>>> pendulum.now().diff_for_humans(now)
"a few seconds after"
```

--------------------------------

### Compare Duration and timedelta behavior

Source: https://pendulum.eustace.io/docs

Demonstrates how Pendulum's Duration class avoids native normalization for more intuitive results compared to the standard datetime.timedelta.

```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
```

--------------------------------

### Compare set() and in_tz() for timezone handling

Source: https://pendulum.eustace.io/docs

Use set() to modify timezone information without conversion, and in_tz() to convert the time to the target timezone.

```python
>>> import pendulum

>>> dt = pendulum.datetime(2013, 3, 31, 2, 30)
>>> print(dt)
'2013-03-31T02:30:00+00:00'

>>> dt = dt.set(tz='Europe/Paris')
>>> print(dt)
'2013-03-31T03:30:00+02:00'

>>> dt = dt.in_tz('Europe/Paris')
>>> print(dt)
'2013-03-31T04:30:00+02:00'

>>> dt = dt.set(tz='Europe/Paris').set(tz='UTC')
>>> print(dt)
'2013-03-31T03:30:00+00:00'

>>> dt = dt.in_tz('Europe/Paris').in_tz('UTC')
>>> print(dt)
'2013-03-31T02:30:00+00:00'
```

--------------------------------

### Controlling range gap length

Source: https://pendulum.eustace.io/docs

Shows how to pass an amount to the range() method to control the length of the gap between iterations.

```python
>>> for dt in interval.range('days', 2):
>>>     print(dt)

'2000-01-01T00:00:00+00:00'
'2000-01-03T00:00:00+00:00'
'2000-01-05T00:00:00+00:00'
'2000-01-07T00:00:00+00:00'
'2000-01-09T00:00:00+00:00'
```

--------------------------------

### Checking membership in an Interval

Source: https://pendulum.eustace.io/docs

Shows how to use the in keyword to check if a DateTime instance falls within an Interval.

```python
>>> dt = pendulum.datetime(2000, 1, 4)
>>> dt in interval
True
```

--------------------------------

### Register sqlite3 adapter for Pendulum DateTime

Source: https://pendulum.eustace.io/docs

Registers a custom adapter for sqlite3 to correctly handle Pendulum DateTime objects by using the isoformat method.

```python
import pendulum
from sqlite3 import register_adapter

register_adapter(pendulum.DateTime, lambda val: val.isoformat(' '))
```

--------------------------------

### Switching timezones with in_timezone and in_tz

Source: https://pendulum.eustace.io/docs

Shows how to change the timezone of a DateTime instance using the in_timezone() method or its concise alias in_tz().

```python
>>> in_paris = pendulum.datetime(2016, 8, 7, 22, 24, 30, tz='Europe/Paris')
'2016-08-07T22:24:30+02:00'
>>> in_paris.in_timezone('America/New_York')
'2016-08-07T16:24:30-04:00'
>>> in_paris.in_tz('Asia/Tokyo')
'2016-08-08T05:24:30+09:00'
```

--------------------------------

### Using timezone library with standard datetime objects

Source: https://pendulum.eustace.io/docs

Demonstrates using the Pendulum timezone library with standard Python datetime objects, utilizing the fold attribute for transition rules.

```python
>>> from datetime import datetime
>>> from pendulum import timezone

>>> paris = timezone('Europe/Paris')
>>> dt = datetime(2013, 3, 31, 2, 30)
# By default, fold is set to 0
>>> dt = paris.convert(dt)
>>> dt.isoformat()
'2013-03-31T01:30:00+01:00'

>>> dt = datetime(2013, 3, 31, 2, 30, fold=1)
>>> dt = paris.convert(dt)
>>> dt.isoformat()
'2013-03-31T03:30:00+02:00'
```

--------------------------------

### Access Duration properties and methods

Source: https://pendulum.eustace.io/docs

Retrieve specific units from a Duration instance, including years, months, and remaining days or seconds.

```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
```

--------------------------------

### Modify date and time with on() and at()

Source: https://pendulum.eustace.io/docs

The on() and at() methods provide a fluent interface to change the date and time respectively.

```python
>>> dt.on(1975, 5, 21).at(22, 32, 5).to_datetime_string()
'1975-05-21 22:32:05'

>>> dt.at(10).to_datetime_string()
'2016-11-16 10:00:00'

>>> dt.at(10, 30).to_datetime_string()
'2016-11-16 10:30:00'
```
Tokens:
Raw