rokh 0.3

Rokh: Iranian Calendar Events Collection

Rokh: Iranian Calendar Events Collection

---

Overview

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.

PyPI Counter
Github Stars

Branch	main	dev
CI

Code Quality

Installation

PyPI

• Check Python Packaging User Guide
• Run pip install rokh==0.3

Source code

• Download Version 0.3 or Latest Source
• Run pip install .

Usage

Get events

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.

>>> from rokh import get_events, DateSystem
>>> 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'
# }

Get today events

Use get_today_events to retrieve today events.

>>> from rokh import get_today_events, DateSystem
>>> get_today_events()
# {
#    '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': 'gregorian',
#    'event_date_system': 'all'
# }

Issues & bug reports

Just fill an issue and describe it. We'll check it ASAP! or send an email to [e-mail].

• Please complete the issue template

You can also join our discord server

References

1- ساعت و تقویم ایران | تاریخ امروز | Time.ir

2- Jalali Holiday API

3- United Nations List of International Days and Weeks

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 ;-) .

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

Unreleased

0.3 - 2025-12-21

Added

• United nations list of international days and weeks

Changed

• README.md updated
• Gregorian events typo fixed

0.2 - 2025-11-20

Added

• Logo
• get_today_events function
• Event issue template

Changed

• README.md updated
• get_events function current year bug fixed

0.1 - 2025-10-25

Added

• get_events function
• DateSystem enum
• Jalali events
• Gregorian events
• Hijri events