gws.lib.datetimex

Date and time utilities.

These utilities are wrappers around the datetime module, some functions also use pendulum (https://pendulum.eustace.io/), however all functions here return strictly stock datetime.datetime objects.

date objects are silently promoted to datetime with time set to midnight UTC. time objects are silently promoted to datetime in the local timezone with the today’s date.

This module always returns timezone-aware objects.

When constructing an object (e.g. from a string), the default time zone should be passed as a zoneinfo string (like Europe/Berlin). An empty zoneinfo string (default) means the local time zone. Alias names like CEST are not supported.

Naive datetime arguments are assumed to be in the local time zone.

When running in a docker container, there are several ways to set up the local time zone:

• by setting the config variable server.timeZone (see gws.config.parser)

• by setting the TZ environment variable

• mounting a host zone info file to /etc/localtime

Source code: gws.lib.datetimex

Package Contents

gws.lib.datetimex.add(d: datetime.date | None = None, years=0, months=0, days=0, weeks=0, hours=0, minutes=0, seconds=0, microseconds=0) → datetime.datetime

Add time components to a datetime.

Parameters:

• d – Base datetime (default current date/time)

• years – Years to add

• months – Months to add

• days – Days to add

• weeks – Weeks to add

• hours – Hours to add

• minutes – Minutes to add

• seconds – Seconds to add

• microseconds – Microseconds to add

gws.lib.datetimex.day_of_week(d: datetime.date | None = None) → int

gws.lib.datetimex.day_of_year(d: datetime.date | None = None) → int

gws.lib.datetimex.days_in_month(d: datetime.date | None = None) → int

class gws.lib.datetimex.Diff

Difference between two dates.

days: int

hours: int

microseconds: int

minutes: int

months: int

seconds: int

weeks: int

years: int

gws.lib.datetimex.difference(d1: datetime.date, d2: datetime.date | None = None) → Diff

Compute the difference between two dates.

Parameters:

• d1 – The first date.

• d2 – The second date. If None, the current date and time is used.

gws.lib.datetimex.end_of_day(d: datetime.date | None = None) → datetime.datetime

gws.lib.datetimex.end_of_hour(d: datetime.date | None = None) → datetime.datetime

gws.lib.datetimex.end_of_minute(d: datetime.date | None = None) → datetime.datetime

gws.lib.datetimex.end_of_month(d: datetime.date | None = None) → datetime.datetime

gws.lib.datetimex.end_of_second(d: datetime.date | None = None) → datetime.datetime

gws.lib.datetimex.end_of_week(d: datetime.date | None = None) → datetime.datetime

gws.lib.datetimex.end_of_year(d: datetime.date | None = None) → datetime.datetime

exception gws.lib.datetimex.Error

Bases: gws.Error

Generic GWS error.

gws.lib.datetimex.from_iso_string(s: str, tz: str = '') → datetime.datetime

Parse an ISO 8601 datetime string.

Parameters:

• s – ISO 8601 date/time string to parse

• tz – Default time zone string for timezone-naive inputs

gws.lib.datetimex.from_iso_time_string(s: str, tz: str = '') → datetime.datetime

Parse an ISO 8601 time string.

Parameters:

• s – ISO 8601 time string to parse

• tz – Default time zone string for timezone-naive inputs

gws.lib.datetimex.from_string(s: str, tz: str = '') → datetime.datetime

Parse a datetime string using flexible parsing.

Parameters:

• s – Date/time string to parse

• tz – Default time zone string for timezone-naive inputs

gws.lib.datetimex.from_timestamp(n: float, tz: str = '') → datetime.datetime

Create a datetime from a Unix timestamp.

Parameters:

• n – Unix timestamp (seconds since epoch)

• tz – Time zone string (default empty for local time zone)

gws.lib.datetimex.is_date(x) → bool

Check if an object is a date.

Parameters:

x – Object to check

gws.lib.datetimex.is_datetime(x) → bool

Check if an object is a datetime.

Parameters:

x – Object to check

gws.lib.datetimex.is_local(d: datetime.datetime) → bool

Check if a datetime is in the local timezone.

Parameters:

d – Datetime to check

gws.lib.datetimex.is_utc(d: datetime.datetime) → bool

Check if a datetime is in UTC timezone.

Parameters:

d – Datetime to check

gws.lib.datetimex.mock_now(d)

gws.lib.datetimex.new(year, month, day, hour=0, minute=0, second=0, microsecond=0, fold=0, tz: str = '') → datetime.datetime

Create a new datetime object with the specified components.

Parameters:

• year – Year component

• month – Month component

• day – Day component

• hour – Hour component (default 0)

• minute – Minute component (default 0)

• second – Second component (default 0)

• microsecond – Microsecond component (default 0)

• fold – Fold component for ambiguous times (default 0)

• tz – Time zone string (default empty for local time zone)

gws.lib.datetimex.next(day: int | str, d: datetime.date | None = None, keep_time=False) → datetime.datetime

Get the next occurrence of a specific weekday.

Parameters:

• day – Day of week (0-6 for Monday-Sunday or weekday name string)

• d – Starting date (default current date/time)

• keep_time – Whether to keep the time component

gws.lib.datetimex.now(tz: str = '') → datetime.datetime

Get the current date and time.

Parameters:

tz – Time zone string (default empty for local time zone)

gws.lib.datetimex.now_utc() → datetime.datetime

Get the current date and time in UTC.

gws.lib.datetimex.parse(s: str | datetime.datetime | datetime.date | None, tz: str = '') → datetime.datetime | None

Parse a string, datetime, or date into a datetime object.

Parameters:

• s – Input to parse (string, datetime, date, or None)

• tz – Default time zone string for timezone-naive inputs

gws.lib.datetimex.parse_duration(s: str) → int

Convert duration string to seconds.

Parameters:

s – Duration string (e.g. ‘1w2d3h4m5s’) or integer seconds

gws.lib.datetimex.parse_time(s: str | datetime.time | None, tz: str = '') → datetime.datetime | None

Parse a string or time into a datetime object.

Parameters:

• s – Input to parse (string, time, or None)

• tz – Default time zone string for timezone-naive inputs

gws.lib.datetimex.prev(day: int | str, d: datetime.date | None = None, keep_time=False) → datetime.datetime

Get the previous occurrence of a specific weekday.

Parameters:

• day – Day of week (0-6 for Monday-Sunday or weekday name string)

• d – Starting date (default current date/time)

• keep_time – Whether to keep the time component

gws.lib.datetimex.set_local_time_zone(tz: str)

Set the local time zone for the system.

Parameters:

tz – Time zone string (e.g. ‘Europe/Berlin’)

gws.lib.datetimex.start_of_day(d: datetime.date | None = None) → datetime.datetime

gws.lib.datetimex.start_of_hour(d: datetime.date | None = None) → datetime.datetime

gws.lib.datetimex.start_of_minute(d: datetime.date | None = None) → datetime.datetime

gws.lib.datetimex.start_of_month(d: datetime.date | None = None) → datetime.datetime

gws.lib.datetimex.start_of_second(d: datetime.date | None = None) → datetime.datetime

gws.lib.datetimex.start_of_week(d: datetime.date | None = None) → datetime.datetime

gws.lib.datetimex.start_of_year(d: datetime.date | None = None) → datetime.datetime

gws.lib.datetimex.time_to_iso_string(d: datetime.date | datetime.time | None = None, with_tz='+') → str

Convert a date or time to an ISO time string.

Parameters:

• d – Date or time to convert (default returns 00:00:00)

• with_tz – Include timezone information (unused in current implementation)

gws.lib.datetimex.time_zone(tz: str = '') → zoneinfo.ZoneInfo

Get a ZoneInfo object for the specified time zone.

Parameters:

tz – Time zone string (e.g. ‘Europe/Berlin’). Empty string returns local time zone.

gws.lib.datetimex.to_basic_string(d: datetime.date | None = None) → str

Convert a date to a basic string format (YYYYMMDDHHMMSS).

Parameters:

d – Date to convert (default current date/time)

gws.lib.datetimex.to_iso_date_string(d: datetime.date | None = None) → str

Convert a date to an ISO date string (YYYY-MM-DD format).

Parameters:

d – Date to convert (default current date/time)

gws.lib.datetimex.to_iso_string(d: datetime.date | None = None, with_tz='+', sep='T') → str

Convert a date or time to an ISO string.

Parameters:

• d – Date or time to convert. If None, the current date and time is used.

• with_tz – If set, append the time zone information. Can be “Z” (for UTC), “:” (for ISO 8601 format) or “+” (for +hhmm format).

• sep – Separator between date and time. Default is “T”.

gws.lib.datetimex.to_iso_time_string(d: datetime.date | None = None, with_tz='+') → str

Convert a date to an ISO time string.

Parameters:

• d – Date to convert (default current date/time)

• with_tz – Include timezone information (‘+’ for +hhmm, ‘Z’ for UTC as Z, False for no timezone)

gws.lib.datetimex.to_local(d: datetime.date | None = None) → datetime.datetime

Convert a date to local timezone.

Parameters:

d – Date to convert (default current date/time)

gws.lib.datetimex.to_millis(d: datetime.date | None = None) → int

Convert a date to milliseconds since Unix epoch.

Parameters:

d – Date to convert (default current date/time)

gws.lib.datetimex.to_string(fmt: str, d: datetime.date | None = None) → str

Convert a date to a string using a custom format.

Parameters:

• fmt – strftime format string

• d – Date to convert (default current date/time)

gws.lib.datetimex.to_time_zone(tz: str, d: datetime.date | None = None) → datetime.datetime

Convert a date to a specific timezone.

Parameters:

• tz – Target timezone string

• d – Date to convert (default current date/time)

gws.lib.datetimex.to_timestamp(d: datetime.date | None = None) → int

Convert a date to a Unix timestamp.

Parameters:

d – Date to convert (default current date/time)

gws.lib.datetimex.to_utc(d: datetime.date | None = None) → datetime.datetime

Convert a date to UTC timezone.

Parameters:

d – Date to convert (default current date/time)

gws.lib.datetimex.today(tz: str = '') → datetime.datetime

Get today’s date at midnight.

Parameters:

tz – Time zone string (default empty for local time zone)

gws.lib.datetimex.today_utc() → datetime.datetime

Get today’s date at midnight in UTC.

gws.lib.datetimex.total_difference(d1: datetime.date, d2: datetime.date | None = None) → Diff

Compute the total difference between two dates in each unit.

Parameters:

• d1 – First date

• d2 – Second date (default current date/time)

gws.lib.datetimex.UTC

gws.lib.datetimex.week_of_month(d: datetime.date | None = None) → int

gws.lib.datetimex.week_of_year(d: datetime.date | None = None) → int