Module

utils.dates

Date and time utilities for Bengal SSG.

Provides centralized date parsing, formatting, and manipulation functions to eliminate duplicate logic across templates and core code.

View source
10 Functions

Functions

parse_date
Parse various date formats into datetime. Handles: - datetime objects (pass through) - date object…
3 datetime | None 
def parse_date(value: DateLike, formats: list[str] | None = None, on_error: str = 'return_none') -> datetime | None

Parse various date formats into datetime.

Handles:

  • datetime objects (pass through)
  • date objects (convert to datetime at midnight)
  • ISO 8601 strings (with or without timezone)
  • Custom format strings

Parameters 3

Name Type Default Description
value DateLike —

Date value in various formats
formats list[str] | None None

Optional list of strptime format strings to try
on_error str 'return_none'

How to handle parse errors: - 'return_none': Return None (default) - 'raise': Raise ValueError - 'return_original': Return original value as-is

Returns

datetime | None —

datetime object or None if parsing fails

format_date_iso
Format date as ISO 8601 string. Uses parse_date internally for flexible input handling.
1 str 
def format_date_iso(date: DateLike) -> str

Format date as ISO 8601 string.

Uses parse_date internally for flexible input handling.

Parameters 1

Name Type Default Description
date DateLike —

Date value in various formats

Returns

str —

ISO 8601 formatted string (YYYY-MM-DDTHH:MM:SS)

format_date_rfc822
Format date as RFC 822 string (for RSS feeds). Uses parse_date internally for flexible input handling.
1 str 
def format_date_rfc822(date: DateLike) -> str

Format date as RFC 822 string (for RSS feeds).

Uses parse_date internally for flexible input handling.

Parameters 1

Name Type Default Description
date DateLike —

Date value in various formats

Returns

str —

RFC 822 formatted string (e.g., "Fri, 03 Oct 2025 14:30:00 +0000")

format_date_human
Format date in human-readable format. Uses parse_date internally for flexible input handling.
2 str 
def format_date_human(date: DateLike, format: str = '%B %d, %Y') -> str

Format date in human-readable format.

Uses parse_date internally for flexible input handling.

Parameters 2

Name Type Default Description
date DateLike —

Date value in various formats
format str '%B %d, %Y'

strftime format string (default: "October 09, 2025")

Returns

str —

Formatted date string

time_ago
Convert date to human-readable "time ago" format. Uses parse_date internally for flexible input ha…
2 str 
def time_ago(date: DateLike, now: datetime | None = None) -> str

Convert date to human-readable "time ago" format.

Uses parse_date internally for flexible input handling.

Parameters 2

Name Type Default Description
date DateLike —

Date to convert
now datetime | None None

Current time (defaults to datetime.now())

Returns

str —

Human-readable time ago string

get_current_year
Get current year as integer. Useful for copyright notices and templates.
0 int 
def get_current_year() -> int

Get current year as integer.

Useful for copyright notices and templates.

Returns

int —

Current year

is_recent
Check if date is recent (within specified days).
3 bool 
def is_recent(date: DateLike, days: int = 7, now: datetime | None = None) -> bool

Check if date is recent (within specified days).

Parameters 3

Name Type Default Description
date DateLike —

Date to check
days int 7

Number of days to consider "recent" (default: 7)
now datetime | None None

Current time (defaults to datetime.now())

Returns

bool —

True if date is within the last N days

date_range_overlap
Check if two date ranges overlap.
4 bool 
def date_range_overlap(start1: DateLike, end1: DateLike, start2: DateLike, end2: DateLike) -> bool

Check if two date ranges overlap.

Parameters 4

Name Type Default Description
start1 DateLike —

Start of first range
end1 DateLike —

End of first range
start2 DateLike —

Start of second range
end2 DateLike —

End of second range

Returns

bool —

True if ranges overlap

utc_now
Get current UTC datetime (low-level primitive).
0 datetime 
def utc_now() -> datetime

Get current UTC datetime (low-level primitive).

Returns

datetime

iso_timestamp
Get ISO 8601 timestamp from datetime (UTC).
1 str 
def iso_timestamp(dt: datetime | None = None) -> str

Get ISO 8601 timestamp from datetime (UTC).

Parameters 1

Name Type Default Description
dt datetime | None None

Returns

str