arrowThe 'arrow' library is a Python package that offers a sensible, human-friendly approach to creating, manipulating, formatting, and converting dates and times. It aims to be a drop-in replacement for Python's built-in `datetime` module, but with many usability improvements, particularly around timezone handling and common operations.
Key features and benefits of the `arrow` library include:
1. Simplicity: It simplifies date and time handling with a cleaner, more intuitive API compared to the standard `datetime` module.
2. Timezone Awareness: All `arrow` objects are timezone-aware by default. It makes it easy to convert between timezones without complex `pytz` interactions.
3. Flexible Creation: You can create `arrow` objects from various inputs, including integers (timestamps), strings (parsed intelligently), or by specifying individual date/time components.
4. Fluent API for Manipulation: It provides methods for adding, subtracting, replacing, and shifting time components (years, months, days, hours, etc.) in a chained, readable manner.
5. Formatting and Parsing: Easy-to-use methods for formatting dates into strings and parsing strings into `arrow` objects, supporting common patterns.
6. Humanization: A unique feature to describe time differences (deltas) in a human-readable format (e.g., 'an hour ago', 'in 3 days').
7. Isos Ranging: Convenient methods for generating date ranges (e.g., all days in a month, all hours in a day).
In essence, `arrow` abstracts away many of the common frustrations with `datetime`, making date and time operations more enjoyable and less error-prone for developers.
Example Code
import arrow
1. Create Arrow objects
Current local time
now = arrow.now()
print(f"Current local time: {now}")
Current UTC time
utc_now = arrow.utcnow()
print(f"Current UTC time: {utc_now}")
From a string (parsed intelligently)
date_str = "2023-10-27 14:30:00 EST"
some_date = arrow.get(date_str)
print(f"From string '{date_str}': {some_date}")
From specific components
specific_date = arrow.get(2024, 7, 15, 10, 0, 0, tzinfo='America/New_York')
print(f"From components: {specific_date}")
2. Timezone conversion
Convert to a different timezone
la_time = some_date.to('America/Los_Angeles')
print(f"'{date_str}' in LA time: {la_time}")
Convert to UTC
utc_converted = some_date.to('UTC')
print(f"'{date_str}' in UTC: {utc_converted}")
3. Manipulation (add, subtract, replace)
Add 3 days and 2 hours
future_date = now.shift(days=3, hours=2)
print(f"3 days and 2 hours from now: {future_date}")
Subtract 1 month
past_date = now.shift(months=-1)
print(f"1 month ago: {past_date}")
Replace year and day
replaced_date = now.replace(year=2025, day=1)
print(f"Replaced year to 2025 and day to 1: {replaced_date}")
4. Formatting and Parsing
Format using a common string format
formatted_date = now.format("YYYY-MM-DD HH:mm:ss ZZZ")
print(f"Formatted date: {formatted_date}")
Format using a predefined constant
iso_format = now.format('YYYY-MM-DDTHH:mm:ssZZ')
print(f"ISO formatted date: {iso_format}")
Parsing with a specified format (if needed for ambiguous strings)
date_string_custom = "10/27/2023 2:30 PM"
parsed_custom = arrow.get(date_string_custom, "MM/DD/YYYY h:mm A")
print(f"Parsed custom string: {parsed_custom}")
5. Humanization
Time difference (delta) from now
two_hours_ago = now.shift(hours=-2)
print(f"Humanized '{two_hours_ago}' vs now: {two_hours_ago.humanize()}")
in_five_days = now.shift(days=5)
print(f"Humanized '{in_five_days}' vs now: {in_five_days.humanize()}")
Difference between two specific dates
delta_humanized = specific_date.humanize(locale='es') Example with locale
print(f"Humanized '{specific_date}' vs now (Spanish): {delta_humanized}")
6. Ranging (iterate over a period)
print("\nHours in today (first 3):")
for r in now.span('hour'):
print(r.format('YYYY-MM-DD HH:mm:ss'))
if r.hour == now.hour + 2: Print only a few for brevity
break
print("\nDays in October 2023 (first 3):")
start_of_october = arrow.get(2023, 10, 1)
for r in start_of_october.span('day'):
print(r.format('YYYY-MM-DD'))
if r.day == 3:
break