# Croatian Holidays
[](https://pypi.org/project/croatian-holidays/)
[](https://pypi.org/project/croatian-holidays/)
[](LICENSE)
A lightweight Python utility for **Croatian public holidays**: compute holidays for any year, check if today is a holiday, list upcoming holidays, and optionally scrape an external reference page.
- **Pure Python** for computed holidays (Easter, Corpus Christi, + fixed dates)
- **Typed exceptions** and **no print spam** (uses `logging`)
- **Optional web parsing** with timeouts and structural checks
- Pretty-print and JSON save helpers
> Project name on PyPI is **`croatian-holidays`**, while the import name is **`croatian_holidays`**.
> You can check it out on https://pypi.org/project/croatian-holidays/0.1.0/
## Installation
```bash
pip install croatian-holidays
```
or
```bash
pip install croatian-holidays==0.1.0 ## For specific versions
```
## Quick start
```python
import datetime as dt
from croatian_holidays import CroatianHolidays
ch = CroatianHolidays()
# 1) Is today a holiday?
print("Today is holiday:", ch.isHoliday())
# 2) All holidays for a year
hol_2025 = ch.getHolidays(2025) # dict: "dd. mm. yyyy." -> "Holiday name"
print(hol_2025["01. 05. 2025."]) # "Praznik rada"
# 3) Include localized day-of-week and pretty output
print(ch.getHolidays(2025, showdays=True, prettyprint=True))
# 4) Upcoming holidays after now (current year)
print(ch.upcomingHolidays(date=dt.datetime.now(), showdays=True, prettyPrint=True))
# 5) Holidays between two dates (inclusive)
print(ch.getHolidaysBetweenDates("01. 05. 2025.", "31. 12. 2025.", showdays=True, prettyPrint=True))
# 6) Persist to JSON
data = ch.getHolidays(2025, showdays=True)
from croatian_holidays import SaveError
try:
ch.saveToJson(data, "croatia_2025_holidays.json")
except SaveError as e:
print("Saving failed:", e)
```
## Features
- ✅ **Algorithmic dates**: Easter (Meeus/Jones/Butcher), Corpus Christi (+60 days)
- ✅ **Fixed-date holidays**: New Year’s, Statehood Day, All Saints’, etc.
- ✅ **Features**:
- `getHolidays(year, showdays=False, prettyprint=False)`
- `upcomingHolidays(date, showdays=False, prettyPrint=False)`
- `getHolidaysBetweenDates(start_date, end_date, showdays=False, prettyPrint=False)`
- `isHoliday()`
- `getHolidaysFromWeb(base_url=..., prettyPrint=False, timeout=10.0, ...)`
- `prettyPrint(dict)`
- `saveToJson(dict, filename)`
- 🧯 **Errors are explicit** and do not leak prints, using logger
- 🧰 **Logging-friendly**: ships with a `NullHandler`; opt-in to logs in your app.
## Module Reference
> Date strings use `"dd. mm. yyyy."` (note the trailing dot).
### `CroatianHolidays.getHolidays(year, showdays=False, prettyprint=False) -> dict | str`
Return holidays for `year`.
- `showdays=True` → values become `{ "name": ..., "day_of_week": ... }` (Croatian weekday).
- `prettyprint=True` → returns pretty JSON `str` instead of `dict`.
### `CroatianHolidays.upcomingHolidays(date, showdays=False, prettyPrint=False) -> dict | str`
Return upcoming holidays **after** the given `datetime` (current year only).
### `CroatianHolidays.getHolidaysBetweenDates(start_date, end_date, showdays=False, prettyPrint=False, dateformat="%d. %m. %Y.") -> dict | str`
Return holidays within an **inclusive** range. `start_date`/`end_date` can be `str`, `date`, or `datetime`.
### `CroatianHolidays.isHoliday() -> bool`
True if **today** is a holiday.
### `CroatianHolidays.getHolidaysFromWeb(base_url=..., prettyPrint=False, timeout=10.0, session=None, user_agent=None) -> dict | str`
Try to parse an external web page for holidays
### `CroatianHolidays.prettyPrint(json_data: dict) -> str`
Pretty JSON with UTF-8 (no ASCII escapes).
### `CroatianHolidays.saveToJson(data: dict, filename: str, encoding="utf-8") -> None`
Write a dictionary to a JSON file.
## Exceptions
Import from the package root:
```python
from croatian_holidays import (
CroatianHolidaysError, InvalidYearError, DateFormatError,
NetworkError, ParseError, SaveError
)
```
- `InvalidYearError`: year must be `1583..4099` (Gregorian computus range).
- `DateFormatError`: invalid date strings / formatting issues.
- `NetworkError`: timeouts, connection issues, HTTP errors in web fetch.
- `ParseError`: the web page did not match expected structure.
- `SaveError`: file write errors.
- `CroatianHolidaysError`: base class for all package errors.
## Logging
By default, the library is quiet. To see warnings or debug messages:
```python
import logging
logging.basicConfig(level=logging.INFO)
```
## Development
```bash
git clone https://github.com/mgracanin/croatian-holidays.git
cd croatian-holidays
python -m venv .venv && source .venv/bin/activate # or use whatever you like
pip install -e .
```
Recommended tooling (optional):
- **ruff** for linting
- **mypy** for typing
- **pytest** for tests
## Versioning & Compatibility
- Python **3.8+**
- Semantic-ish versioning; breaking API changes bump the minor/major.
## License
MIT — see [LICENSE](LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "croatian-holidays",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "croatia, holidays, calendar, dates, easter, corpus-christi",
"author": null,
"author_email": "Matija Gra\u010danin <matijag@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c1/6c/83ab447f2c5143cc0da2b375143e78a340acb6c37ef5fdba01cbea6a0eca/croatian_holidays-0.1.1.tar.gz",
"platform": null,
"description": "# Croatian Holidays\r\n\r\n[](https://pypi.org/project/croatian-holidays/)\r\n[](https://pypi.org/project/croatian-holidays/)\r\n[](LICENSE)\r\n\r\nA lightweight Python utility for **Croatian public holidays**: compute holidays for any year, check if today is a holiday, list upcoming holidays, and optionally scrape an external reference page.\r\n\r\n- **Pure Python** for computed holidays (Easter, Corpus Christi, + fixed dates)\r\n- **Typed exceptions** and **no print spam** (uses `logging`)\r\n- **Optional web parsing** with timeouts and structural checks\r\n- Pretty-print and JSON save helpers\r\n\r\n> Project name on PyPI is **`croatian-holidays`**, while the import name is **`croatian_holidays`**.\r\n> You can check it out on https://pypi.org/project/croatian-holidays/0.1.0/\r\n\r\n## Installation\r\n\r\n```bash\r\npip install croatian-holidays\r\n```\r\n\r\nor\r\n\r\n```bash\r\npip install croatian-holidays==0.1.0 ## For specific versions\r\n```\r\n\r\n\r\n## Quick start\r\n\r\n```python\r\nimport datetime as dt\r\nfrom croatian_holidays import CroatianHolidays\r\n\r\nch = CroatianHolidays()\r\n\r\n# 1) Is today a holiday?\r\nprint(\"Today is holiday:\", ch.isHoliday())\r\n\r\n# 2) All holidays for a year\r\nhol_2025 = ch.getHolidays(2025) # dict: \"dd. mm. yyyy.\" -> \"Holiday name\"\r\nprint(hol_2025[\"01. 05. 2025.\"]) # \"Praznik rada\"\r\n\r\n# 3) Include localized day-of-week and pretty output\r\nprint(ch.getHolidays(2025, showdays=True, prettyprint=True))\r\n\r\n# 4) Upcoming holidays after now (current year)\r\nprint(ch.upcomingHolidays(date=dt.datetime.now(), showdays=True, prettyPrint=True))\r\n\r\n# 5) Holidays between two dates (inclusive)\r\nprint(ch.getHolidaysBetweenDates(\"01. 05. 2025.\", \"31. 12. 2025.\", showdays=True, prettyPrint=True))\r\n\r\n# 6) Persist to JSON\r\ndata = ch.getHolidays(2025, showdays=True)\r\nfrom croatian_holidays import SaveError\r\ntry:\r\n ch.saveToJson(data, \"croatia_2025_holidays.json\")\r\nexcept SaveError as e:\r\n print(\"Saving failed:\", e)\r\n```\r\n\r\n## Features\r\n\r\n- \u2705 **Algorithmic dates**: Easter (Meeus/Jones/Butcher), Corpus Christi (+60 days)\r\n- \u2705 **Fixed-date holidays**: New Year\u2019s, Statehood Day, All Saints\u2019, etc.\r\n- \u2705 **Features**:\r\n - `getHolidays(year, showdays=False, prettyprint=False)`\r\n - `upcomingHolidays(date, showdays=False, prettyPrint=False)`\r\n - `getHolidaysBetweenDates(start_date, end_date, showdays=False, prettyPrint=False)`\r\n - `isHoliday()`\r\n - `getHolidaysFromWeb(base_url=..., prettyPrint=False, timeout=10.0, ...)`\r\n - `prettyPrint(dict)`\r\n - `saveToJson(dict, filename)`\r\n- \ud83e\uddef **Errors are explicit** and do not leak prints, using logger\r\n- \ud83e\uddf0 **Logging-friendly**: ships with a `NullHandler`; opt-in to logs in your app.\r\n\r\n## Module Reference\r\n\r\n> Date strings use `\"dd. mm. yyyy.\"` (note the trailing dot). \r\n\r\n### `CroatianHolidays.getHolidays(year, showdays=False, prettyprint=False) -> dict | str`\r\nReturn holidays for `year`. \r\n- `showdays=True` \u2192 values become `{ \"name\": ..., \"day_of_week\": ... }` (Croatian weekday).\r\n- `prettyprint=True` \u2192 returns pretty JSON `str` instead of `dict`.\r\n\r\n### `CroatianHolidays.upcomingHolidays(date, showdays=False, prettyPrint=False) -> dict | str`\r\nReturn upcoming holidays **after** the given `datetime` (current year only).\r\n\r\n### `CroatianHolidays.getHolidaysBetweenDates(start_date, end_date, showdays=False, prettyPrint=False, dateformat=\"%d. %m. %Y.\") -> dict | str`\r\nReturn holidays within an **inclusive** range. `start_date`/`end_date` can be `str`, `date`, or `datetime`.\r\n\r\n### `CroatianHolidays.isHoliday() -> bool`\r\nTrue if **today** is a holiday.\r\n\r\n### `CroatianHolidays.getHolidaysFromWeb(base_url=..., prettyPrint=False, timeout=10.0, session=None, user_agent=None) -> dict | str`\r\nTry to parse an external web page for holidays\r\n\r\n### `CroatianHolidays.prettyPrint(json_data: dict) -> str`\r\nPretty JSON with UTF-8 (no ASCII escapes).\r\n\r\n### `CroatianHolidays.saveToJson(data: dict, filename: str, encoding=\"utf-8\") -> None`\r\nWrite a dictionary to a JSON file.\r\n\r\n## Exceptions\r\n\r\nImport from the package root:\r\n\r\n```python\r\nfrom croatian_holidays import (\r\n CroatianHolidaysError, InvalidYearError, DateFormatError,\r\n NetworkError, ParseError, SaveError\r\n)\r\n```\r\n\r\n- `InvalidYearError`: year must be `1583..4099` (Gregorian computus range).\r\n- `DateFormatError`: invalid date strings / formatting issues.\r\n- `NetworkError`: timeouts, connection issues, HTTP errors in web fetch.\r\n- `ParseError`: the web page did not match expected structure.\r\n- `SaveError`: file write errors.\r\n- `CroatianHolidaysError`: base class for all package errors.\r\n\r\n## Logging\r\n\r\nBy default, the library is quiet. To see warnings or debug messages:\r\n\r\n```python\r\nimport logging\r\nlogging.basicConfig(level=logging.INFO)\r\n```\r\n\r\n## Development\r\n\r\n```bash\r\ngit clone https://github.com/mgracanin/croatian-holidays.git\r\ncd croatian-holidays\r\npython -m venv .venv && source .venv/bin/activate # or use whatever you like\r\npip install -e .\r\n```\r\n\r\nRecommended tooling (optional):\r\n- **ruff** for linting\r\n- **mypy** for typing\r\n- **pytest** for tests\r\n\r\n## Versioning & Compatibility\r\n\r\n- Python **3.8+**\r\n- Semantic-ish versioning; breaking API changes bump the minor/major.\r\n\r\n## License\r\n\r\nMIT \u2014 see [LICENSE](LICENSE).\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python library for Croatian public holidays with some computed dates, fixed days and optional web scraping.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/mgracanin/croatian-holidays",
"Issues": "https://github.com/mgracanin/croatian-holidays/issues",
"Repository": "https://github.com/mgracanin/croatian-holidays"
},
"split_keywords": [
"croatia",
" holidays",
" calendar",
" dates",
" easter",
" corpus-christi"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4e76e601ef9c0529222e44db0dea4fc2a427d88e31cb9d4738e358afa7697bb1",
"md5": "11aee80b9fb3b5be51102718443f5173",
"sha256": "f8c4551f9b2125647835e613513246f588d7bf0fb093240627f822113f5a1fac"
},
"downloads": -1,
"filename": "croatian_holidays-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "11aee80b9fb3b5be51102718443f5173",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9260,
"upload_time": "2025-08-13T08:27:57",
"upload_time_iso_8601": "2025-08-13T08:27:57.772652Z",
"url": "https://files.pythonhosted.org/packages/4e/76/e601ef9c0529222e44db0dea4fc2a427d88e31cb9d4738e358afa7697bb1/croatian_holidays-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c16c83ab447f2c5143cc0da2b375143e78a340acb6c37ef5fdba01cbea6a0eca",
"md5": "16a792e05c86c3cde41c579fcbabdc00",
"sha256": "cb3469a7d8c86c0da6492576c94069783ebdad4a5690e491ea51787aa8588a72"
},
"downloads": -1,
"filename": "croatian_holidays-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "16a792e05c86c3cde41c579fcbabdc00",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 9401,
"upload_time": "2025-08-13T08:27:58",
"upload_time_iso_8601": "2025-08-13T08:27:58.616533Z",
"url": "https://files.pythonhosted.org/packages/c1/6c/83ab447f2c5143cc0da2b375143e78a340acb6c37ef5fdba01cbea6a0eca/croatian_holidays-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-13 08:27:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mgracanin",
"github_project": "croatian-holidays",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "croatian-holidays"
}
JSON
