{"id":7727,"library":"snaptime","title":"Snaptime","description":"Snaptime is a Python package (version 0.2.4) designed for transforming timestamps using a simple Domain Specific Language (DSL), inspired by Splunk's relative time modifiers. It provides functions to easily truncate, snap to specific time units, and apply delta transformations to datetime objects. The library has a low release cadence, with the last update in 2017.","status":"maintenance","version":"0.2.4","language":"en","source_language":"en","source_url":"https://github.com/zartstrom/snaptime","tags":["datetime","timestamps","time","time-manipulation"],"install":[{"cmd":"pip install snaptime","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"snap","correct":"from snaptime import snap"},{"symbol":"snap_tz","correct":"from snaptime import snap_tz"}],"quickstart":{"code":"from datetime import datetime\nfrom snaptime import snap, snap_tz\nimport pytz\n\n# Example 1: Basic snap and delta transformations\ndt = datetime(2018, 10, 28, 23, 0, 0)\nprint(f\"Original: {dt}\")\nprint(f\"Snap to day (@d): {snap(dt, '@d')}\") # 2018-10-28 00:00:00\nprint(f\"Add 3 hours (+3h): {snap(dt, '+3h')}\") # 2018-10-29 02:00:00\nprint(f\"Add 3 hours then snap to day (+3h@d): {snap(dt, '+3h@d')}\") # 2018-10-29 00:00:00\n\n# Example 2: Motivating example from docs (letter delivery time)\nt_harry_throws_letter = datetime(2024, 4, 15, 15, 0, 0) # Harry throws letter at 3 PM\nletter_delivery_time = snap(t_harry_throws_letter, \"+8h@d+1d+11h\")\nprint(f\"\\nLetter thrown: {t_harry_throws_letter}\")\nprint(f\"Letter delivered: {letter_delivery_time}\")\n\n# Example 3: Handling timezones with snap_tz\n# Requires 'pytz' library\nberlin_tz = pytz.timezone('Europe/Berlin')\ndt_tz_aware = berlin_tz.localize(datetime(2017, 3, 26, 3, 26, 6))\n\n# Using naive snap can lead to unexpected results during DST changes\nprint(f\"\\nTZ-aware original: {dt_tz_aware}\")\nprint(f\"snap(dt_tz_aware, '@d') (naive approach, potential DST issue): {snap(dt_tz_aware, '@d')}\")\n\n# Use snap_tz for correct timezone handling\nprint(f\"snap_tz(dt_tz_aware, '@d', berlin_tz) (correct DST handling): {snap_tz(dt_tz_aware, '@d', berlin_tz)}\")","lang":"python","description":"This quickstart demonstrates basic usage of `snap` for time manipulation and highlights the importance of `snap_tz` when dealing with timezone-aware datetimes, particularly around Daylight Saving Time (DST) changes. It includes a practical example of calculating a delivery time and showcases both naive and timezone-aware snapping."},"warnings":[{"fix":"Always use `snap_tz` when manipulating timezone-aware `datetime` objects. Provide an explicit timezone object (e.g., from `pytz`) as the third argument to `snap_tz`. Ensure the `pytz` library is installed if you need robust timezone handling.","message":"When working with timezone-aware datetime objects, using the `snap` function can lead to unexpected results, especially during Daylight Saving Time (DST) transitions. The `snap` function treats datetimes naively with respect to timezones.","severity":"gotcha","affected_versions":"0.2.0 - 0.2.4"},{"fix":"Consider testing thoroughly with your target Python environment. For new projects, evaluate alternatives if long-term active maintenance is a critical requirement.","message":"The `snaptime` library has not seen updates since version 0.2.4 was released in June 2017. While functional, it may not be actively maintained, which could lead to compatibility issues with newer Python versions or lack of bug fixes.","severity":"deprecated","affected_versions":"All versions (0.2.0 - 0.2.4)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install snaptime` to install the library. If using a virtual environment, ensure it is activated before installation and execution.","cause":"The `snaptime` library has not been installed in your Python environment or the environment is not correctly activated.","error":"ModuleNotFoundError: No module named 'snaptime'"},{"fix":"Ensure `pytz` is imported (`import pytz`) and that you are calling the `localize` method on a timezone object, passing only the naive datetime object. For example: `tz = pytz.timezone('Continent/City'); dt_aware = tz.localize(datetime_object_naive)`.","cause":"This error often occurs when `pytz.timezone.localize()` is called without a datetime object, or with incorrect arguments, if `pytz` is not imported or used correctly. More specifically, `pytz.timezone` is called like a function to create a timezone object, which then has a `localize` method. The `pytz.timezone` function itself should not be called with `localize` as an argument. The quickstart code should correctly use `berlin_tz.localize(datetime(2017, 3, 26, 3, 26, 6))`","error":"TypeError: localize() takes 1 positional argument but 2 were given"}]}