Recipes

Common patterns and use cases for Calendar-Smith.

—

Working with Japanese fiscal years

Many organizations in Japan use a fiscal year starting April 1.

from calendar_smith import get_fiscal_year

# Date in the current fiscal year (FY2026)
date_str = "2026-04-22"
fy = get_fiscal_year(date_str, system="jp")
# Result: 2026

# Date in the previous fiscal year (FY2025)
date_str = "2026-03-31"
fy = get_fiscal_year(date_str, system="jp")
# Result: 2025

—

Generating weekly windows for analysis

If you need to analyze data in 7-day windows starting from a specific date:

from calendar_smith import get_dates_windows

# Start date, window size (7 days), count (4 windows)
windows = get_dates_windows("2026-03-17", 7, 4)

for start, end in windows:
    print(f"Window: {start} to {end}")

—

Handling timezones safely

Convert UTC to JST or other timezones without external libraries:

from calendar_smith import now_utc, to_timezone, JST

# Current time in UTC
utc_time = now_utc()

# Convert to JST
jst_time = to_timezone(utc_time, JST)

print(f"UTC: {utc_time.isoformat()}")
print(f"JST: {jst_time.isoformat()}")

—

Safe date parsing from CSV strings

When reading from CSV, you often get string dates in various formats. ensure_date helps normalize them while rejecting ambiguous ones.

from calendar_smith import ensure_date

# Standard ISO 8601
d1 = ensure_date("2026-04-22")

# Compressed format (YYYYMMDD)
d2 = ensure_date("20260422")

# Ambiguous formats like "260422" are strictly REJECTED to prevent errors.
try:
    ensure_date("260422")
except ValueError as e:
    print(f"Error: {e}")