Metadata-Version: 2.4
Name: cs-dateutils
Version: 20260912
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 20260912*:
New as_datetime() to convert various things into a timezone aware datetime, hauled in from cs.feeds.

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:


* `as_datetime`: Turn a value into a timezone aware datetime.


* `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.

# Functions

## as_datetime(dt: float | str | datetime.date | datetime.datetime, *, tz: datetime.tzinfo = datetime.timezone.utc) -> datetime.datetime

Turn a value into a timezone aware datetime.

Parameters:
* `dt`: the `datetime` specification, a `str` or `float` or `date` or `datetime`
* `tz`: optional `tzinfo` specifying the target timezone, default UTC

The conversion of `dt` is as follows:
* `datetime`: `dt.astimezone(tz=tz)`
* `date`: rather arbitrarily assume it is in the target timezone
* `float`: a UNIX timestamp (seconds since the epoch)
* `str`: try `datetime.fromisoformat` then `datetime.strptime("%a, %d %b %Y %H:%M:%S %z")`

## datetime2unixtime(dt)

Convert a timezone aware `datetime` to a UNIX timestamp.
*WARNING*: a naive datetime is assumed to be in UTC.

## 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.

## localdate2unixtime(d)

Convert a localtime `date` into a UNIX timestamp.

## 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.

# Classes

## class UNIXTimeMixin

A mixin for classes with a `.unixtime` attribute,
a `float` storing a UNIX timestamp.

### UNIXTimeMixin.__dict__

Read-only proxy of a mapping.

### UNIXTimeMixin.__firstlineno__

int([x]) -> integer
int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments
are given.  If x is a number, return x.__int__().  For floating-point
numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string,
bytes, or bytearray instance representing an integer literal in the
given base.  The literal can be preceded by '+' or '-' and be surrounded
by whitespace.  The base defaults to 10.  Valid bases are 0 and 2-36.
Base 0 means to interpret the base from the string as an integer literal.
>>> int('0b100', base=0)
4

### UNIXTimeMixin.__static_attributes__

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple.
If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

### 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`.

## class tzinfoHHMM(datetime.tzinfo)

tzinfo class based on +HHMM / -HHMM strings.

### tzinfoHHMM.__dict__

Read-only proxy of a mapping.

### tzinfoHHMM.__firstlineno__

int([x]) -> integer
int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments
are given.  If x is a number, return x.__int__().  For floating-point
numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string,
bytes, or bytearray instance representing an integer literal in the
given base.  The literal can be preceded by '+' or '-' and be surrounded
by whitespace.  The base defaults to 10.  Valid bases are 0 and 2-36.
Base 0 means to interpret the base from the string as an integer literal.
>>> int('0b100', base=0)
4

### tzinfoHHMM.__static_attributes__

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple.
If iterable is specified the tuple is initialized from iterable's items.

If the argument is a tuple, the return value is the same object.

# Release Log



*Release 20260912*:
New as_datetime() to convert various things into a timezone aware datetime, hauled in from cs.feeds.

*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.
