Introduction

This page introduce pyjalali to you. If you want rather head into class and methods’ documentation see Module Index.

Install

In jcal source directory navigate to subdirectory sources and run python setup.py install. You must have libjalali installed before.

Usage

You can use most functionalities of standard datetime module by pyjalali.datetime:

>>> from pyjalali.datetime import datetime
>>> datetime.now()
... pyjalali.datetime.datetime(1392, 12, 1, 23, 40, 18, 772116)
>>> datetime.today() - datetime(1367, 11 1)
... datetime.timedelta(30, 85313, 805141)

There is also pyjalali.datetime.date:

>>> from pyjalali.datetime import date
>>> date.today().isoformat()
... '1392-12-01'

You can make timezone aware datetimes:

>>> from pytz import timezone
>>> now_in_teh = datetime.now(timezone('Asia/Tehran'))
>>> # see current time in another area
>>> in_amsterdam = now_in_teh.astimezone(timezone('Europe/Amsterdam'))
>>> print now_in_teh.time(), in_amsterdam.time()
... 10:42:03.233978 08:12:03.233978
>>> in_amsterdam == now_in_teh
... True

To convert between Hijri Shamsi and Gregorian calendars, you can use functions jalali_from_gregorian() and gregorian_from_jalali() (or respectively g2j() and j2g() for short). Also you can use datetime.datetime.gregorian to get equal datetime in Gregorian calendar. This will be cached for future uses:

>>> from datetime import datetime as _std_datetime, date as _std_date
>>> from pyjalali.datetime import jalali_from_gregorian, gregorian_from_jalali, datetime, date
>>> jd = datetime(1389, 21, 11, 12, 23, 10)
>>> gd = jd.gregorian
>>> print gd, jd
... 2011-01-30 18:23:10  1389-11-10 18:23:10
>>> gregorian_from_jalali(jd) == gd
... True
>>> jalali_from_gregorian(_std_date.today())
... pyjalali.datetime.date(1392, 12, 2)

Note unlike many Hijri Shamsi implementations, libjalali doesn’t work by converting dates to Gregorian and forwarding operations to Gregorian date. It’s a Hijri Shamsi calendar implementation from base. The only place pyjalali converts Hijri Shamsi date to Gregorian internally, is to work with pytz package in timezone aware datetimes. So keep in mind libjalali doesn’t offer a general converter for dates before UNIX Epoch and pyjalali converters will fail for them.

If you need to invoke libjalali library functions directly, you can use wrapper functions. jtime contains libjalali time functions. Functions used internally by libjalali resides in jalali. jstr contains functions for converting between dates and string representation. Core libjalali data structures are simulated in types.

>>> from pyjalali.jtime import jlocaltime
>>> print jlocaltime(int(time()))
... 1392/11/2 11-29-11 +12600 (IRST)

Note

You can use functions datetime.now() and datetime.utcnow() in module level:

>>> from pyjalali.datetime import utcnow
>>> utcnow()
... pyjalali.datetime.datetime(1392, 12, 1, 20, 18, 27, 651499)

Version

pyjalali is a very thin wrapper around libjalali. Package’s version you see in pyjalali.__init__.__version__ cosists of 3 numbers describing version of libjalali which pyjalali supposed to work with it and another number that is revision of pyjalali itself. So 0.6.11.92 would expected to work with libjalali version 0.6.11.