datetool

Author: Jacek ‘Szumak’ Kotlarski –<szumak@virthost.pl> Created: 02.12.2023

Purpose: Sets of classes for various date/time operations.

class jsktoolbox.datetool.DateTime

Bases: NoNewAttributes

A utility class for generating various datetime structures.

classmethod now(tz=None)

Return a datetime object for the current time.

### Arguments: * tz: Optional[timezone] - The timezone for the object. Defaults to None (local time).

### Returns: datetime - The current datetime object.

Parameters:

tz (timezone | None)

Return type:

datetime

classmethod datetime_from_timestamp(timestamp_seconds, tz=None)

Create a datetime object from a Unix timestamp.

### Arguments: * timestamp_seconds: Union[int, float] - The Unix timestamp in seconds. * tz: Optional[timezone] - The timezone for the object. Defaults to None.

### Returns: datetime - The datetime object corresponding to the timestamp.

### Raises: * TypeError: If timestamp_seconds is not an int or float.

Parameters:

• timestamp_seconds (int | float)

• tz (timezone | None)

Return type:

datetime

classmethod elapsed_time_from_seconds(seconds)

Convert a duration in seconds into a timedelta object.

### Arguments: * seconds: Union[int, float] - The duration in seconds.

### Returns: timedelta - The timedelta object representing the duration.

### Raises: * TypeError: If seconds is not an int or float.

Parameters:

seconds (int | float)

Return type:

timedelta

classmethod elapsed_time_from_timestamp(seconds, tz=None)

Calculate the elapsed time from a given timestamp to now.

### Arguments: * seconds: Union[int, float] - The starting Unix timestamp in seconds. * tz: Optional[timezone] - The timezone for the calculation. Defaults to None.

### Returns: timedelta - The timedelta object for the elapsed time, accurate to the second.

### Raises: * TypeError: If seconds is not an int or float.

Parameters:

• seconds (int | float)

• tz (timezone | None)

Return type:

timedelta

class jsktoolbox.datetool.Timestamp

Bases: NoNewAttributes

A utility class for generating Unix timestamps.

classmethod now(returned_type=<class 'int'>)

Get the current Unix timestamp.

### Arguments: * returned_type: Union[type[int], type[float]] - The desired type, int (default) or float.

### Returns: Union[int, float] - The current Unix timestamp.

### Raises: * TypeError: If returned_type is not int or float.

Parameters:

returned_type (type[int] | type[float])

Return type:

int | float

classmethod from_string(date_string, format, returned_type=<class 'int'>)

Create a Unix timestamp from a string representation of a date.

### Arguments: * date_string: str - The string containing the date and/or time. * format: str - The strptime format code used to parse the date_string. * returned_type: Union[type[int], type[float]] - The desired type, int (default) or float.

### Returns: Union[int, float] - The Unix timestamp derived from the string.

### Raises: * TypeError: If returned_type is not int or float. * ValueError: If date_string cannot be parsed with the given format.

Parameters:

• date_string (str)

• format (str)

• returned_type (type[int] | type[float])

Return type:

int | float

classmethod month_timestamp_tuple(query_date=None, tz=datetime.timezone.utc)

Get the start and end Unix timestamps for a given month.

If query_date is not provided, the current month is used.

### Arguments: * query_date: Optional[Union[float, int, datetime]] - The date to determine the month (timestamp or datetime object). Defaults to None. * tz: Optional[timezone] - The timezone for the calculation. Defaults to timezone.utc.

### Returns: Tuple[float, float] - A tuple with the start and end timestamps of the month.

### Raises: * TypeError: If tz or query_date is an unsupported type.

Parameters:

• query_date (float | int | datetime | None)

• tz (timezone | None)

Return type:

Tuple[float, float]