Date Utilities¶
date_utils
¶
QUARTER_MAP = {}
module-attribute
¶
dict: Maps month numbers (1-12) to quarter labels (Q1-Q4).
MONTH_NAMES_ABBREV = [('01', 'Jan'), ('02', 'Feb'), ('03', 'Mar'), ('04', 'Apr'), ('05', 'May'), ('06', 'Jun'), ('07', 'Jul'), ('08', 'Aug'), ('09', 'Sep'), ('10', 'Oct'), ('11', 'Nov'), ('12', 'Dec')]
module-attribute
¶
list[tuple[str, str]]: Zero-padded month number to abbreviated name pairs.
MONTH_NAMES = [('01', 'January'), ('02', 'February'), ('03', 'March'), ('04', 'April'), ('05', 'May'), ('06', 'June'), ('07', 'July'), ('08', 'August'), ('09', 'September'), ('10', 'October'), ('11', 'November'), ('12', 'December')]
module-attribute
¶
list[tuple[str, str]]: Zero-padded month number to full name pairs.
get_month_label(month, abbrev=False)
¶
Return the name of a month by its number.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
month
|
Month number (1-12), as int or string. |
required | |
abbrev
|
If True, return abbreviated name (e.g. |
False
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
Month name. |
get_year_month_label(year, month, abbrev=False)
¶
Return a formatted 'Month Year' label.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
year
|
Year number. |
required | |
month
|
Month number (1-12). |
required | |
abbrev
|
If True, use abbreviated month name. |
False
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
Label like |
get_current_quarter()
¶
Return the current calendar quarter and its months.
Returns:
| Type | Description |
|---|---|
|
tuple[str, list[int]]: Quarter label (e.g. |
get_quarter(quarter_number)
¶
Return a quarter label and its months by quarter number.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
quarter_number
|
Quarter number (1-4). |
required |
Returns:
| Type | Description |
|---|---|
|
tuple[str, list[int]]: Quarter label (e.g. |
get_adjacent_months(month, year, plus=0, minus=0)
¶
Return a list of (month, year) tuples around a reference month.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
month
|
Reference month number. |
required | |
year
|
Reference year. |
required | |
plus
|
Number of months after the reference to include. |
0
|
|
minus
|
Number of months before the reference to include. |
0
|
Returns:
| Type | Description |
|---|---|
|
list[tuple[int, int]]: (month, year) tuples in chronological order. |
is_first_day_of_month(date_to_check=None)
¶
Check if a date is the first day of its month.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
date_to_check
|
Date to check. Defaults to today. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
bool |
True if it is the first day. |
is_last_day_of_month(date_to_check=None)
¶
Check if a date is the last day of its month.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
date_to_check
|
Date to check. Defaults to today. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
bool |
True if it is the last day. |
is_last_day_of_quarter(date_to_check=None)
¶
Check if a date is the last day of its calendar quarter.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
date_to_check
|
Date to check. Defaults to today. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
bool |
True if it is the last day of the quarter. |
first_day_of_month(year, month)
¶
Return the first day of the given month.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
year
|
int
|
Year. |
required |
month
|
int
|
Month number (1-12). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
datetime |
First day of the month. |
get_last_month()
¶
Return the month and year of the previous month.
Returns:
| Type | Description |
|---|---|
|
tuple[int, int]: (month, year) of last month. |
last_day_of_month(day=None, year=None, month=None)
¶
Return the last day of the given month.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
day
|
date
|
Reference date. Used if provided. |
None
|
year
|
int
|
Year (used with month if day is not provided). |
None
|
month
|
int
|
Month number (used with year if day is not provided). |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
datetime |
Last day of the month. |
Raises:
| Type | Description |
|---|---|
Exception
|
If neither day nor (year, month) are provided. |
next_weekday(d, weekday)
¶
Return the next occurrence of a given weekday after date d.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
d
|
Reference date. |
required | |
weekday
|
Target weekday (0=Monday, 6=Sunday). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
date |
The next date matching the target weekday. |
get_adjacent_dates(ref_date=None, plus=0, minus=0)
¶
Return a list of dates around a reference date.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ref_date
|
Reference date. Defaults to today. |
None
|
|
plus
|
Number of days after the reference to include. |
0
|
|
minus
|
Number of days before the reference to include. |
0
|
Returns:
| Type | Description |
|---|---|
|
list[datetime]: Dates in chronological order, including the reference. |
is_date(_input, _format)
¶
Check if a string can be parsed as a date with the given format.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
_input
|
str
|
String to parse. |
required |
_format
|
str
|
Date format string (e.g. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
bool |
True if the string is a valid date in the given format. |