Maya: Datetimes for Humans

Warnings

• gotcha When parsing imprecise dates (e.g., `maya.when('tomorrow')` or '2024-01-15'), Maya typically returns a `MayaDT` object representing 00:00:00 of that day. This may not align with a user's expectation of representing a full day or a time-of-day relative to the current moment.
  Fix: Be explicit with time components if a specific time is desired (e.g., `maya.when('tomorrow 12pm')`), or handle ranges manually if a full-day interval is needed (e.g., `maya.when('2024-01-15').start_of_day()` and `.end_of_day()` if available, or construct `MayaInterval` explicitly).
• gotcha While Maya aims to simplify timezone handling by internally converting all times to UTC for consistent arithmetic, operations like adding a `timedelta` to a `MayaDT` object obtained with a specific `to_timezone` might not correctly account for Daylight Saving Time (DST) transitions in non-UTC timezones. This can lead to off-by-one-hour errors.
  Fix: For precise timezone-aware arithmetic, convert to a `datetime` object with the desired timezone using `MayaDT.datetime(to_timezone='...')` and perform arithmetic there, or ensure operations are explicitly done in UTC before converting back to a local timezone.
• gotcha Older versions of Maya (e.g., v0.4.1) had specific, limited compatibility with `pendulum` versions (e.g., `>= 1.0` and `<= 1.5.1`). While this might be resolved in 0.6.1, unexpected `pendulum` version incompatibilities can still occur during installation or runtime, leading to broken parsing functionality.
  Fix: Check `maya`'s `setup.py` or `pyproject.toml` (if available in a modern release) for current `pendulum` dependency constraints. If encountering issues, try pinning `pendulum` to a known compatible version in your `requirements.txt`.
• gotcha Users have reported that `maya.parse()` may fail to correctly parse some valid ISO 8601 strings or encounter issues with 'certain dates', indicating potential edge cases in its parsing logic.
  Fix: If parsing fails, try providing date strings in common, unambiguous formats (e.g., 'YYYY-MM-DD HH:MM:SSZ') or fall back to Python's standard `datetime.strptime()` if specific formatting is known.
• gotcha Installing `maya` in a `python-slim` Docker container (or similar minimal environments) can fail due to dependencies (specifically `regex`) requiring a C compiler (`gcc`) or Python development headers (`python3.x-dev`) during the wheel building process.
  Fix: Ensure `gcc` and `python3-dev` (or equivalent for your OS/Python version) are installed in the Docker image or environment before attempting `pip install maya`.

Install

• pip install maya Install with pip

Imports

• maya

  import maya

Quickstart

This quickstart demonstrates how to get the current time, parse human-readable date strings, convert datetimes to specific timezones, and generate time intervals using the `maya` library. It showcases the core functionalities of `maya.now()`, `maya.parse()`, `MayaDT.datetime()`, and `maya.intervals()`.

import maya

# Get the current time
now = maya.now()
print(f"Current time: {now}")

# Parse anything
date_obj = maya.parse("tomorrow")
print(f"'Tomorrow' parsed: {date_obj.slang_date()}, {date_obj.slang_time()}")

# Convert to a specific timezone
la_time = now.datetime(to_timezone="America/Los_Angeles")
print(f"Current time in LA: {la_time}")

# Generate time intervals
start = maya.when("2024-01-01")
end = maya.when("2024-01-03")
print("Days in interval:")
for day in maya.intervals(start=start, end=end, interval=60*60*24):
    print(f"- {day.slang_date()}")