pendulumPendulum is a Python library that aims to be a drop-in replacement for the built-in `datetime` module, as well as for other libraries like `arrow`. It provides a more intuitive and robust API for handling dates and times, with a strong focus on simplifying common operations and addressing the complexities of timezones.
Key features of Pendulum include:
1. Timezone Awareness by Default: Unlike `datetime`, Pendulum objects are always timezone-aware, significantly reducing common bugs related to naive datetimes.
2. Simplified Manipulation: Operations like adding or subtracting durations (e.g., years, months, days, hours, minutes) are straightforward and readable.
3. Robust Parsing: It offers powerful parsing capabilities for various date and time string formats, often without needing explicit format strings.
4. Fluent API: Chaining methods together allows for expressive and concise code.
5. Periods and Intervals: Easily calculate and represent durations or time spans between two points.
6. Immutable Objects: All Pendulum datetime objects are immutable, ensuring that operations return new instances rather than modifying existing ones, which helps prevent side effects.
7. Compatibility: It integrates well with the standard `datetime` module; Pendulum objects can often be used where `datetime` objects are expected.
Pendulum is particularly useful for applications requiring precise timezone handling, complex date arithmetic, or clean parsing of various date string inputs, making date and time management less error-prone and more enjoyable for developers.
Example Code
import pendulum
1. Getting the current time (timezone-aware)
now = pendulum.now()
print(f"Current time: {now}")
print(f"Current timezone: {now.timezone.name}")
2. Creating a specific datetime (with timezone)
date_in_london = pendulum.datetime(2023, 10, 26, 10, 30, 0, tz='Europe/London')
print(f"Date in London: {date_in_london}")
3. Converting to a different timezone
date_in_nyc = date_in_london.in_tz('America/New_York')
print(f"Date in New York: {date_in_nyc}")
4. Parsing a date string
parsed_date = pendulum.parse('2023-01-15 14:00:00 EST')
print(f"Parsed date: {parsed_date}")
5. Adding and subtracting time
next_week = now.add(weeks=1)
print(f"Next week: {next_week}")
last_month = now.subtract(months=1)
print(f"Last month: {last_month}")
6. Calculating the difference between two datetimes
diff = date_in_nyc - date_in_london This might not be intuitive due to timezone conversion
print(f"Difference (date_in_nyc - date_in_london): {diff}")
diff_seconds = date_in_nyc.diff(date_in_london).in_seconds()
print(f"Difference in seconds: {diff_seconds}")
7. Getting start/end of a time unit
start_of_day = now.start_of('day')
print(f"Start of today: {start_of_day}")
end_of_month = now.end_of('month')
print(f"End of this month: {end_of_month}")
8. Formatting a datetime
formatted_date = now.format('dddd, MMMM Do YYYY [at] h:mm:ss A ZZZ')
print(f"Formatted date: {formatted_date}")
9. Working with periods
christmas_2023 = pendulum.datetime(2023, 12, 25, tz='UTC')
new_year_2024 = pendulum.datetime(2024, 1, 1, tz='UTC')
period = pendulum.period(christmas_2023, new_year_2024)
print(f"Period between Christmas and New Year: {period.in_days()} days")
print(f"Contains December 28th? {period.contains(pendulum.datetime(2023, 12, 28, tz='UTC'))}")