Quick start

fiscalclock has no built-in calendars. You describe your calendar as a JSON definition, and every answer comes from that definition.

Write a definition

Save this definition as retail-4-5-4.json. It describes a 4-5-4 retail calendar: each fiscal year ends on the Saturday nearest 31 January, each quarter has periods of 4, 5 and 4 weeks, a 53-week year puts its extra week at the end of period 12, and labels look like FY2023 Q4.

retail-4-5-4.json

{
  "spec_version": 1,
  "year": {
    "type": "week_based",
    "anchor": { "edge": "end", "month": 1, "day": "last", "rule": "nearest" }
  },
  "week": { "starts_on": "sunday", "numbering": "contains_start" },
  "subdivision": {
    "type": "week_pattern",
    "periods": [4, 5, 4, 4, 5, 4, 4, 5, 4, 4, 5, 4],
    "quarters": [3, 3, 3, 3],
    "extra_week": { "period": 12 }
  },
  "naming": {
    "default": "nrf",
    "schemes": {
      "nrf": {
        "year_number": "start",
        "templates": {
          "year": "FY{yyyy}",
          "quarter": "FY{yyyy} Q{q}",
          "period": "FY{yyyy} P{pp}",
          "week": "FY{yyyy} W{ww}"
        }
      }
    }
  }
}

This is an example, not a published calendar of any organisation. It is the definition of the conformance vector nrf-53-week-years.json, whose year rule gives the 53-week years that the NRF publishes for its 4-5-4 calendar. The period that takes the extra week and the label templates are this example’s own choices.

Write a definition explains each block.

Ask it about a date

The example locates 3 Feb 2024, prints the labels of its fiscal year, quarter and week, and then prints the bounds of fiscal year 2023 and its number of weeks.

Python

quick_start.py

from pathlib import Path

from fiscalclock import FiscalCalendar

cal = FiscalCalendar(Path("retail-4-5-4.json").read_text(encoding="utf-8"))

here = cal.locate("2024-02-03")
print(cal.format(here.year), "|", cal.format(here.quarter), "|", cal.format(here.week))

fy2023 = cal.period("year", 2023)
print(fy2023.start, fy2023.end_exclusive, fy2023.weeks)

Output

FY2023 | FY2023 Q4 | FY2023 W53
2023-01-29 2024-02-04 53

JavaScript

quick_start.mjs

import { readFileSync } from "node:fs";
import { FiscalCalendar } from "fiscalclock";

const cal = new FiscalCalendar(readFileSync("retail-4-5-4.json", "utf8"));

const here = cal.locate("2024-02-03");
console.log(cal.format(here.year), "|", cal.format(here.quarter), "|", cal.format(here.week));

const fy2023 = cal.period("year", 2023);
console.log(fy2023.start, fy2023.end_exclusive, fy2023.weeks);

Output

FY2023 | FY2023 Q4 | FY2023 W53
2023-01-29 2024-02-04 53

Rust

quick_start.rs

use std::error::Error;
use std::fs;

use fiscalclock::{FiscalCalendar, Level};

fn main() -> Result<(), Box<dyn Error>> {
    let cal = FiscalCalendar::from_json(&fs::read_to_string("retail-4-5-4.json")?)?;

    let here = cal.locate("2024-02-03".parse()?)?;
    println!(
        "{} | {} | {}",
        cal.format(&here.year, None)?,
        cal.format(&here.quarter, None)?,
        cal.format(&here.week, None)?
    );

    let fy2023 = cal.period(Level::Year, 2023, None)?;
    println!("{} {} {:?}", fy2023.start, fy2023.end_exclusive, fy2023.weeks);

    Ok(())
}

Output

FY2023 | FY2023 Q4 | FY2023 W53
2023-01-29 2024-02-04 Some(53)

3 Feb 2024 is the last day of fiscal year 2023, in its fourth quarter and in week 53, the extra week. Fiscal year 2023 starts on 29 Jan 2023 and ends before 4 Feb 2024: every period is a half-open interval with an exclusive end, as Dates and intervals explains.

Next steps

• Write a definition for your own calendar.
• Week-based years explains 52- and 53-week years.
• The API reference lists every operation in each language.