{"id":5311,"library":"maya","title":"Maya: Datetimes for Humans","description":"Maya is a Python library designed to make working with datetimes significantly easier and more intuitive. It wraps Python's built-in `datetime` module, providing a human-friendly API that simplifies common tasks such as parsing diverse date strings, handling timezones, and converting between various time representations. It aims to eliminate common pitfalls like distinguishing between naive and aware datetimes. The current version is 0.6.1, and while releases are infrequent, the project is actively maintained to address user issues.","status":"active","version":"0.6.1","language":"en","source_language":"en","source_url":"https://github.com/kennethreitz/maya","tags":["datetime","timezone","parsing","human-friendly","time"],"install":[{"cmd":"pip install maya","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Powers Maya's date parsing capabilities.","package":"pendulum","optional":false},{"reason":"Likely used for robust string parsing, as indicated by GitHub issues.","package":"dateparser","optional":false}],"imports":[{"symbol":"maya","correct":"import maya"}],"quickstart":{"code":"import maya\n\n# Get the current time\nnow = maya.now()\nprint(f\"Current time: {now}\")\n\n# Parse anything\ndate_obj = maya.parse(\"tomorrow\")\nprint(f\"'Tomorrow' parsed: {date_obj.slang_date()}, {date_obj.slang_time()}\")\n\n# Convert to a specific timezone\nla_time = now.datetime(to_timezone=\"America/Los_Angeles\")\nprint(f\"Current time in LA: {la_time}\")\n\n# Generate time intervals\nstart = maya.when(\"2024-01-01\")\nend = maya.when(\"2024-01-03\")\nprint(\"Days in interval:\")\nfor day in maya.intervals(start=start, end=end, interval=60*60*24):\n    print(f\"- {day.slang_date()}\")","lang":"python","description":"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()`."},"warnings":[{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"<= 0.5.0, potentially later versions with specific `pendulum` releases."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions in minimal environments"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}