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.

Most sources come in two flavours: an offline class (the default — no network, no cache) and a *Web class that reads the publisher's live page.

⚙️ 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

Guilherme Rodrigues

🔗 Useful Links

• Documentation
• GitHub Repository
• Issue Tracker

🤝 Contributing

Issues and PRs are welcome. Please read CONTRIBUTING.md first for dev setup, tests, the branch/PR workflow, and the CI gate.

📜 License

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