retailcalendar

A Python package for working with the NRF 4-5-4 Retail Calendar and public holiday calendars for Brazil and the United States.

The retail calendar groups weeks into months following a 4-5-4 week pattern per quarter, giving retailers a consistent structure for fiscal year reporting. Some years have 53 weeks (a "53-week year") — this package handles that automatically.

Installation

pip install retailcalendar

CLI Usage

# Display the 4-5-4 calendar for the current year
454cal

# Display for a specific year
454cal 2025

# Use a different fiscal year start month (default is January)
454cal --start_month 2 2025

# Disable today and holiday highlights
454cal -d 2025

# Use a color theme
454cal -t ocean 2025
454cal -t sunset 2025

# Use a different holiday region
454cal -r US 2025
454cal -r BR-SP-SAO 2025

# Combine options
454cal -t matrix -r US 2025

The output is a color-formatted calendar printed to the terminal, organized with 3 months per row and week numbers on the left. Public holidays and today's date are highlighted using the active color theme.

CLI Options

Themes

Python API

Cal454 — NRF 4-5-4 Retail Calendar

from retailcalendar import Cal454, CalendarTheme

# Create a calendar for fiscal year 2025 (starts February 2025)
cal = Cal454(year=2025, s_month=2)

# Display the full calendar (holidays highlighted by default)
cal.format_year()
cal.format_year(highlight_today=False, highlight_holidays=False)

# Use a built-in color theme
cal.format_year(theme="ocean")
cal.format_year(theme="volcano", region="US")

# Define a custom theme
my_theme = CalendarTheme(
    year_title="bold blue",
    month_name="cyan",
    day_header="grey50",
    week_number="bright_green",
    today="bold white on dark_blue",
    holiday="bold white on dark_green",
)
cal.format_year(theme=my_theme)

# Get month start/end dates (list of 12 dates)
cal.month_start_dates()
cal.month_end_dates()

# Get quarter start/end dates (list of 4 dates)
cal.quarter_start_dates()
cal.quarter_end_dates()

# Get all weeks in a given month (1-indexed)
cal.month_days_by_week(month=1)

# Get all weeks for the entire year
cal.year_days_by_week()

# Check if a year has 53 weeks
Cal454.has_43_weeks(year=2023)            # True
Cal454.has_43_weeks(year=2023, s_month=1) # False

Cal454 Parameters

format_year() Parameters

HolidayCalendar — Public Holiday Calculator

Calculates public holidays for a given region and year. Regions are defined in holidays.yaml and support inheritance — a city-level region automatically includes state and national holidays.

from retailcalendar import HolidayCalendar

cal = HolidayCalendar("BR-PR-CWB", 2025)

# Full list of holidays as dicts, sorted by date
for h in cal.holidays():
    print(h["date"], h["name"])

# Just the canonical holiday dates
cal.dates()           # list[date]

# Observed (legally effective) dates after weekend shifts
cal.observed_dates()  # list[date]

Each dict returned by holidays() contains:

Supported Regions

Holiday rule types

since field

Holidays with a since year are excluded for earlier years. For example, Brazil's Dia da Consciência Negra (since: 2024) does not appear for 2023 and earlier.

How the 4-5-4 Calendar Works

Each fiscal quarter follows a 4-5-4 week pattern:

The fiscal year normally has 52 weeks. Per NRF rules, a 53rd week is added to the last month of the year when the last day of a standard 52-week year has 4 or more days remaining in the start month. Known 53-week years (February start): 2000, 2006, 2012, 2017, 2023, 2028.

The fiscal year starts on the Sunday on or before February 1 (or the configured start month).

Development

git clone https://github.com/thig0w/454calendar.git
cd 454calendar

# Set up development environment (venv, dev deps, pre-commit hooks)
make devenv

# Run formatter, linter, and tests
make precommit

# Run tests only
uv run pytest

# Build distribution package
make build

# Clean everything
make clean

Requirements: Python 3.10+

License

GNU General Public License v3.0 — see LICENSE.