calendar_smith package

Submodules

calendar_smith.core module

class calendar_smith.core.DateRange(start: date, end: date)

Bases: NamedTuple

Simple date range with start and end dates.

end: date

Alias for field number 1

start: date

Alias for field number 0

class calendar_smith.core.WeekSpan(number: int, start: date, end: date)

Bases: NamedTuple

ISO week span with week number, start date, and end date.

end: date

Alias for field number 2

number: int

Alias for field number 0

start: date

Alias for field number 1

calendar_smith.core.get_dates_windows(start_date: date, window_size: int, repeats: int, sampling_rate: int | None = None) → list[DateRange]

Return date windows based on a sampling rate.

Parameters:

• start_date – The starting date of the first window.

• window_size – The duration of each window in days.

• repeats – Number of windows to generate.

• sampling_rate – The number of days between the start of each window. Defaults to window_size, which produces consecutive non-overlapping windows.

calendar_smith.core.get_fiscal_year(date_obj: date, system: str = 'us') → int

Return the fiscal year for a date.

Supported systems:

• us: fiscal year starts Oct 1

• jp: fiscal year starts Apr 1

calendar_smith.core.get_iso_week_span(iso_year: int, iso_week: int) → WeekSpan

Return the Monday-to-Sunday span for an ISO week.

calendar_smith.core.get_iso_weeks_for_year(year: int) → List[WeekSpan]

Return all ISO week spans for a given year.

calendar_smith.core.get_nth_week_of_month(date_obj: date) → int

Return the 1-based week number within the month.

calendar_smith.time module

calendar_smith.time.from_iso(value: str) → datetime

Parse an ISO 8601 string into an aware datetime.

Raises:

ValueError – If the parsed datetime is naive.

calendar_smith.time.now_et() → datetime

Return the current datetime in America/New_York.

calendar_smith.time.now_in(timezone: ZoneInfo) → datetime

Return the current datetime in the given timezone.

calendar_smith.time.now_jst() → datetime

Return the current datetime in Asia/Tokyo.

calendar_smith.time.now_utc() → datetime

Return the current UTC datetime.

calendar_smith.time.to_iso(dt: datetime) → str

Return an ISO 8601 string for an aware datetime.

Raises:

ValueError – If dt is naive.

calendar_smith.time.to_timezone(dt: datetime, timezone: ZoneInfo) → datetime

Convert an aware datetime to another timezone.

Raises:

ValueError – If dt is naive.

calendar_smith.time.tz(name: str) → ZoneInfo

Return a timezone from an IANA name.

Example

tz(“Australia/Sydney”)

calendar_smith.utils module

calendar_smith.utils.ensure_date(date_input: str | date | None) → date

Convert a string, date, or None into a datetime.date.

calendar_smith.utils.format_ordinal(n: int) → str

Return n as an ordinal string, such as 1st or 22nd.

calendar_smith.utils.parse_date_lenient(date_str: str) → date

Parse common date formats and reject ambiguous shorthand values.

calendar_smith.cli module

calendar_smith.cli.build_parser()

calendar_smith.cli.convert_timezone()

calendar_smith.cli.convert_timezone_args(args)

Convert an ISO 8601 datetime to another timezone.

calendar_smith.cli.determine_nth_week()

calendar_smith.cli.determine_nth_week_args(_args)

Show the week number within a month.

calendar_smith.cli.fiscal_year()

calendar_smith.cli.generate_windows()

calendar_smith.cli.generate_windows_args(args)

Generate date windows with optional sampling rate.

calendar_smith.cli.get_fiscal_year_args(args)

Return the fiscal year for a date.

calendar_smith.cli.main(argv=None)

Top-level CLI entry point.

calendar_smith.cli.process_csv()

calendar_smith.cli.process_csv_args(args)

Add a fiscal year column to a CSV.

calendar_smith.cli.solve_week_span()

calendar_smith.cli.solve_week_span_args(args)

Show the span for a specific ISO week.

calendar_smith.cli.solve_weeks()

calendar_smith.cli.solve_weeks_args(args)

List ISO week ranges for a year.

Module contents

Calendar-Smith: Lightweight fiscal and ISO calendar utilities.

class calendar_smith.DateRange(start: date, end: date)

Bases: NamedTuple

Simple date range with start and end dates.

end: date

Alias for field number 1

start: date

Alias for field number 0

class calendar_smith.WeekSpan(number: int, start: date, end: date)

Bases: NamedTuple

ISO week span with week number, start date, and end date.

end: date

Alias for field number 2

number: int

Alias for field number 0

start: date

Alias for field number 1

calendar_smith.ensure_date(date_input: str | date | None) → date

Convert a string, date, or None into a datetime.date.

calendar_smith.fiscal_year()

calendar_smith.format_ordinal(n: int) → str

Return n as an ordinal string, such as 1st or 22nd.

calendar_smith.from_iso(value: str) → datetime

Parse an ISO 8601 string into an aware datetime.

Raises:

ValueError – If the parsed datetime is naive.

calendar_smith.get_dates_windows(start_date: date, window_size: int, repeats: int, sampling_rate: int | None = None) → list[DateRange]

Return date windows based on a sampling rate.

Parameters:

• start_date – The starting date of the first window.

• window_size – The duration of each window in days.

• repeats – Number of windows to generate.

• sampling_rate – The number of days between the start of each window. Defaults to window_size, which produces consecutive non-overlapping windows.

calendar_smith.get_fiscal_year(date_obj: date, system: str = 'us') → int

Return the fiscal year for a date.

Supported systems:

• us: fiscal year starts Oct 1

• jp: fiscal year starts Apr 1

calendar_smith.get_iso_week_span(iso_year: int, iso_week: int) → WeekSpan

Return the Monday-to-Sunday span for an ISO week.

calendar_smith.get_iso_weeks_for_year(year: int) → List[WeekSpan]

Return all ISO week spans for a given year.

calendar_smith.get_nth_week_of_month(date_obj: date) → int

Return the 1-based week number within the month.

calendar_smith.main(argv=None)

Top-level CLI entry point.

calendar_smith.now_et() → datetime

Return the current datetime in America/New_York.

calendar_smith.now_in(timezone: ZoneInfo) → datetime

Return the current datetime in the given timezone.

calendar_smith.now_jst() → datetime

Return the current datetime in Asia/Tokyo.

calendar_smith.now_utc() → datetime

Return the current UTC datetime.

calendar_smith.to_iso(dt: datetime) → str

Return an ISO 8601 string for an aware datetime.

Raises:

ValueError – If dt is naive.

calendar_smith.to_timezone(dt: datetime, timezone: ZoneInfo) → datetime

Convert an aware datetime to another timezone.

Raises:

ValueError – If dt is naive.

calendar_smith.tz(name: str) → ZoneInfo

Return a timezone from an IANA name.

Example

tz(“Australia/Sydney”)