jaldt

Jaldt is a package for working with date and time based on Jalali calendar and date.


License
MIT
Install
pip install jaldt==1.0.0

Documentation

Jaldt

pypi license

img1

Jaldt is a package for working with date and time based on Jalali calendar and date.

Table of Contents:

How to install

You can download and install this package directly from pypi repository by pip module. (Make sure you are using Python3)

python3 -m pip install jaldt  

Functions

This package contains some simple functions to work with date and time in the format of Jalali date, which you can follow the explanations of these functions.

g2j:

With this function, you can easily convert the Gregorian date to Jalali date and receive the output in a list that includes the converted year, month and day.

Example:

from jaldt import g2j

year, month, day = g2j(2023, 1, 10)

print(f'{year}/{month}/{day}')

output:

1401/10/20

j2g:

With this function, you can easily convert the Jalali date to Gregorian date and receive the output in a list that includes the converted year, month and day.

Example:

from jaldt import j2g

year, month, day = j2g(1401, 10, 20)

print(f'{year}/{month}/{day}')

output:

2023/1/10

now:

With this function, you can get the current date and time in Jalali date with various formats.

Example:

from jaldt import now

current_date_and_time_in_jalali = now()
print(current_date_and_time_in_jalali)

output:

۱۴۰۱/۱۰/۲۰ ۱۶:۲۳:۰۳.۵۶۰۴۲۲

strftime argument:

The strftime argument allows you to specify your desired output by specifying symbols.

Symbol Description Output
%a Abbreviated weekday name. sha, 1sh, ..
%A Full weekday name. shanbe, 1shanbe, ...
%-d Day of the month as a decimal number. 1, 2, ..., 31
%d Day of the month as a zero added decimal. 01, 02, ..., 31
%b Abbreviated month name. far, ord, ..., esf
%B Full month name. farvardin, ordibehesht, ...
%-m Month as a decimal number. 1, 2, ..., 12
%m Month as a zero added decimal number. 01, 02, ..., 12
%Y Year with century as a decimal number. 1401, 1402, ...
%y Year without century as a zero added decimal number. 01, 02, ...
%-H Hour (24-hour clock) as a decimal number. 0, 1, ..., 23
%H Hour (24-hour clock) as a zero added decimal number. 00, 01, ..., 23
%-I Hour (12-hour clock) as a decimal number. 1, 2, ..., 12
%I Hour (12-hour clock) as a zero added decimal number. 01, 02, ..., 12
%p Locale’s AM or PM. AM, PM
%-M Minute as a decimal number. 0, 1, ..., 59
%M Minute as a zero added decimal number. 00, 01, ..., 59
%-S Second as a decimal number. 0, 1, ..., 59
%S Second as a zero added decimal number. 00, 01, ..., 59

Example: Print the current time similar to a 12-hour digital clock.

from jaldt import now

farsi_clock = now(strftime='%I:%M %p', lang='farsi')
fingilish_clock = now(strftime='%I:%M %p', lang='fingilish')

print(farsi_clock)
print(fingilish_clock)

output:

۰۷:۰۷ بعد از ظهر
07:07 PM

lang argument:

The lang argument is used to specify the output language. It is used in two modes: farsi and fingilish. The default value of this argument is farsi.

Example:

from jaldt import now

farsi_datetime = now(lang='farsi')
fingilish_datetime = now(lang='fingilish')

print(farsi_datetime)
print(fingilish_datetime)

output:

۱۴۰۱/۱۰/۲۱ ۱۹:۲۵:۳۱.۸۶۲۹۱۲
1401/10/21 19:25:31.862958

calendar:

With the calendar function, you can print the Jalali calendar with different colors in farsi and fingilish languages.

Example:

from jaldt import calendar

calendar()

output:

img2

month argument:

The month argument allows you to print the calendar of the month you want. The value of this argument must be one of the Jalali months, and its default value is 'now', which refers to the current month.

Jalali months Confirmed value
فروردین 'farvardin'
اردیبهشت 'ordibehesht'
خرداد 'khordad'
تیر 'tir'
مرداد 'mordad'
شهریور 'shahrivar'
مهر 'mehr'
آبان 'aban'
آذر 'azar'
دی 'dey'
بهمن 'bahman'
اسفند 'esfand'

Example:

from jaldt import calendar

autumn_months = ['mehr', 'aban', 'azar']
for month in autumn_months:
    calendar(month=month, color='yellow')

output:

img3

lang argument:

The lang argument is used to specify the output language. It is used in two modes: farsi and fingilish. The default value of this argument is farsi.

Example:

from jaldt import calendar

for language in ['farsi', 'fingilish']:
    calendar(lang=language)

output:

img4

color argument:

The color argument allows you to change the color of the calendar using ANSI codes. Make sure your shell supports ANSI codes!

