Usage

Because of the nature of the Badí’ Calendar things will work a little differently when compared to the standard Python datetime package. The standard datetime package only needs to know the IANA timezone information, actually it just needs the offset in seconds from UTC and if the local time is in DST (Daylight Savings Time) the determination of local time.

The badidatetime package, on the other hand, also needs the latitude and longitude information. Most computers know the UTC offset and DST which is used to determine the locales timezone, but do not know or need to know the latitude and longitude of your location. However, the badidatetime package does need this additional information to get the correct sunset for any locale.

Initialize

To start off you must decide if you will have internet access while using the API. If not then the latitude and longitude should be provided or the locale. See below. If the default is accepted then your locale becomes Tehran Iran. This means the functionality in fromtimestamp, atimezone, and LOCAL will be the default coordinents in the date and datetime classes.

The default setting will not do a network request for the latitude and longitude. Follow the processed outlined below.

Warning

Be sure to always import the packages you want after running set_local_coordinates().

from badidatetime import set_local_coordinates

set_local_coordinates(<latitude>, <longitude>)
# OR
set_local_coordinates(locale=<locale>

from badidatetime import date, time, datetime, ...

The set_local_coordinates() function takes one or two arguments which can be either the locale or latitude and longitude. If the latitude and longitude are supplied the network will not be used. However, if the locale is supplied then there will be a network call. The locale can be a street address, city, state, county or even a zip code. If you are writing code that uses this API your users will need to enter either their locale or latitude and longitude which you would redirect to this function.

datetime module

Provides Classes

timedelta
date
tzinfo
time
datetime
timezone

This module has most of the features that is in the standard datetime module that comes with Python. There are exceptions in two categories.

  1. The badidatetime module conforms to the Badí’ Calendar not the Gregorian Calendar. Where a Gregorian date is always represented as yy-mm-dd (ISO notation), the Badí’ Calendar has two formats which are called long and short form dates.

    1. Short form dates are represented the same as the Gregorian as yy-mm-dd and the ISO standard would work the same also.

    2. Long form dates are the Kull-i-Shay’, Váḥid, Year, Month, and Day. I have extended the ISO notation as kk-vv-yy-mm-dd. Remember that the year in this form is not the same as the year in the short form. The formula for converting to the short form is year = (kk-1) * 361 + (vv-1) * 19 + yy, the month and day are the same as the short form month and day.

  2. Other than the UTC timezone object the badidatetime module also provides a few other constants.

    1. The BADI timezone object.

    2. The LOCAL timezone object. The LOCAL object will be the same as the BADI object if the geocoder is left disabled, see above.

    3. The BADI_IANA which gives the IANA text value for Tehran, Iran.

    4. The BADI_COORD is a tuple containing the latitude, longitude, and offset from UTC.

    5. The GMT_COORD is a tuple containing the latitude, longitude, and offset from UTC which is always 0.0.

    6. The LOCAL_COORD is a tuple containing the latitude, longitude, and offset of the current locale or will be the same as BADI_COORD if the geocoder is left disabled, see above.

The timedelta and tzinfo classes are direct references to the Python standard datetime package. All other classes have been rewritten.

badi_calendar module

Provides Class

BahaiCalendar

This module provides the functionality needed for finding the Julian Period day and the long or short form Badí’ dates along with conversion methods between Badí’ and Gregorian dates. There is also a conversion method to convert a POSIX timestamp to a Badí’ date. The BahaiCalendar class supers the BaseCalendar and Coefficients classes. Internally fractions of days are a fraction on the day. These fractions can be converted to hours, minutes, seconds, and microseconds.

gregorian_calendar module

Provides Class

GregorianCalendar

This module provides the functionality needed for finding the Julian Period day and the Gregorian dates. The GregorianCalendar class supers the BaseCalendar class. Internally fractions of days are a fraction on the day. These fractions can be converted to hours, minutes, seconds, and microseconds.

base_clanedar module

Provides Class

BaseCalendar

This module provides all the heavy lifting for the astronomical calculations. All the methods are protected. The methods that would generally be used for a project using this API can be found in the last third of the BaseCalendar class. The BaseCalendar class supers the AstronomicalTerms and JulianPeriod classes.

julian_period module

Provides Class

JulianPeriod

This module provides functionality to convert a Julian Period day to a century and millennia. All the methods are protected, so unless you are fixing a bug in this API you will never need to use any methods in the JulianCalendar class.