<div align="center">
<h1>Rokh: Iranian Calendar Events Collection</h1>
<br/>
<a href="https://badge.fury.io/py/rokh"><img src="https://badge.fury.io/py/rokh.svg" alt="PyPI version"></a>
<a href="https://www.python.org/"><img src="https://img.shields.io/badge/built%20with-Python3-green.svg" alt="built with Python3"></a>
<a href="https://github.com/openscilab/rokh"><img alt="GitHub repo size" src="https://img.shields.io/github/repo-size/openscilab/rokh"></a>
</div>
----------
## Overview
<p align="justify">
Rokh provides a unified interface for accessing Iranian calendar events across Jalali, Gregorian, and Hijri date systems. It lets you easily retrieve national holidays, cultural events, and religious occasions by simply passing a date. It automatically converts between calendars and return event's description.
You can use it in your apps, bots, and research tools that rely on Iranian date conversions, holidays, and cultural event data.
In Farsi, Rokh is derived from Rokhdad, meaning "event." Rokh itself also means "face" and even refers to the "rook" piece in chess.
</p>
<table>
<tr>
<td align="center">PyPI Counter</td>
<td align="center">
<a href="https://pepy.tech/projects/rokh">
<img src="https://static.pepy.tech/badge/rokh">
</a>
</td>
</tr>
<tr>
<td align="center">Github Stars</td>
<td align="center">
<a href="https://github.com/openscilab/rokh">
<img src="https://img.shields.io/github/stars/openscilab/rokh.svg?style=social&label=Stars">
</a>
</td>
</tr>
</table>
<table>
<tr>
<td align="center">Branch</td>
<td align="center">main</td>
<td align="center">dev</td>
</tr>
<tr>
<td align="center">CI</td>
<td align="center">
<img src="https://github.com/openscilab/rokh/actions/workflows/test.yml/badge.svg?branch=main">
</td>
<td align="center">
<img src="https://github.com/openscilab/rokh/actions/workflows/test.yml/badge.svg?branch=dev">
</td>
</tr>
</table>
## Installation
### PyPI
- Check [Python Packaging User Guide](https://packaging.python.org/installing/)
- Run `pip install rokh==0.1`
### Source code
- Download [Version 0.1](https://github.com/openscilab/rokh/archive/v0.1.zip) or [Latest Source](https://github.com/openscilab/rokh/archive/dev.zip)
- Run `pip install .`
## Usage
Use `get_events` to retrieve all Iranian calendar events for a given date.
Simply specify the date (in Jalali, Gregorian, or Hijri format), and the function returns corresponding events.
```pycon
>>> from rokh import get_events, DateSystem
>>> result = get_events(day=1, month=1, year=1403, input_date_system=DateSystem.JALALI)
# {
# 'events': {
# 'gregorian': [
# {
# 'description': 'روز جهانی شادی',
# 'is_holiday': False
# }
# ],
# 'hijri': [],
# 'jalali': [
# {
# 'description': 'جشن نوروز/جشن سال نو',
# 'is_holiday': True
# }
# ]
# },
# 'gregorian_date': {'day': 20, 'month': 3, 'year': 2024},
# 'hijri_date': {'day': 10, 'month': 9, 'year': 1445},
# 'jalali_date': {'day': 1, 'month': 1, 'year': 1403},
# 'is_holiday': True,
# 'input_date_system': 'jalali',
# 'event_date_system': 'all'
# }
```
## Issues & bug reports
Just fill an issue and describe it. We'll check it ASAP! or send an email to [rokh@openscilab.com](mailto:rokh@openscilab.com "rokh@openscilab.com").
- Please complete the issue template
## References
<blockquote>1- <a href="https://www.time.ir/">ساعت و تقویم ایران | تاریخ امروز | Time.ir</a></blockquote>
<blockquote>2- <a href="https://holidayapi.ir/">Jalali Holiday API</a></blockquote>
## Show your support
### Star this repo
Give a ⭐️ if this project helped you!
### Donate to our project
If you do like our project and we hope that you do, can you please support us? Our project is not and is never going to be working for profit. We need the money just so we can continue doing what we do ;-) .
<a href="https://openscilab.com/#donation" target="_blank"><img src="https://github.com/openscilab/rokh/raw/main/otherfiles/donation.png" width="270" alt="Rokh Donation"></a>
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
## [Unreleased]
## [0.1] - 2025-10-25
### Added
- `get_events` function
- `DateSystem` enum
- Jalali events
- Gregorian events
- Hijri events
[Unreleased]: https://github.com/openscilab/rokh/compare/v0.1...dev
[0.1]: https://github.com/openscilab/rokh/compare/0397711...v0.1
Raw data
{
"_id": null,
"home_page": "https://github.com/openscilab/rokh",
"name": "rokh",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "events date date-system calendar gregorian hijri jalali",
"author": "Rokh Development Team",
"author_email": "rokh@openscilab.com",
"download_url": "https://files.pythonhosted.org/packages/f2/e5/59086cb3eb3c4898543c8aeb27787b9a32f03032f223aaa8cba3bf770447/rokh-0.1.tar.gz",
"platform": null,
"description": "\n<div align=\"center\">\n <h1>Rokh: Iranian Calendar Events Collection</h1>\n <br/>\n <a href=\"https://badge.fury.io/py/rokh\"><img src=\"https://badge.fury.io/py/rokh.svg\" alt=\"PyPI version\"></a>\n <a href=\"https://www.python.org/\"><img src=\"https://img.shields.io/badge/built%20with-Python3-green.svg\" alt=\"built with Python3\"></a>\n <a href=\"https://github.com/openscilab/rokh\"><img alt=\"GitHub repo size\" src=\"https://img.shields.io/github/repo-size/openscilab/rokh\"></a>\n\n</div>\n\n----------\n\n\n## Overview\n<p align=\"justify\">\nRokh provides a unified interface for accessing Iranian calendar events across Jalali, Gregorian, and Hijri date systems. It lets you easily retrieve national holidays, cultural events, and religious occasions by simply passing a date. It automatically converts between calendars and return event's description.\nYou can use it in your apps, bots, and research tools that rely on Iranian date conversions, holidays, and cultural event data.\n\nIn Farsi, Rokh is derived from Rokhdad, meaning \"event.\" Rokh itself also means \"face\" and even refers to the \"rook\" piece in chess.\n\n</p>\n\n<table>\n <tr>\n <td align=\"center\">PyPI Counter</td>\n <td align=\"center\">\n <a href=\"https://pepy.tech/projects/rokh\">\n <img src=\"https://static.pepy.tech/badge/rokh\">\n </a>\n </td>\n </tr>\n <tr>\n <td align=\"center\">Github Stars</td>\n <td align=\"center\">\n <a href=\"https://github.com/openscilab/rokh\">\n <img src=\"https://img.shields.io/github/stars/openscilab/rokh.svg?style=social&label=Stars\">\n </a>\n </td>\n </tr>\n</table>\n<table>\n <tr> \n <td align=\"center\">Branch</td>\n <td align=\"center\">main</td>\n <td align=\"center\">dev</td>\n </tr>\n <tr>\n <td align=\"center\">CI</td>\n <td align=\"center\">\n <img src=\"https://github.com/openscilab/rokh/actions/workflows/test.yml/badge.svg?branch=main\">\n </td>\n <td align=\"center\">\n <img src=\"https://github.com/openscilab/rokh/actions/workflows/test.yml/badge.svg?branch=dev\">\n </td>\n </tr>\n</table>\n\n\n## Installation\n\n### PyPI\n- Check [Python Packaging User Guide](https://packaging.python.org/installing/)\n- Run `pip install rokh==0.1`\n### Source code\n- Download [Version 0.1](https://github.com/openscilab/rokh/archive/v0.1.zip) or [Latest Source](https://github.com/openscilab/rokh/archive/dev.zip)\n- Run `pip install .`\n\n## Usage\n\nUse `get_events` to retrieve all Iranian calendar events for a given date.\nSimply specify the date (in Jalali, Gregorian, or Hijri format), and the function returns corresponding events.\n\n```pycon\n>>> from rokh import get_events, DateSystem\n>>> result = get_events(day=1, month=1, year=1403, input_date_system=DateSystem.JALALI)\n# {\n# 'events': {\n# 'gregorian': [\n# {\n# 'description': '\u0631\u0648\u0632 \u062c\u0647\u0627\u0646\u06cc \u0634\u0627\u062f\u06cc',\n# 'is_holiday': False\n# }\n# ],\n# 'hijri': [],\n# 'jalali': [\n# {\n# 'description': '\u062c\u0634\u0646 \u0646\u0648\u0631\u0648\u0632/\u062c\u0634\u0646 \u0633\u0627\u0644 \u0646\u0648',\n# 'is_holiday': True\n# }\n# ]\n# },\n# 'gregorian_date': {'day': 20, 'month': 3, 'year': 2024},\n# 'hijri_date': {'day': 10, 'month': 9, 'year': 1445},\n# 'jalali_date': {'day': 1, 'month': 1, 'year': 1403},\n# 'is_holiday': True,\n# 'input_date_system': 'jalali',\n# 'event_date_system': 'all'\n# }\n```\n\n## Issues & bug reports\n\nJust fill an issue and describe it. We'll check it ASAP! or send an email to [rokh@openscilab.com](mailto:rokh@openscilab.com \"rokh@openscilab.com\"). \n\n- Please complete the issue template\n\n\n## References\n\n<blockquote>1- <a href=\"https://www.time.ir/\">\u0633\u0627\u0639\u062a \u0648 \u062a\u0642\u0648\u06cc\u0645 \u0627\u06cc\u0631\u0627\u0646 | \u062a\u0627\u0631\u06cc\u062e \u0627\u0645\u0631\u0648\u0632 | Time.ir</a></blockquote>\n<blockquote>2- <a href=\"https://holidayapi.ir/\">Jalali Holiday API</a></blockquote>\n\n\n## Show your support\n\n\n### Star this repo\n\nGive a \u2b50\ufe0f if this project helped you!\n\n### Donate to our project\nIf you do like our project and we hope that you do, can you please support us? Our project is not and is never going to be working for profit. We need the money just so we can continue doing what we do ;-) .\t\t\t\n\n<a href=\"https://openscilab.com/#donation\" target=\"_blank\"><img src=\"https://github.com/openscilab/rokh/raw/main/otherfiles/donation.png\" width=\"270\" alt=\"Rokh Donation\"></a>\n# Changelog\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)\nand this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).\n\n## [Unreleased]\n## [0.1] - 2025-10-25\n### Added\n- `get_events` function\n- `DateSystem` enum\n- Jalali events\n- Gregorian events\n- Hijri events\n\n\n[Unreleased]: https://github.com/openscilab/rokh/compare/v0.1...dev\n[0.1]: https://github.com/openscilab/rokh/compare/0397711...v0.1\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Rokh: Iranian Calendar Events Collection",
"version": "0.1",
"project_urls": {
"Download": "https://github.com/openscilab/rokh/tarball/v0.1",
"Homepage": "https://github.com/openscilab/rokh",
"Source": "https://github.com/openscilab/rokh"
},
"split_keywords": [
"events",
"date",
"date-system",
"calendar",
"gregorian",
"hijri",
"jalali"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "90f3deb0ef327d3b59cbc992cf38c50eb65dec8f09d308f51a3057f7761a2942",
"md5": "63e0e13e0019fe271bb1f2a43b4afd85",
"sha256": "cf6f17dfd86f3cad1254365fda7854041dd315bc307069f3bfb7e63d294af9cc"
},
"downloads": -1,
"filename": "rokh-0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "63e0e13e0019fe271bb1f2a43b4afd85",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 35210,
"upload_time": "2025-10-25T11:51:09",
"upload_time_iso_8601": "2025-10-25T11:51:09.474962Z",
"url": "https://files.pythonhosted.org/packages/90/f3/deb0ef327d3b59cbc992cf38c50eb65dec8f09d308f51a3057f7761a2942/rokh-0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f2e559086cb3eb3c4898543c8aeb27787b9a32f03032f223aaa8cba3bf770447",
"md5": "c260ed877f9df19ec02ac146865296c0",
"sha256": "8b5f617430bb482a2fe48e38e648bf0b2c68f7813e0252b21c959d7359ea76aa"
},
"downloads": -1,
"filename": "rokh-0.1.tar.gz",
"has_sig": false,
"md5_digest": "c260ed877f9df19ec02ac146865296c0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 37718,
"upload_time": "2025-10-25T11:51:07",
"upload_time_iso_8601": "2025-10-25T11:51:07.828726Z",
"url": "https://files.pythonhosted.org/packages/f2/e5/59086cb3eb3c4898543c8aeb27787b9a32f03032f223aaa8cba3bf770447/rokh-0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-25 11:51:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "openscilab",
"github_project": "rokh",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "jdatetime",
"specs": [
[
">=",
"3.8.2"
]
]
},
{
"name": "hijridate",
"specs": [
[
">=",
"2.3.0"
]
]
}
],
"lcname": "rokh"
}
JSON
