{"id":5178,"library":"delta","title":"Delta (Duration Parsing)","description":"Delta is a Python library designed for human-friendly, context-aware parsing of duration strings. It allows users to convert natural language descriptions of time durations (e.g., '1 year 2 months and 3 days') into `datetime.timedelta` objects, optionally considering a specific start date for accurate calculations (e.g., for '2 months' relative to January vs. April). The library is currently at version 0.4.2 and appears to have a low release cadence.","status":"maintenance","version":"0.4.2","language":"en","source_language":"en","source_url":"https://github.com/rlgomes/delta","tags":["duration parsing","time","datetime","natural language","utility"],"install":[{"cmd":"pip install delta","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"The primary function for parsing duration strings.","symbol":"delta.parse","correct":"import delta\nfrom datetime import datetime\nduration = delta.parse('1 day')"}],"quickstart":{"code":"import delta\nfrom datetime import datetime\n\n# Parse a duration without a specific context (defaults to current date)\nduration_no_context = delta.parse('1 year 2 months and 3 days')\nprint(f\"Duration without context: {duration_no_context}\")\n\n# Parse a duration with an explicit context date\ncontext_date = datetime(2023, 1, 15) # January 15, 2023\nduration_with_context = delta.parse('1 month and 2 weeks', context_date)\nprint(f\"Duration with context {context_date.strftime('%Y-%m-%d')}: {duration_with_context}\")\n\n# Parse different string formats\nduration_short_form = delta.parse('2y 3m 4w 5d')\nprint(f\"Duration from short form: {duration_short_form}\")","lang":"python","description":"This quickstart demonstrates how to use the `delta.parse()` function to interpret various human-readable duration strings. It shows examples with and without an explicit context date, highlighting how 'context-aware' parsing works for units like months."},"warnings":[{"fix":"Consider testing thoroughly with your specific Python version and use case. For active development, explore alternatives like `pendulum` or `dateutil` if they meet your parsing needs.","message":"The `delta` library appears to be minimally maintained, with the last notable activity on its GitHub repository around 2017. Users should be aware that it may not receive updates for new Python versions, bug fixes, or new features.","severity":"gotcha","affected_versions":"<=0.4.2"},{"fix":"Always provide an explicit `datetime` object as the `context` argument to `delta.parse()` for reproducible and consistent duration calculations, especially when dealing with non-fixed time units like months or years.","message":"When `delta.parse()` is called without an explicit `context` argument, it defaults to the current date. This means that calculations for relative units like '1 month' or '1 year' will vary depending on when the code is executed, leading to non-reproducible results. For example, '1 month' from January 31st is different from '1 month' from February 28th.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure the `context` `datetime` objects are consistent with the expected timezone behavior of your application. If precise timezone handling is critical, consider pre-processing your `datetime` objects or using a library with explicit timezone support.","message":"The library's 'context-aware' parsing of durations for units like 'months' or 'years' relies on Python's `datetime` objects. However, the library does not explicitly handle timezone information in its parsing logic. If your applications involve timezone-aware `datetime` objects or cross daylight saving time boundaries, the calculations might produce unexpected results without careful management of the input `context` `datetime` objects.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Test the library with the full range of expected input strings in your application. Implement robust error handling around `delta.parse()` calls to gracefully manage potential parsing failures.","message":"While designed for 'human-friendly' parsing, highly unusual, ambiguous, or malformed duration strings might lead to unexpected parsing results or unhandled exceptions. The robustness to a very wide variety of informal inputs is not extensively documented.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}