logger = logging.getLogger(__name__)
+def is_timezone_aware(dt: datetime.datetime) -> bool:
+ """See: https://docs.python.org/3/library/datetime.html
+ #determining-if-an-object-is-aware-or-naive
+
+ >>> is_timezone_aware(datetime.datetime.now())
+ False
+
+ >>> is_timezone_aware(now_pacific())
+ True
+
+ """
+ return (
+ dt.tzinfo is not None and
+ dt.tzinfo.utcoffset(dt) is not None
+ )
+
+
+def is_timezone_naive(dt: datetime.datetime) -> bool:
+ return not is_timezone_aware(dt)
+
+
def replace_timezone(dt: datetime.datetime,
tz: datetime.tzinfo) -> datetime.datetime:
"""
- Replaces the timezone on a datetime object.
+ Replaces the timezone on a datetime object directly (leaving
+ the year, month, day, hour, minute, second, micro, etc... alone).
+ Note: this changes the instant to which this dt refers.
>>> from pytz import UTC
>>> d = now_pacific()
>>> d.tzinfo.tzname(d)[0] # Note: could be PST or PDT
'P'
+ >>> h = d.hour
>>> o = replace_timezone(d, UTC)
>>> o.tzinfo.tzname(o)
'UTC'
+ >>> o.hour == h
+ True
+
+ """
+ return datetime.datetime(
+ dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second, dt.microsecond,
+ tzinfo=tz
+ )
+
+
+def replace_time_timezone(t: datetime.time,
+ tz: datetime.tzinfo) -> datetime.time:
+ """
+ Replaces the timezone on a datetime.time directly without performing
+ any translation.
+
+ >>> t = datetime.time(8, 15, 12, 0, pytz.UTC)
+ >>> t.tzname()
+ 'UTC'
+
+ >>> t = replace_time_timezone(t, pytz.timezone('US/Pacific'))
+ >>> t.tzname()
+ 'US/Pacific'
+
+ """
+ return t.replace(tzinfo=tz)
+
+
+def translate_timezone(dt: datetime.datetime,
+ tz: datetime.tzinfo) -> datetime.datetime:
+ """
+ Translates dt into a different timezone by adjusting the year, month,
+ day, hour, minute, second, micro, etc... appropriately. The returned
+ dt is the same instant in another timezone.
+
+ >>> from pytz import UTC
+ >>> d = now_pacific()
+ >>> d.tzinfo.tzname(d)[0] # Note: could be PST or PDT
+ 'P'
+ >>> h = d.hour
+ >>> o = translate_timezone(d, UTC)
+ >>> o.tzinfo.tzname(o)
+ 'UTC'
+ >>> o.hour == h
+ False
"""
return dt.replace(tzinfo=None).astimezone(tz=tz)
def now_pacific() -> datetime.datetime:
"""
- What time is it? Result in US/Pacifit time (PST/PDT)
+ What time is it? Result in US/Pacific time (PST/PDT)
"""
- return replace_timezone(now(), pytz.timezone("US/Pacific"))
+ return datetime.datetime.now(pytz.timezone("US/Pacific"))
def date_to_datetime(date: datetime.date) -> datetime.datetime:
)
+def time_to_datetime_today(time: datetime.time) -> datetime.datetime:
+ """
+ Given a time, returns that time as a datetime with a date component
+ set based on the current date. If the time passed is timezone aware,
+ the resulting datetime will also be (and will use the same tzinfo).
+ If the time is timezone naive, the datetime returned will be too.
+
+ >>> t = datetime.time(13, 14, 0)
+ >>> d = now_pacific().date()
+ >>> dt = time_to_datetime_today(t)
+ >>> dt.date() == d
+ True
+
+ >>> dt.time() == t
+ True
+
+ >>> dt.tzinfo == t.tzinfo
+ True
+
+ >>> dt.tzinfo == None
+ True
+
+ >>> t = datetime.time(8, 15, 12, 0, pytz.UTC)
+ >>> t.tzinfo == None
+ False
+
+ >>> dt = time_to_datetime_today(t)
+ >>> dt.tzinfo == None
+ False
+
+ """
+ now = now_pacific()
+ tz = time.tzinfo
+ return datetime.datetime.combine(now, time, tz)
+
+
def date_and_time_to_datetime(date: datetime.date,
time: datetime.time) -> datetime.datetime:
"""
return descr
+def describe_timedelta(delta: datetime.timedelta) -> str:
+ """
+ Describe a duration represented by a timedelta object.
+
+ >>> d = datetime.timedelta(1, 600)
+ >>> describe_timedelta(d)
+ '1 day, and 10 minutes'
+
+ """
+ return describe_duration(delta.total_seconds())
+
+
def describe_duration_briefly(seconds: int, *, include_seconds=False) -> str:
"""
Describe a duration briefly.
return descr.strip()
+def describe_timedelta_briefly(delta: datetime.timedelta) -> str:
+ """
+ Describe a duration represented by a timedelta object.
+
+ >>> d = datetime.timedelta(1, 600)
+ >>> describe_timedelta_briefly(d)
+ '1d 10m'
+
+ """
+ return describe_duration_briefly(delta.total_seconds())
+
+
if __name__ == '__main__':
import doctest
doctest.testmod()