Install & Compatibility
Where this runs
tested against v0.2.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.030s · 22.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.7s · import 0.028s · 23MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
snap
✓ from snaptime import snap
snap_tz
✓ from snaptime import snap_tz
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)}")
Debug
Known issues
gotchaWhen 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.fixAlways 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.
affects: 0.2.0 - 0.2.4
deprecatedThe `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.fixConsider testing thoroughly with your target Python environment. For new projects, evaluate alternatives if long-term active maintenance is a critical requirement.
affects: All versions (0.2.0 - 0.2.4)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'snaptime'
The `snaptime` library has not been installed in your Python environment or the environment is not correctly activated.
fixRun `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
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))`
fixEnsure `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)`. Upgrade
Version history
0.2.4latest on PyPI · released Jun 15, 2017
Audit
Dependencies
No dependency data recorded yet.