mirror of
https://github.com/hanzoskill/oura-analytics.git
synced 2026-10-30 21:10:57 +00:00
217 lines
6.6 KiB
Python
217 lines
6.6 KiB
Python
#!/usr/bin/env python3
|
|
"""
|
|
Timezone Utilities for Oura Analytics
|
|
|
|
Handles timezone-aware day alignment, travel detection, and DST handling.
|
|
"""
|
|
|
|
import os
|
|
import pytz
|
|
from datetime import datetime, date
|
|
from typing import Optional, Tuple, List
|
|
|
|
|
|
def get_user_timezone() -> str:
|
|
"""Get user's configured timezone or default to America/Los_Angeles."""
|
|
return os.environ.get("USER_TIMEZONE", "America/Los_Angeles")
|
|
|
|
|
|
def get_canonical_day(utc_timestamp: str, user_tz: Optional[str] = None) -> Tuple[Optional[date], Optional[datetime]]:
|
|
"""
|
|
Convert a UTC timestamp to the user's canonical day.
|
|
|
|
Args:
|
|
utc_timestamp: ISO format timestamp (e.g., "2026-01-15T00:00:00.000+00:00")
|
|
user_tz: User's timezone (default: from USER_TIMEZONE env or America/Los_Angeles)
|
|
|
|
Returns:
|
|
Tuple of (date object or None, timezone-aware datetime or None)
|
|
Returns (None, None) for invalid/missing timestamps
|
|
"""
|
|
if user_tz is None:
|
|
user_tz = get_user_timezone()
|
|
|
|
# Handle empty or invalid timestamps
|
|
if not utc_timestamp or len(utc_timestamp) < 10:
|
|
return None, None
|
|
|
|
try:
|
|
# Parse the UTC timestamp
|
|
# Handle both +00:00 and Z format
|
|
ts_clean = utc_timestamp.replace("Z", "+00:00")
|
|
utc_dt = datetime.fromisoformat(ts_clean)
|
|
|
|
# Handle naive timestamps by assuming UTC
|
|
if utc_dt.tzinfo is None:
|
|
utc_dt = pytz.UTC.localize(utc_dt)
|
|
|
|
# Convert to user's timezone
|
|
user_tz_obj = pytz.timezone(user_tz)
|
|
local_dt = utc_dt.astimezone(user_tz_obj)
|
|
|
|
return local_dt.date(), local_dt
|
|
except (ValueError, pytz.UnknownTimeZoneError):
|
|
# Return None for any parsing errors
|
|
return None, None
|
|
|
|
|
|
def get_canonical_day_from_date_str(date_str: str, user_tz: Optional[str] = None) -> Optional[date]:
|
|
"""
|
|
Get canonical day from a date string (YYYY-MM-DD).
|
|
|
|
For dates, we assume the date is in the user's local timezone.
|
|
Returns None for invalid/empty dates.
|
|
"""
|
|
if user_tz is None:
|
|
user_tz = get_user_timezone()
|
|
|
|
# Handle empty or invalid date strings
|
|
if not date_str or len(date_str) < 10:
|
|
return None
|
|
|
|
try:
|
|
# Parse the date as midnight in user's timezone
|
|
user_tz_obj = pytz.timezone(user_tz)
|
|
dt = datetime.strptime(date_str, "%Y-%m-%d")
|
|
local_dt = user_tz_obj.localize(dt)
|
|
return local_dt.date()
|
|
except (ValueError, pytz.UnknownTimeZoneError):
|
|
return None
|
|
|
|
|
|
def is_travel_day(sleep_records: list, threshold_hours: float = 3.0, user_tz: Optional[str] = None) -> List[date]:
|
|
"""
|
|
Detect potential travel days based on bedtime shifts.
|
|
|
|
Args:
|
|
sleep_records: List of sleep records with bedtime_start
|
|
threshold_hours: Minimum hour shift to flag as potential travel
|
|
user_tz: User's timezone (default: from USER_TIMEZONE env or America/Los_Angeles)
|
|
|
|
Returns:
|
|
List of dates that may be travel days
|
|
"""
|
|
if not sleep_records or len(sleep_records) < 2:
|
|
return []
|
|
|
|
travel_days = []
|
|
if user_tz is None:
|
|
user_tz = get_user_timezone()
|
|
|
|
# Extract bedtimes in user's local hour
|
|
bedtimes = []
|
|
for record in sleep_records:
|
|
bedtime_start = record.get("bedtime_start", "")
|
|
if not bedtime_start:
|
|
continue
|
|
|
|
canonical_day, local_dt = get_canonical_day(bedtime_start, user_tz)
|
|
if local_dt:
|
|
bedtimes.append((canonical_day, local_dt.hour + local_dt.minute / 60))
|
|
|
|
# Need at least 3 records for meaningful travel detection
|
|
if len(bedtimes) < 3:
|
|
return []
|
|
|
|
hours = [h for _, h in bedtimes]
|
|
median_hour = sorted(hours)[len(hours) // 2]
|
|
|
|
for day, hour in bedtimes:
|
|
# Use min to handle the wraparound at midnight
|
|
shift = min(abs(hour - median_hour), 24 - abs(hour - median_hour))
|
|
if shift > threshold_hours:
|
|
if day not in travel_days:
|
|
travel_days.append(day)
|
|
|
|
return travel_days
|
|
|
|
|
|
def get_sleep_for_canonical_day(sleep_data: list, target_date: date,
|
|
user_tz: Optional[str] = None) -> list:
|
|
"""
|
|
Get all sleep records that belong to a canonical day.
|
|
|
|
Oura assigns sleep to the wake date, but sleep starting the previous
|
|
day may still be relevant for the "night before".
|
|
"""
|
|
if user_tz is None:
|
|
user_tz = get_user_timezone()
|
|
|
|
matching = []
|
|
for record in sleep_data:
|
|
record_day_str = record.get("day")
|
|
if not record_day_str:
|
|
continue
|
|
|
|
canonical_day = get_canonical_day_from_date_str(record_day_str, user_tz)
|
|
|
|
if canonical_day == target_date:
|
|
matching.append(record)
|
|
|
|
return matching
|
|
|
|
|
|
def group_by_canonical_day(data: list, timestamp_field: str = "day",
|
|
user_tz: Optional[str] = None) -> dict:
|
|
"""
|
|
Group data records by canonical day.
|
|
|
|
Args:
|
|
data: List of records with a date field
|
|
timestamp_field: Field name containing the date (e.g., "day" or "bedtime_start")
|
|
user_tz: User's timezone
|
|
|
|
Returns:
|
|
Dict mapping date strings to lists of records
|
|
Skips records with missing/invalid timestamps
|
|
"""
|
|
if user_tz is None:
|
|
user_tz = get_user_timezone()
|
|
|
|
grouped = {}
|
|
for record in data:
|
|
if timestamp_field == "day":
|
|
record_date = record.get("day", "")
|
|
if not record_date:
|
|
continue
|
|
canonical = get_canonical_day_from_date_str(record_date, user_tz)
|
|
else:
|
|
record_ts = record.get(timestamp_field, "")
|
|
if not record_ts:
|
|
continue
|
|
canonical, _ = get_canonical_day(record_ts, user_tz)
|
|
|
|
if canonical is None:
|
|
continue
|
|
|
|
date_str = canonical.isoformat()
|
|
if date_str not in grouped:
|
|
grouped[date_str] = []
|
|
grouped[date_str].append(record)
|
|
|
|
return grouped
|
|
|
|
|
|
def format_localized_datetime(utc_timestamp: str, fmt: str = "%Y-%m-%d %H:%M",
|
|
user_tz: Optional[str] = None) -> str:
|
|
"""
|
|
Format a UTC timestamp in user's local time.
|
|
|
|
Args:
|
|
utc_timestamp: ISO format timestamp
|
|
fmt: Output format (default: "YYYY-MM-DD HH:MM")
|
|
user_tz: User's timezone
|
|
|
|
Returns:
|
|
Formatted datetime string in local time, or original if invalid
|
|
"""
|
|
_, local_dt = get_canonical_day(utc_timestamp, user_tz)
|
|
if local_dt:
|
|
return local_dt.strftime(fmt)
|
|
# Fallback: return the date only
|
|
return utc_timestamp[:10]
|
|
|
|
|
|
# Alias for backwards compatibility
|
|
get_canonical_date = get_canonical_day
|