Python API

Calendar-Smith provides a clean and simple Python API for integrating calendar-related math into your own scripts, applications, and data-processing pipelines.

Use the Python API when you want to:

  • Call calendar logic directly from Python code

  • Reuse date-parsing or fiscal-year-calculation logic programmatically

  • Build repeatable pipelines without shell commands

  • Integrate timezone conversion or window generation in application code

—

Typical import style

Import directly from the top-level package whenever possible:

from calendar_smith import get_fiscal_year, now_jst

# Calculate Japanese fiscal year
fy = get_fiscal_year("2026-04-22", system="jp")

# Get current time in JST
current_time = now_jst()

—

Overview

The Python API complements the command-line interface (CLI).

  • Use the CLI for one-off tasks and shell workflows.

  • Use the Python API when you need direct integration in Python code.

For detailed module reference, see API Reference.

—

Key modules

  • calendar_smith.core: Core logic for fiscal years, ISO weeks, and date windows.

  • calendar_smith.time: Timezone utilities and ISO 8601 helpers.

  • calendar_smith.utils: General helpers for date parsing and ordinal formatting.

—

Example: Processing a list of dates

from calendar_smith import get_fiscal_year, ensure_date

raw_dates = ["2026-03-31", "2026-04-01", "2026-04-22"]

# Safely parse and calculate fiscal year for each date
results = []
for d in raw_dates:
    date_obj = ensure_date(d)
    fy = get_fiscal_year(date_obj, system="jp")
    results.append((date_obj, fy))

print(results)

—

Next steps