# © Copyright 2021-2022, Scott Gasch
-"""Utilities related to dates and times and datetimes."""
+"""Utilities related to dates, times, and datetimes."""
import datetime
import enum
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
+ """Returns true if the datetime argument is timezone aware or
+ False if not.
+
+ See: https://docs.python.org/3/library/datetime.html
+ #determining-if-an-object-is-aware-or-naive
+
+ Args:
+ dt: The datetime object to check
>>> is_timezone_aware(datetime.datetime.now())
False
def is_timezone_naive(dt: datetime.datetime) -> bool:
- """Inverse of is_timezone_aware.
+ """Inverse of is_timezone_aware -- returns true if the dt argument
+ is timezone naive.
+
+ See: https://docs.python.org/3/library/datetime.html
+ #determining-if-an-object-is-aware-or-naive
+
+ Args:
+ dt: The datetime object to check
>>> is_timezone_naive(datetime.datetime.now())
True
def strip_timezone(dt: datetime.datetime) -> datetime.datetime:
- """Remove the timezone from a datetime. Does not change the
- hours, minutes, seconds, months, days, years, etc... Thus the
- instant to which this timestamp refers will change. Silently
- ignores datetimes which are already timezone naive.
+ """Remove the timezone from a datetime.
+
+ .. warning::
+
+ This does not change the hours, minutes, seconds,
+ months, days, years, etc... Thus the instant to which this
+ timestamp refers will change. Silently ignores datetimes
+ which are already timezone naive.
>>> now = now_pacific()
>>> now.tzinfo == None
return dt
raise Exception(
f'{dt} is already timezone aware; use replace_timezone or translate_timezone '
- + 'depending on the semantics you want.'
+ + 'depending on the semantics you want. See the pydocs / code.'
)
return dt.replace(tzinfo=tz)
with a tz parameter. Using this can have weird side effects like
UTC offsets that are not an even multiple of an hour, etc...
- Note: this changes the instant to which this dt refers.
+ .. warning::
+
+ This changes the instant to which this dt refers.
>>> from pytz import UTC
>>> d = now_pacific()
def replace_time_timezone(t: datetime.time, tz: datetime.tzinfo) -> datetime.time:
- """
- Replaces the timezone on a datetime.time directly without performing
- any translation. Note that, as above, this will change the instant
- to which the time refers.
+ """Replaces the timezone on a datetime.time directly without performing
+ any translation.
+
+ .. warning::
+
+ Note that, as above, this will change the instant to
+ which the time refers.
>>> t = datetime.time(8, 15, 12, 0, pytz.UTC)
>>> t.tzname()
>>> t = replace_time_timezone(t, pytz.timezone('US/Pacific'))
>>> t.tzname()
'US/Pacific'
-
"""
return t.replace(tzinfo=tz)
def now() -> datetime.datetime:
"""
- What time is it? Returned as a timezone naive datetime.
+ What time is it? Result is a timezone naive datetime.
"""
return datetime.datetime.now()
def datetime_to_date_and_time(
dt: datetime.datetime,
) -> Tuple[datetime.date, datetime.time]:
- """Return the component date and time objects of a datetime.
+ """Return the component date and time objects of a datetime in a
+ Tuple given a datetime.
>>> import datetime
>>> dt = datetime.datetime(2021, 12, 25, 12, 30)
def datetime_to_date(dt: datetime.datetime) -> datetime.date:
- """Return the date part of a datetime.
+ """Return just the date part of a datetime.
>>> import datetime
>>> dt = datetime.datetime(2021, 12, 25, 12, 30)
def datetime_to_time(dt: datetime.datetime) -> datetime.time:
- """Return the time part of a datetime.
+ """Return just the time part of a datetime.
>>> import datetime
>>> dt = datetime.datetime(2021, 12, 25, 12, 30)