{"id":7905,"library":"ago","title":"Ago: Human Readable Timedeltas","description":"Ago is a lightweight Python library, currently at version 0.1.0, designed to convert `datetime` and `timedelta` objects into human-readable strings like '3 hours ago' or 'in 5 days'. It focuses on simplicity and customization of tense and precision. The library is actively maintained, with its latest release in March 2025, and maintains a stable, albeit early-stage, release cadence.","status":"active","version":"0.1.0","language":"en","source_language":"en","source_url":"https://git.unturf.com/python/ago","tags":["time","datetime","timedelta","human-readable","formatting"],"install":[{"cmd":"pip install ago","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The primary function for converting datetime/timedelta objects.","symbol":"human","correct":"from ago import human"},{"note":"Converts a timedelta object into a dictionary of units (e.g., {'year': 1, 'day': 35}).","symbol":"delta2dict","correct":"from ago import delta2dict"}],"quickstart":{"code":"from datetime import datetime, timedelta\nfrom ago import human\n\n# Example with a past datetime object\ndb_date = datetime(year=2023, month=1, day=1, hour=10, minute=30, second=0)\nprint(f'Item created: {human(db_date)}')\n\n# Example with a future timedelta object\nfuture_delta = timedelta(days=5, hours=3, minutes=45)\nprint(f'Task due: {human(future_delta)}')\n\n# Example with custom precision and tense\nlong_ago = datetime(year=2020, month=3, day=15)\nprint(f'Event happened: {human(long_ago, precision=3, past_tense=\"{} since\")}')\n\n# Using delta2dict\ndelta_for_dict = timedelta(days=400, hours=5, minutes=30)\ntime_components = delta2dict(delta_for_dict)\nprint(f'Time components: {time_components}')","lang":"python","description":"This quickstart demonstrates how to use the `human` function to convert `datetime` and `timedelta` objects into human-readable strings, including customizing precision and tense. It also shows the usage of `delta2dict` to break down a `timedelta` into its constituent units."},"warnings":[{"fix":"Always specify `precision` (e.g., `human(subject, precision=3)`) if you require more than two units of time in the output string.","message":"The `human` function's `precision` parameter defaults to `2`, meaning it will only display up to two units (e.g., '1 year, 2 months ago' instead of '1 year, 2 months, 3 days, 4 hours ago'). If more detail is needed, explicitly set a higher `precision` value.","severity":"gotcha","affected_versions":"All versions (0.1.0)"},{"fix":"For multilingual applications, manage the `past_tense` and `future_tense` parameters yourself using an i18n/l10n framework, or consider libraries with explicit localization support if this is a critical requirement.","message":"The `ago` library does not provide built-in localization (e.g., a `locale` parameter for `human()`) for different languages. Implementing internationalization requires manually handling translation of the tense strings (`past_tense`, `future_tense`) or extending the library's logic.","severity":"gotcha","affected_versions":"All versions (0.1.0)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure that any `datetime` objects passed to `ago.human()` are valid `datetime` instances and not `None`. Always validate inputs if they originate from external or potentially unreliable sources.","cause":"This error typically occurs when attempting to calculate a `timedelta` (implicitly or explicitly within `ago`) where one of the `datetime` objects is `None`.","error":"TypeError: unsupported operand type(s) for -: 'datetime.datetime' and 'NoneType'"},{"fix":"Convert string representations of dates or times into `datetime` objects (e.g., using `datetime.strptime()`) or into `timedelta` objects before passing them to `ago.human()`.","cause":"The `ago.human()` function expects a `datetime` or `timedelta` object. Passing a string directly will result in this error because string objects do not have the methods expected for time calculations.","error":"AttributeError: 'str' object has no attribute 'total_seconds'"}]}