Colors ANSI Codes Confirmed value
default \x1b[0m 'def'
gray \x1b[90m 'gray'
red \x1b[91m 'red'
green \x1b[92m 'green'
yellow \x1b[93m 'yellow'
blue \x1b[94m 'blue'
pink \x1b[95m 'pink'
cyan \x1b[36m 'cyan'
black \x1b[30m 'black'

Example:
from jaldt import calendar

calendar(color='yellow')

output:

img5

style argument:

The style argument allows you to specify how to display the current day in three modes: highlight, underline and blink. The default value of this argument is highlight.

Example:

from jaldt import calendar

calendar(style='blink')

output:

img6

events:

This function returns all the historical events of the selected month in the form of a dictionary or prints it on the screen.

Example:

from jaldt import events

current_month_events = events()

for day, event in current_month_events.items():
    print(day, event)

output:

۱ روز میلاد خورشید؛ جشن خرم روز، نخستین جشن دیگان
۴ ['روز بزرگداشت دوستی', 'جشن کریسمس']
۵ ['سالروز شهادت آشو زرتشت، اَبَراِنسان بزرگ تاریخ', 'زمین لرزه ی بم ۱۳۸۲']
۸ دی به آذر روز، دومین جشن دیگان
۱۱ جشن آغاز سال نو میلادی
۱۳ شهادت سردار حاج قاسم سلیمانی در سال ۱۳۹۸
۱۵ دی به مهر روز، سومین جشن دیگان
۱۶ غرق شدن کشتی سانچی در سال ۱۳۹۶
۱۸ شلیک به پرواز ۷۵۲ هواپیمایی اوکراین توسط جمهوری اسلامی در سال ۱۳۹۸
۱۹ درگذشت اکبر هاشمی رفسنجانی در سال ۱۳۹۵
۲۰ قتل امیرکبیر به دستور ناصرالدین شاه قاجار در سال ۱۲۳۰
۲۳ دی به دین روز، چهارمین جشن دیگان
۳۰ آتش سوزی و فروریختن ساختمان پلاسکو در سال ۱۳۹۵

month argument:

The month argument allows you to access historical events for any month you choose.

Jalali months Confirmed value
فروردین 'farvardin'
اردیبهشت 'ordibehesht'
خرداد 'khordad'
تیر 'tir'
مرداد 'mordad'
شهریور 'shahrivar'
مهر 'mehr'
آبان 'aban'
آذر 'azar'
دی 'dey'
بهمن 'bahman'
اسفند 'esfand'

Example:
from jaldt import events

aban_events = events(month='aban')

for day, event in aban_events.items():
  print(day, event)

output:

۱ روز آمار و برنامه ریزی
۷ سالروز ورود کوروش بزرگ به بابل در سال ۵۳۹ پیش از میلاد
۸ روز نوجوان
۱۰ آبان روز، جشن آبانگان
۱۳ روز دانش آموز
۱۴ روز فرهنگ عمومی
۱۵ جشن میانه پاییز
۱۸ روز ملی کیفیت
۲۳ روز جهانی دیابت
۲۴ ['شروع اعتراضات سراسری به دلیل گران شدن نرخ بنزین در سال ۱۳۹۸', 'روز کتاب و کتابخوانی']
۲۶ روز جهانی فلسفه
۲۸ روز جهانی آقایان
۲۹ روز جهانی کودک

inplace argument:

The inplace argument allows you to get the output or have it automatically printed to the screen. (True Value for printing events)

Example:

from jaldt import events

events(month=6, inplace=True)

output:

شهریور ۱: روز بزرگداشت ابوعلی سینا و روز پزشک
شهریور ۲:  آغاز هفته دولت
شهریور ۴: شهریور روز، جشن شهریورگان -  زادروز داراب (کوروش)
شهریور ۵: روز بزرگداشت محمدبن زکریای رازی و روز داروساز
شهریور ۸: انفجار در دفتر نخست‌وزیری جمهوری اسلامی ایران، روز مبارزه با تروریسم
شهریور ۱۱: روز صنعت چاپ
شهریور ۱۳: روز بزرگداشت ابوریحان بیرونی
شهریور ۱۷: قیام ۱۷ شهریور
شهریور ۱۹: روز جهانی پیشگیری از خودکشی
شهریور ۲۰: حمله به برج‌های دوقلوی مرکز تجارت جهانی
شهریور ۲۱: روز سینما
شهریور ۲۲: به قتل رسیدن مهسا امینی توسط جمهوری اسلامی در سال ۱۴۰۱ و شروع اعتراضات سراسری (زن، زندگی، آزادی) - روز گرامیداشت برنامه نویسان
شهریور ۲۷: روز شعر و ادب پارسی و روز بزرگداشت استاد شهریار
شهریور ۳۰: روز جهانی صلح
شهریور ۳۱: آغاز هفته دفاع مقدس

Contribute

To contribute to this project, you can simply do so by making modifications and then making a merge request. For now this is a simple project and I have these ideas for development:

  • Adding Lunar date (Qamari) events to the events function
  • Add more formats to the now function
  • Age calculation by Jalali's date of birth
  • Convert English numbers to Farsi and vice versa

Resources

Converting Gregorian date to Jalali date and vice versa: https://jdf.scr.ir/jdf/python

Events of Jalali history: https://www.time.ir