wwdates 0.1.0

Global calendar system. Python package.

wwdates

Global calendar system. Python package.

wwdates fetches official holiday calendars for Brazil (ANBIMA, FEBRABAN, B3) and the United States (Nasdaq, Federal Holidays), then layers a rich set of working-day / date helpers on top — is_working_day, add_working_days, working_days_range, delta_working_days, timezone-aware conversions, and more. Fetched calendars are cached locally so repeated calls stay fast and offline-friendly.

📖 Full documentation: https://guilhermegor.github.io/wwdates/

✨ Key Features

🗓️ Holiday providers

One class per calendar source; all share the same date-operations surface — they differ only in which holidays they load.

Provider	Import	Holidays
DatesBRAnbima	wwdates.br.anbima	🇧🇷 ANBIMA national holidays
DatesBRFebraban	wwdates.br.febraban	🇧🇷 FEBRABAN bank holidays
DatesBRB3	wwdates.br.b3	🇧🇷 ANBIMA + B3 exchange non-trading days
DatesUSNasdaq	wwdates.us.nasdaq	🇺🇸 Nasdaq market closures
DatesUSFederalHolidays	wwdates.us.federal_holidays	🇺🇸 US federal holidays (offline, recommended)
DatesUSFederalHolidaysWeb	wwdates.us.federal_holidays_web	🇺🇸 US federal holidays via live scrape

⚙️ Shared calendar operations

Every provider inherits the full surface: working-day predicates (is_working_day, is_holiday, is_weekend), business-day arithmetic (add_working_days, nearest_working_day, get_nth_weekday_month), ranges & deltas (working_days_range, delta_working_days, delta_working_hours), timezone/timestamp conversions, and locale-aware formatting. See the API Reference for the complete list.

🚀 Getting Started

Prerequisites

• Python 3.10+
• Poetry (recommended)

Installation

pip install wwdates

Or with Poetry:

poetry add wwdates

Everything works offline after install — no browser needed. The recommended DatesUSFederalHolidays computes federal holidays locally.

Optional: the browser-scrape provider ([web] extra)

Only the DatesUSFederalHolidaysWeb provider needs a browser — it scrapes federalholidays.net with Playwright, which is not installed by the base package. It is vital only if you specifically want that provider's live-scraped dates; otherwise skip this entirely and use the offline DatesUSFederalHolidays.

To enable it, install the optional web extra (note the brackets — quote them so the shell does not glob), then fetch the browser binary:

pip install "wwdates[web]"   # adds Playwright
playwright install chromium  # one-time browser download (pip cannot do this step)

Without both steps, constructing/using DatesUSFederalHolidaysWeb raises a clear ImportError telling you to run them.

Quick start

from datetime import date

from wwdates.br.b3 import DatesBRB3

cls_cal = DatesBRB3()
cls_cal.is_working_day(date(2024, 12, 25))       # False — Christmas
cls_cal.add_working_days(date(2024, 12, 24), 3)  # skips holidays + weekends
cls_cal.holidays()                               # [(name, date), ...]

DatesBRB3 here is just an example — the same methods work on every provider; only the loaded holiday set differs. More recipes in the Examples guide.

📚 Documentation

• Usage — install, providers, basics
• Examples — task-oriented recipes
• API Reference — every class and method
• FAQ — common questions & troubleshooting
• Contributing — dev setup, tests, releasing
• Changelog — release history

🛠️ Development

git clone https://github.com/guilhermegor/wwdates.git
cd wwdates
make init                  # or: bash tasks.sh init  (venv + deps + pre-commit hooks)
make unit_tests            # run the test suite
make install_dist_locally  # build the wheel and smoke-import it

See Contributing for the full branch/PR workflow and CI gate.

👨‍💻 Authors

• guilhermegor — GitHub

📜 License

This project is licensed under the MIT License — see LICENSE for details.

🔗 Useful Links

• Documentation
• GitHub Repository
• Issue Tracker