Native hijri calendar support

[cbd59159-0a09-4f28-8e2c-38a19b76b099]

BPO	31895
Nosy	@malemburg, @terryjreedy, @stevendaprano, @gareth-rees, @Haneef95, @sanjeev singh

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields: ```python assignee = None closed_at = created_at = labels = ['type-feature', '3.8'] title = 'Native hijri calendar support' updated_at = user = 'https://github.com/Haneef95' ``` bugs.python.org fields: ```python activity = actor = 'terry.reedy' assignee = 'none' closed = True closed_date = closer = 'terry.reedy' components = [] creation = creator = 'haneef95' dependencies = [] files = [] hgrepos = [] issue_num = 31895 keywords = [] message_count = 9.0 messages = ['305199', '305200', '305202', '305214', '305219', '305222', '305225', '305226', '305507'] nosy_count = 6.0 nosy_names = ['lemburg', 'terry.reedy', 'steven.daprano', 'gdr@garethrees.org', 'haneef95', 'sanjeev091'] pr_nums = [] priority = 'normal' resolution = 'rejected' stage = 'resolved' status = 'closed' superseder = None type = 'enhancement' url = 'https://bugs.python.org/issue31895' versions = ['Python 3.8'] ```

[cbd59159-0a09-4f28-8e2c-38a19b76b099]

There should be native support for converting between Hijri (Umm al-Qura), Gregorian, Julian and UnixTime calendars.

Many big players have included native support for Hijri calendar in their SDKs and software. Below are some:

(Java Hijri calendar support)[https://docs.oracle.com/javase/8/docs/api/java/time/chrono/HijrahChronology.html] (Apple supports the Hijri calendar in 5 of their SDKs (Software Development Kits))[https://developer.apple.com/documentation/foundation/calendar.identifier] (Microsoft Windows supports Hijri calendar naively)[https://www.microsoft.com/middleeast/msdn/ArabicCalendar.aspx] (Microsoft Office has native support)[https://blogs.technet.microsoft.com/office_global_experience/2010/01/13/um-al-qura-calendar-support-in-office-2010/] (Android Hijri calendar support)[https://developer.android.com/reference/android/icu/util/IslamicCalendar.html] (Google Calendar allows Hijri calendar as an alternate calendar)[https://www.maketecheasier.com/display-alternate-calendar-google-calendar/]

[cbd59159-0a09-4f28-8e2c-38a19b76b099]

This feature can be added to the (datetime.py)[https://docs.python.org/3/library/datetime.html], Java has done a similar move and it makes the whole process a lot easier.

The Hijri calendar is used across the globe by various websites and developers, some have even made libraries.

[stevendaprano]

Python 2.7 is in feature freeze, so 3.7 is the absolute earliest this could be introduced. Given how close we are to 3.7 feature freeze, 3.8 is more likely.

I don't think we would have any objections to supporting hijri calendar, in principle, but as a practical matter I expect that none of the core developers are probably qualified to write, review, support and maintain it. (I could be wrong, of course.) And what interface is required?

I'm not convinced that the datetime module is the right place for this. In the long run, we should expect that Python may support multiple calendars: Western, Arabic, Jewish, Asian calendars, and more. I think that would make datetime too big and clunky.

I think the best approach would be to provide a third-party package on PyPI, and once it has proven itself, it could be proposed for the standard library.

[faa20c90-fcf0-43f4-810b-00286077d549]

It is a substantial undertaking, requiring a great deal of expertise, to implement the Islamic calendar. The difficulty is that there are multiple versions of the calendar. In some places the calendar is based on human observation of the new moon, and so a database of past observations is needed (and future dates can't be represented). In other places the time of observability of the new moon is calculated according to an astronomical ephemeris (and different ephemerides are used in different places and at different times).

[malemburg]

I agree with Steven: It's best to use a PyPI package for calendar support such as https://pypi.python.org/pypi/convertdate/.

We only have the standard Gregorian calendar support in datetime and calendar modules.

[faa20c90-fcf0-43f4-810b-00286077d549]

convertdate does not document which version of the Islamic calendar it uses, but looking at the source code, it seems that it uses a rule-based calendar which has a 30-year cycle with 11 leap years. This won't help Haneef, who wants the Umm al-Qura calendar.

[cbd59159-0a09-4f28-8e2c-38a19b76b099]

Thanks @steven.daprano, yeah, it would be good to have support for other calendars as well.

In my case, I use the Hijri Umm al-Qura, Gregorian and obviously UnixTime calendars.

You're right, maybe it would be wiser to implement it in the PyPi first and then move it to a standard Python library.

@Lemburg, I checked out the PyPi convertdate library, as Gareth mentioned, it doesn't specify which Islamic calendar it is implementing and had a look at the code, it doesn't look like Umm al-Qura. It seems to be a very roughly calculated Tabular Lunar Calendar (with Hijrah as the reference point), no where near accurate to the actual lunar cycles.

@Gareth To explain Islamic Hijri Calendar in short, it is basically a sighted Lunar calendar, which has to be sighted at the end of every month to determine the beginning of the next month. Therefore, it is not possible to determine the dates in future (beyond 29th of the month). Every month could be 29 or 30 days. There are 12 months and 354 days in a year. However, to solve this issue, Muslim astronomers and Scholars over the course of History (1400years) have used two different types of Hijri calendars; one sighted and another calculated. The sighted version of the calendar is accurate but cannot go beyond 29th of the current month. The astronomically calculated version could go up-to a fixed period which the astronomers have calculated. The calculated/civil calendar is used for Visas, deeds, bank statements, appointments and other civil matters in their respective countries.

One of the predominantly used and astronomically calculated Hijri calendars is the Umm al-Qura Hijri calendar. It was calculated by scholars & astronomers at the Umm al-Qura (Makkah) University.

Sorry about the long post, hope this helps.

[malemburg]

There are other PyPI packages available for this specific calendar as well, e.g. https://pypi.python.org/pypi/umalqurra/

Perhaps you could send Neil a PR to make the calculation more accurate ?!

In any case, the stdlib is not meant to cover everything, only a basic subset of functionality, so adding support for more than just one calendar is out of scope.

[terryjreedy]

Haneef, thank you for the explanation. Any such addition would need a PEP. But I agree with Marc-Andre that supporting the multitude of calendars is out of scope for the stdlib. So I suspect such a PEP would be rejected, with the suggestion already given here, that this belongs on PyPI. An existing example is the time module of the astropy module, http://docs.astropy.org/en/stable/time/index.html .

I could be wrong, but I have a vague impression that expanding calendar support has been requested and rejected before. We have enough to do properly supporting the existing time, datetime, and calendar modules.