duck.utils.dateutils

Date and Time Utilities Module

Provides utility functions for working with dates and times, including formatting, parsing, calculating time differences, and handling time zones. It also provides functions to get the current time in different formats, including local time and Greenwich Mean Time (GMT).

Module Contents

Functions

build_readable_date	Build a readable date from a dictionary of datetime values.
calculate_date_diff	Calculates the difference between two datetime objects.
convert_timezone	Converts a datetime object from one time zone to another.
datetime_difference	Get the difference between two datetime objects (date_x and date_y).
datetime_difference_from_now	Get the difference between now and future datetime obj
datetime_difference_upto_now	Get the difference between a previous_datetime object up to now.
days_to_seconds	Convert days to seconds.
django_short_local_date	Returns the current local date and time in a short django formatted string.
format_date	Formats a given datetime object into a string with the specified format.
gmt_date	Returns the current Greenwich Mean Time (GMT) in a formatted string.
hours_to_seconds	Convert hours to seconds.
local_date	Returns the current local date and time in a formatted string.
minutes_to_seconds	Convert minutes to seconds.
months_to_seconds	Convert months to seconds.
parse_date	Parses a date string into a datetime object using the given format.
parse_datetime	Parses a date string into a datetime object using the given format.
parse_time	Parses a time string into a datetime object using the given format.
seconds_to_days	Convert seconds to days.
seconds_to_hours	Convert seconds to hours.
seconds_to_minutes	Convert seconds to minutes.
seconds_to_months	Convert seconds to months.
seconds_to_weeks	Convert seconds to weeks.
seconds_to_years	Convert seconds to years.
short_local_date	Returns the current local date and time in a short formatted string.
weeks_to_seconds	Convert weeks to seconds.
years_to_seconds	Convert years to seconds.

API

duck.utils.dateutils.build_readable_date(date_: dict, one_date=False) → str

Build a readable date from a dictionary of datetime values.

Parameters:

• date_ – A dictionary containing the difference in years, months, weeks, days, hours, minutes, and seconds.

• one_date – If True, return only the first non-zero date component.

Returns:

A readable date string.

Return type:

str

Raises:

KeyError – If the dictionary does not contain all the required keys.

duck.utils.dateutils.calculate_date_diff(start_date: datetime, end_date: datetime) → datetime.timedelta

Calculates the difference between two datetime objects.

Parameters:

• start_date – The start date.

• end_date – The end date.

Returns:

The difference between the two dates.

Return type:

timedelta

duck.utils.dateutils.convert_timezone(date: datetime, from_timezone: str, to_timezone: str) → datetime.datetime

Converts a datetime object from one time zone to another.

Parameters:

• date – The datetime to convert.

• from_timezone – The original time zone (e.g., “UTC”).

• to_timezone – The target time zone (e.g., “US/Eastern”).

Returns:

The converted datetime object.

Return type:

datetime

duck.utils.dateutils.datetime_difference(date_x: datetime.datetime, date_y: datetime.datetime) → dict

Get the difference between two datetime objects (date_x and date_y).

Parameters:

• date_x – The first datetime object.

• date_y – The second datetime object.

Returns:

A dictionary containing the difference in years, months, weeks, days, hours, minutes, and seconds.

Return type:

dict

Raises:

ValueError – If either date_x or date_y is not an instance of datetime.datetime.

duck.utils.dateutils.datetime_difference_from_now(future_datetime: datetime.datetime) → dict

Get the difference between now and future datetime obj

Parameters:

future_datetime – The previous datetime object.

Returns:

A dictionary containing the difference in years, months, weeks, days, hours, minutes, and seconds.

Return type:

dict

Raises:

ValueError – If future_datetime is not an instance of datetime.datetime.

duck.utils.dateutils.datetime_difference_upto_now(previous_datetime: datetime.datetime) → dict

Get the difference between a previous_datetime object up to now.

Parameters:

previous_datetime – The previous datetime object.

Returns:

A dictionary containing the difference in years, months, weeks, days, hours, minutes, and seconds.

Return type:

dict

Raises:

ValueError – If previous_datetime is not an instance of datetime.datetime.

duck.utils.dateutils.days_to_seconds(days)

Convert days to seconds.

