Introduction¶

Basic Usage¶

Importing¶

>>> from khayyam import *

This will imports khayyam.JalaliDate, khayyam.JalaliDatetime, khayyam.Timezone, khayyam.TehranTimezone, khayyam.MINYEAR, khayyam.MAXYEAR, khayyam.SATURDAY, khayyam.SUNDAY, khayyam.MONDAY, khayyam.THURSDAY, khayyam.WEDNESDAY, khayyam.TUESDAY, khayyam.FRIDAY

Or

>>> from khayyam import JalaliDatetime, TehranTimezone

And:

>>> print(JalaliDatetime)
<class 'khayyam.jalali_datetime.JalaliDatetime'>

Instantiating¶

Simply you can instantiate khayyam.JalaliDate and khayyam.JalaliDatetime classes just like the other regular python classes.

>>> JalaliDate(1345)
khayyam.JalaliDate(1345, 1, 1, Doshanbeh)

>>> JalaliDate(427, 2, 28) # Khayyam's birthday
khayyam.JalaliDate(427, 2, 28, Panjshanbeh)

>>> JalaliDate(1345, 12, 30) 
ValueError: .... # So, it's not a leap year!

>>> JalaliDate(1346, 12, 30) # A leap year.
khayyam.JalaliDate(1346, 12, 30, Chaharshanbeh)

>>> JalaliDatetime(JalaliDate(1345, 1, 1))
khayyam.JalaliDatetime(1345, 1, 1, 0, 0, 0, 0, Doshanbeh)

>>> from datetime import datetime
>>> JalaliDatetime(datetime(1982, 9, 6))
khayyam.JalaliDatetime(1361, 6, 15, 0, 0, 0, 0, Doshanbeh)

>>> JalaliDatetime()
khayyam.JalaliDatetime(1, 1, 1, 0, 0, 0, 0, Jomeh)

Interesting! the calendar starting by friday.

Adjusting microseconds:

>>> JalaliDatetime(989, 3, 25, 10, 43, 23, 345453)
khayyam.JalaliDatetime(989, 3, 25, 10, 43, 23, 345453, Seshanbeh)

Current date and time¶

>>> JalaliDatetime.now() 
khayyam.JalaliDatetime(1394, 4, 30, 20, 49, 55, 205834, Seshanbeh)

>>> print(JalaliDatetime.now())) 
1394-04-30 20:56:20.991585

DST aware

>>> print(JalaliDatetime.now(TehranTimezone())) 
1394-04-30 19:59:12.935506+04:30

>>> print(JalaliDatetime.now(TehranTimezone()) - timedelta(days=6*30)) 
1393-11-02 20:01:11.663719+03:30

As you see, the DST offset in the second statement is +3:30. so the khayyam.TehranTimezone is supporting daylight saving time properly.

Today

>>> JalaliDate.today() 
khayyam.JalaliDate(1394, 4, 30, Seshanbeh)

>>> print(JalaliDate.today()) 
1394-4-30

>>> print(JalaliDate.today().strftime('%A %d %B %Y')) 
چهارشنبه 31 تیر 1394

>>> print(JalaliDate(1394, 5, 1).strftime('%A %D %B %N'))
پنجشنبه ۱ مرداد ۱۳۹۴

Right-to-left¶

Additionally, if right to left text rendering is not supported by your terminal emulator:

ﻅ.ﺏ 05:45:40 1394 ﺩاﺩﺮﻣ 01 ﻪﺒﻨﺸﺠﻨﭘ

You can install the rtl package:

$ pip install rtl

And then use it to reshape and change direction of the text

>>> from rtl import rtl
>>> print(rtl(JalaliDatetime(1394, 5, 1, 17, 45, 40).strftime('%C'))) 
پنجشنبه 01 مرداد 1394 05:45:40 ب.ظ

rprint() function¶

If you are using python2 its good to import new print function:

>>> from __future__ import print_function

Extending your practice environment by defining a handy print function for RTL:

>>> def rprint(s):
...     print(rtl(s))

>>> rprint(JalaliDatetime(1394, 5, 1, 17, 45, 40).strftime('%C')) 
پنجشنبه 01 مرداد 1394 05:45:40 ب.ظ

Formatting & Parsing¶

All Supported format directives are listed here: Formatting and Parsing directives.

All formatting behaviours are driven from strftime() and strptime() Behavior.

To format locale’s date & time:

>>> from khayyam import JalaliDatetime
>>> dt = JalaliDatetime(1394, 4, 31, 17, 45, 40)
>>> time_string = dt.strftime('%C')
>>> print(time_string)
چهارشنبه ۳۱ تیر ۱۳۹۴ ۰۵:۴۵:۴۰ ب.ظ

