Metadata-Version: 2.4
Name: cs-dateutils
Version: 20250724
Summary: A few conveniences to do with dates and times.
Keywords: date,time,datetime,python,python3
Author-email: Cameron Simpson <cs@cskk.id.au>
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Project-URL: MonoRepo Commits, https://bitbucket.org/cameron_simpson/css/commits/branch/main
Project-URL: Monorepo Git Mirror, https://github.com/cameron-simpson/css
Project-URL: Monorepo Hg/Mercurial Mirror, https://hg.sr.ht/~cameron-simpson/css
Project-URL: Source, https://github.com/cameron-simpson/css/blob/main/lib/python/cs/dateutils.py

A few conveniences to do with dates and times.

*Latest release 20250724*:
* unixtime2datetime: default tz now UTC.
* Some doc updates.

There are some other PyPI modules providing richer date handling
than the stdlib `datetime` module.
This module mostly contains conveniences used in my other code;
you're welcome to it, but it does not pretend to be large or complete.

Short summary:
* `datetime2unixtime`: Convert a timezone aware `datetime` to a UNIX timestamp. *WARNING*: a naive datetime is assumed to be in UTC.
* `isodate`: Return a date in ISO8601 YYYY-MM-DD format, or YYYYMMDD if not `dashed`.
* `localdate2unixtime`: Convert a localtime `date` into a UNIX timestamp.
* `tzinfoHHMM`: tzinfo class based on +HHMM / -HHMM strings.
* `unixtime2datetime`: Convert a a UNIX timestamp to a `datetime` in the timezone `tz`. *Note*: the default timezone is UTC, not the local timezone.
* `UNIXTimeMixin`: A mixin for classes with a `.unixtime` attribute, a `float` storing a UNIX timestamp.

Module contents:
- <a name="datetime2unixtime"></a>`datetime2unixtime(dt)`: Convert a timezone aware `datetime` to a UNIX timestamp.
  *WARNING*: a naive datetime is assumed to be in UTC.
- <a name="isodate"></a>`isodate(when=None, dashed=True)`: Return a date in ISO8601 YYYY-MM-DD format, or YYYYMMDD if not `dashed`.

  Modern Pythons have a `datetime.isoformat` method, you should use that.
- <a name="localdate2unixtime"></a>`localdate2unixtime(d)`: Convert a localtime `date` into a UNIX timestamp.
- <a name="tzinfoHHMM"></a>`class tzinfoHHMM(datetime.tzinfo)`: tzinfo class based on +HHMM / -HHMM strings.
- <a name="unixtime2datetime"></a>`unixtime2datetime(unixtime, *, tz: datetime.tzinfo = datetime.timezone.utc)`: Convert a a UNIX timestamp to a `datetime` in the timezone `tz`.
  *Note*: the default timezone is UTC, not the local timezone.
- <a name="UNIXTimeMixin"></a>`class UNIXTimeMixin`: A mixin for classes with a `.unixtime` attribute,
  a `float` storing a UNIX timestamp.

*`UNIXTimeMixin.as_datetime(self, tz: datetime.tzinfo = datetime.timezone.utc)`*:
Return `self.unixtime` as a `datetime`
with the timezone `tz` (default `UTC`).

*`UNIXTimeMixin.datetime`*:
The `unixtime` as a UTC `datetime`.

# Release Log



*Release 20250724*:
* unixtime2datetime: default tz now UTC.
* Some doc updates.

*Release 20230210*:
* Drop Python 2 support.
* Make timezones mandatory where previously they were assumed.

*Release 20210306*:
Initial release, used by cs.sqltags.