Parameters:

days – The number of days.

Returns:

The number of seconds.

Return type:

float

duck.utils.dateutils.django_short_local_date() → str

Returns the current local date and time in a short django formatted string.

The format is: “DD/Mon/YYYY HH:MM:SS”.

Returns:

The formatted local date and time.

Return type:

str

duck.utils.dateutils.format_date(date: datetime, format_str: str = '%Y-%m-%d %H:%M:%S') → str

Formats a given datetime object into a string with the specified format.

Parameters:

• date – The datetime object to format.

• format_str – The format string.

Returns:

The formatted date string.

Return type:

str

duck.utils.dateutils.gmt_date() → str

Returns the current Greenwich Mean Time (GMT) in a formatted string.

The format is: “Day, DD Mon YYYY HH:MM:SS GMT”.

Returns:

The formatted GMT date and time.

Return type:

str

duck.utils.dateutils.hours_to_seconds(hrs)

Convert hours to seconds.

Parameters:

hrs – The number of hours.

Returns:

The number of seconds.

Return type:

float

duck.utils.dateutils.local_date() → str

Returns the current local date and time in a formatted string.

The format is: “Day, DD Mon YYYY HH:MM:SS”.

Returns:

The formatted local date and time.

Return type:

str

duck.utils.dateutils.minutes_to_seconds(mins)

Convert minutes to seconds.

Parameters:

mins – The number of minutes.

Returns:

The number of seconds.

Return type:

float

duck.utils.dateutils.months_to_seconds(months)

Convert months to seconds.

Parameters:

months – The number of months.

Returns:

The number of seconds.

Return type:

float

duck.utils.dateutils.parse_date(date_str: str, format_str: str = '%d-%m-%Y') → datetime.datetime

Parses a date string into a datetime object using the given format.

Parameters:

• date_str – The date string to parse.

• format_str – The format string.

Returns:

The parsed datetime object.

Return type:

datetime

duck.utils.dateutils.parse_datetime(datetime_str: str, format_str: str = '%d-%m-%Y %H:%M:%S') → datetime.datetime

Parses a date string into a datetime object using the given format.

Parameters:

• datetime_str – The date string to parse.

• format_str – The format string.

Returns:

The parsed datetime object.

Return type:

datetime

duck.utils.dateutils.parse_time(time_str: str, format_str: str = '%H:%M:%S') → datetime.datetime

Parses a time string into a datetime object using the given format.

Parameters:

• time_str – The time string to parse.

• format_str – The format string.

Returns:

The parsed datetime object.

Return type:

datetime

duck.utils.dateutils.seconds_to_days(secs)

Convert seconds to days.

Parameters:

secs – The number of seconds.

Returns:

The number of days.

Return type:

float

duck.utils.dateutils.seconds_to_hours(secs)

Convert seconds to hours.

Parameters:

secs – The number of seconds.

Returns:

The number of hours.

Return type:

float

duck.utils.dateutils.seconds_to_minutes(secs)

Convert seconds to minutes.

Parameters:

secs – The number of seconds.

Returns:

The number of minutes.

Return type:

float

duck.utils.dateutils.seconds_to_months(secs)

Convert seconds to months.

Parameters:

secs – The number of seconds.

Returns:

The number of months.

Return type:

float

duck.utils.dateutils.seconds_to_weeks(secs)

Convert seconds to weeks.

Parameters:

secs – The number of seconds.

Returns:

The number of weeks.

Return type:

float

duck.utils.dateutils.seconds_to_years(secs)

Convert seconds to years.

Parameters:

secs – The number of seconds.

Returns:

The number of years.

Return type:

float

duck.utils.dateutils.short_local_date() → str

Returns the current local date and time in a short formatted string.

The format is: “DD/MM/YYYY HH:MM:SS”.

Returns:

The formatted local date and time.

Return type:

str

duck.utils.dateutils.weeks_to_seconds(weeks)

Convert weeks to seconds.

Parameters:

weeks – The number of weeks.

Returns:

The number of seconds.

Return type:

float

duck.utils.dateutils.years_to_seconds(yrs)

Convert years to seconds.

Parameters:

yrs – The number of years.

Returns:

The number of seconds.

Return type:

float