Basic Holiday Calendar

from mango_calendar import get_calendar

# Get basic Spanish holidays
holidays = get_calendar(
    country="ES",
    start_year=2024,
    end_year=2025
)
print(holidays[['date', 'name']].head())

Advanced Features

# Get holidays with autonomous communities and weights
holidays_with_communities = get_calendar(
    country="ES",
    start_year=2024,
    end_year=2025,
    communities=True,
    return_weights=True,
    calendar_events=True  # Include Black Friday
)

# Calculate distances to holidays
holidays_with_distances = get_calendar(
    country="ES",
    start_year=2024,
    end_year=2025,
    communities=True,
    return_distances=True,
    distances_config={
        "steps_back": 7,
        "steps_forward": 7
    }
)

Date Utilities

from mango_calendar.date_utils import get_holidays_df, get_covid_lockdowns

# Get holidays in a specific format with window bounds
holidays_polars = get_holidays_df(
    steps_back=3,
    steps_forward=7,
    start_year=2024,
    country="ES",
    output_format="polars"
)

# Get COVID lockdown periods
covid_data = get_covid_lockdowns()

Pivot Calendar Data

# Create a pivot table of holidays
pivot_calendar = get_calendar(
    country="ES",
    start_year=2024,
    end_year=2025,
    communities=True,
    return_weights=True,
    pivot=True,
    pivot_keep_communities=True
)

get_calendar()

Main function to retrieve calendar data.

Parameters:

• country (str): Country code (default: “ES”)

• start_year (int): Start year for the calendar (default: 2010)

• end_year (int): End year for the calendar (default: current year + 2)

• communities (bool): Include autonomous community holidays (default: False)

• weight_communities (dict): Custom weights for communities

• calendar_events (bool): Include events like Black Friday (default: False)

• return_weights (bool): Return community weights (default: None)

• return_distances (bool): Return distance calculations (default: False)

• distances_config (dict): Configuration for distance calculations

• name_transformations (bool): Apply name transformations (default: True)

• pivot (bool): Return data in pivot format (default: False)

• pivot_keep_communities (bool): Keep communities when pivoting (default: False)

Returns:

• pd.DataFrame: Calendar data with requested features

get_holidays_df()

Get holidays dataframe with window bounds.

Parameters:

• steps_back (int): Days to go back from holiday

• steps_forward (int): Days to go forward from holiday

• start_year (int): Start year (default: 2014)

• country (str): Country code (default: “ES”)

• output_format (str): “polars” or “pandas” (default: “polars”)

Prerequisites

• Python 3.12+

• uv (recommended) or pip

Setup

# Clone the repository
git clone <repository-url>
cd mango_calendar

# Install dependencies
uv sync

# Run tests
python run_tests.py

Project Structure

mango_calendar/
├── src/
│   └── mango_calendar/
│       ├── __init__.py
│       ├── calendar_features.py
│       └── date_utils.py
├── tests/
│   ├── test_calendar_features.py
│   ├── test_date_utils.py
│   └── test_init.py
├── pyproject.toml
└── README.rst

Dependencies

• holidays>=0.76: Holiday data

• numpy>=2.3.1: Numerical operations

• pandas>=2.3.1: Data manipulation

• polars>=1.31.0: Fast DataFrame operations

• pyarrow>=20.0.0: Columnar data format

• pycountry>=24.6.1: Country information

• unidecode>=1.4.0: Unicode text processing

Development Guidelines

• Follow PEP 8 style guidelines

• Add type hints to all functions

• Write comprehensive docstrings

• Include tests for new features

• Run uv run coverage run -m unittest discover -s tests -p "test_*.py" -v before submitting