Snaptime

Common errors

• ModuleNotFoundError: No module named 'snaptime'

  cause The `snaptime` library has not been installed in your Python environment or the environment is not correctly activated.
  fix Run `pip install snaptime` to install the library. If using a virtual environment, ensure it is activated before installation and execution.

• TypeError: localize() takes 1 positional argument but 2 were given

  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))`
  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)`.

Warnings

• gotcha 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.
  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.
• deprecated 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.
  Fix: Consider testing thoroughly with your target Python environment. For new projects, evaluate alternatives if long-term active maintenance is a critical requirement.

Install

• pip install snaptime Install stable version

Imports

• snap

  from snaptime import snap

• snap_tz

  from snaptime import snap_tz

Quickstart

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.

from datetime import datetime
from snaptime import snap, snap_tz
import pytz

# Example 1: Basic snap and delta transformations
dt = datetime(2018, 10, 28, 23, 0, 0)
print(f"Original: {dt}")
print(f"Snap to day (@d): {snap(dt, '@d')}") # 2018-10-28 00:00:00
print(f"Add 3 hours (+3h): {snap(dt, '+3h')}") # 2018-10-29 02:00:00
print(f"Add 3 hours then snap to day (+3h@d): {snap(dt, '+3h@d')}") # 2018-10-29 00:00:00

# Example 2: Motivating example from docs (letter delivery time)
t_harry_throws_letter = datetime(2024, 4, 15, 15, 0, 0) # Harry throws letter at 3 PM
letter_delivery_time = snap(t_harry_throws_letter, "+8h@d+1d+11h")
print(f"\nLetter thrown: {t_harry_throws_letter}")
print(f"Letter delivered: {letter_delivery_time}")

# Example 3: Handling timezones with snap_tz
# Requires 'pytz' library
berlin_tz = pytz.timezone('Europe/Berlin')
dt_tz_aware = berlin_tz.localize(datetime(2017, 3, 26, 3, 26, 6))

# Using naive snap can lead to unexpected results during DST changes
print(f"\nTZ-aware original: {dt_tz_aware}")
print(f"snap(dt_tz_aware, '@d') (naive approach, potential DST issue): {snap(dt_tz_aware, '@d')}")

# Use snap_tz for correct timezone handling
print(f"snap_tz(dt_tz_aware, '@d', berlin_tz) (correct DST handling): {snap_tz(dt_tz_aware, '@d', berlin_tz)}")