calendar-smith

Calendar-Smith is a zero-dependency, high-performance Python utility for fiscal year calculations, ISO week mapping, and safe date parsing.

It was built for data engineers and analysts who need to process CSVs or perform calendar math without the overhead of heavy libraries like Pandas or Arrow.

Key Features

• Safety-First Parsing: Strictly rejects ambiguous 6-digit (460614) and 7-digit (2026123) strings to prevent century errors and data corruption.
• Fiscal Logic: Built-in support for US (fiscal year ends Sep 30) and Japanese (fiscal year ends Mar 31) fiscal systems.
• Fast-Path Execution: Utilizes datetime.fromisoformat for high-performance processing of standard data.
• Timezone Utilities: Lightweight helpers for UTC, JST, ET, and other common timezones with ISO 8601 support.
• Ordinal Formatting: Human-friendly outputs (e.g., "1st week", "3rd week").
• Zero External Dependencies: Uses only the Python Standard Library (3.10+).

Installation

pip install calendar-smith

To contribute or run tests:

git clone https://github.com/yeiichi/calendar-smith.git
cd calendar-smith
pip install -e ".[dev]"
pytest

CLI Commands

1. calendar-smith

Top-level command with subcommands:

calendar-smith solve 2026
calendar-smith week-span 2020 53
calendar-smith nth
calendar-smith windows 2026-03-17 7 4
calendar-smith tz 2026-03-20T10:00:00+09:00 America/New_York
calendar-smith fiscal-year 2026-04-22 --system jp
calendar-smith csv records.csv records_with_fy.csv --system jp --date-column created_at

2. calendar-smith-csv

Appends a fiscal_year column to an existing CSV file. Supports:

• us: fiscal year ends Sep 30
• jp: fiscal year ends Mar 31

calendar-smith-csv records.csv records_with_fy.csv --system jp --date-column created_at

3. calendar-smith-solve

Lists the Monday-to-Sunday date ranges for every ISO week in a given year.

calendar-smith-solve 2026

4. calendar-smith-nth

Interactive tool to find the ordinal week of the month and the ISO week of the year for any date.

$ calendar-smith-nth
Date? [yyyy-mm-dd] (leave blank for today) >> 2026-02-17

Result:
  Date:       2026-02-17 (Tuesday)
  Month Week: The 3rd week
  Year Week:  The 8th week

5. calendar-smith-week-span

Show the Monday-to-Sunday span for a specific ISO week.

calendar-smith-week-span 2020 53

6. calendar-smith-windows

Generate date windows (consecutive, overlapping, or gapped) from a starting date using a fixed window size and repeat count. Use --sampling-rate (or -s) for overlapping or gapped windows.

# Generate 4 consecutive 7-day windows
calendar-smith-windows 2026-03-17 7 4

# Generate 4 overlapping 7-day windows starting every 1 day
calendar-smith-windows 2026-03-17 7 4 --sampling-rate 1

Example output:

Generated 4 windows starting from 2026-03-17 with size 7:
  Window  1: 2026-03-17 to 2026-03-23
  Window  2: 2026-03-24 to 2026-03-30
  Window  3: 2026-03-31 to 2026-04-06
  Window  4: 2026-04-07 to 2026-04-13

7. calendar-smith-tz

Convert an ISO 8601 datetime string from one timezone to another.

calendar-smith-tz 2026-03-20T10:00:00+09:00 America/New_York
# Output: 2026-03-19T21:00:00-04:00

8. calendar-smith-fiscal-year

Return the fiscal year for a given date.

calendar-smith-fiscal-year 2026-04-22 --system jp
# Output: 2026

Date Parsing Rules

To ensure data integrity, calendar-smith follows these parsing rules:

• Accepted: 2026-02-17, 2026/02/17, 2026.02.17, 2026-2-17, 20260217.

• Rejected:

  • 260217 (6-digit): Rejected to avoid century ambiguity (1926 vs 2026).
  • 2026123 (7-digit): Rejected because it could be Jan 23rd or Dec 3rd.

API Example

from calendar_smith import (
    get_fiscal_year,
    ensure_date,
    get_nth_week_of_month,
    get_dates_windows,
    get_iso_week_span,
    get_iso_weeks_for_year,
    format_ordinal,
    WeekSpan,
    DateRange,
)

# Parse a messy but valid string
d = ensure_date("2026/4/1")

# Get Japanese Fiscal Year (2026)
fy_jp = get_fiscal_year(d, system="jp")

# Get US Fiscal Year (2026 - fiscal year ends Sep 30, 2026)
fy_us = get_fiscal_year(d, system="us")

# Get week of month
week_num = get_nth_week_of_month(d)

# Get a specific ISO week span
span = get_iso_week_span(2026, 1)

# Get all ISO week spans for a year
all_weeks = get_iso_weeks_for_year(2026)

# Generate the next 4 date windows (default: consecutive)
future_windows = get_dates_windows(d, window_size=7, repeats=4)

# Generate overlapping windows (starting every 1 day)
overlapping = get_dates_windows(d, window_size=7, repeats=4, sampling_rate=1)

from calendar_smith import (
    now_utc,
    now_jst,
    to_timezone,
    to_iso,
    from_iso,
    JST,
    ET,
)

# Get current time in JST
dt_jst = now_jst()

# Convert to New York time (ET)
dt_et = to_timezone(dt_jst, ET)

# Get ISO 8601 string
iso_str = to_iso(dt_et)

# Parse ISO 8601 string
dt_parsed = from_iso("2026-03-20T10:00:00+09:00")

License

MIT License. See LICENSE for details.