And parsing it again to a khayyam.JalaliDatetime instance:

>>> JalaliDatetime.strptime(time_string, '%C')
khayyam.JalaliDatetime(1394, 4, 31, 17, 45, 40, 0, Chaharshanbeh)

You may use %f and or %z formatting directives to represent microseconds and timezone info in your formatting or parsing pattern.

So, to reach accurate serialization, you could include those two directive alongside time and date directives in your pattern. for example:

>>> from datetime import timedelta
>>> from khayyam import Timezone
>>> tz = Timezone(timedelta(seconds=60*210)) # +3:30 Tehran
>>> now_string = JalaliDatetime(1394, 4, 31, 14, 10, 21, 452958, tz).strftime('%Y-%m-%d %H:%M:%S.%f %z')
>>> print(now_string)
1394-04-31 14:10:21.452958 +03:30

Parse it back to the khayyam.JalaliDatetime instance:

>>> now = JalaliDatetime.strptime(now_string, '%Y-%m-%d %H:%M:%S.%f %z')
>>> now
khayyam.JalaliDatetime(1394, 4, 31, 14, 10, 21, 452958, tzinfo=+03:30, Chaharshanbeh)

Try some formatting and parsing directives:

>>> now = JalaliDatetime(1394, 4, 31)
>>> print(now.strftime('%a %d %B %y'))
چ 31 تیر 94

>>> print(now.strftime('%A %d %b %Y'))
چهارشنبه 31 تی 1394

>>> from khayyam import TehranTimezone
>>> print(now.astimezone(TehranTimezone()).strftime('%A %d %B %Y %Z'))
چهارشنبه 31 تیر 1394 Iran/Tehran

Converting¶

Converting to gregorian calendar, python’s native datetime.date and datetime.datetime:

>>> from datetime import date, datetime
>>> from khayyam import JalaliDate, JalaliDatetime, TehranTimezone

>>> JalaliDate(1394, 4, 31).todate()
datetime.date(2015, 7, 22)

>>> now = JalaliDatetime(1394, 4, 31, 15, 38, 6, 37269)
>>> now.todate()
datetime.date(2015, 7, 22)

>>> now.todatetime()
datetime.datetime(2015, 7, 22, 15, 38, 6, 37269)

And vise-versa:

>>> JalaliDatetime(datetime(2015, 7, 22, 14, 47, 9, 821830))
khayyam.JalaliDatetime(1394, 4, 31, 14, 47, 9, 821830, Chaharshanbeh)

>>> JalaliDatetime(datetime(2015, 7, 22, 14, 47, 9, 821830, TehranTimezone()))
khayyam.JalaliDatetime(1394, 4, 31, 14, 47, 9, 821830, tzinfo=+03:30 dst:60, Chaharshanbeh)

>>> JalaliDate(date(2015, 7, 22))
khayyam.JalaliDate(1394, 4, 31, Chaharshanbeh)

Arithmetics & Operators¶

Addition and subtraction:

>>> from datetime import timedelta
>>> from khayyam import JalaliDate, JalaliDatetime
>>> now = JalaliDatetime(1394, 4, 31, 16, 17, 31, 374398)
>>> now
khayyam.JalaliDatetime(1394, 4, 31, 16, 17, 31, 374398, Chaharshanbeh)

>>> now + timedelta(days=1)
khayyam.JalaliDatetime(1394, 5, 1, 16, 17, 31, 374398, Panjshanbeh)

>>> now + timedelta(seconds=3600)
khayyam.JalaliDatetime(1394, 4, 31, 17, 17, 31, 374398, Chaharshanbeh)

>>> now - timedelta(seconds=3600)
khayyam.JalaliDatetime(1394, 4, 31, 15, 17, 31, 374398, Chaharshanbeh)

>>> yesterday = now - timedelta(1)
>>> yesterday
khayyam.JalaliDatetime(1394, 4, 30, 16, 17, 31, 374398, Seshanbeh)

>>> now - yesterday
datetime.timedelta(1)

>>> JalaliDatetime.now() - now 
datetime.timedelta(0, 478, 328833) # 478 seconds taken to writing this section

Supported operators:

khayyam.JalaliDate.__add__()
khayyam.JalaliDate.__sub__()

Comparison¶

Just like the datetime, all comparison operators are overridden:

khayyam.JalaliDate.__lt__()
khayyam.JalaliDate.__le__()
khayyam.JalaliDate.__hash__()
khayyam.JalaliDate.__eq__()
khayyam.JalaliDate.__ne__()
khayyam.JalaliDate.__gt__()
khayyam.JalaliDate.__ge__()

So:

>>> now > yesterday
True

>>> now != yesterday
True

>>> now.todate() == yesterday.todate()
False