API Reference¶
The following section documents every class and function in the aladhan.py module.
Client¶
-
class
aladhan.
Client
[source]¶ Al-adhan API client.
Set to synchronous usage by default, set is_async to True if asynchronous usage wanted.
Auto handles rate limits by default, set auto_manage_rate to False if otherwise is wanted. New in v1.2.0
Example
import aladhan client = aladhan.Client() times = client.get_timings_by_address("New York") print(times)
import aladhan, asyncio async def main(): # --- manual closing session client = aladhan.Client(is_async=True) times = await client.get_timings_by_address("New York") print(times) await client.close() # --- using context async with aladhan.Client(is_async=True) as client: times = await client.get_timings_by_address("New York") print(times) loop = asyncio.get_event_loop() loop.run_until_complete(main())
Note
For Asynchronous usage you need to initialize this class in a coroutine.
- Parameters
-
get_next_prayer_by_address
(address, date=None, params=None)[source]¶ Get next upcoming prayer from address.
- Parameters
address (
str
) – An address string. Example: “London, United Kingdom”date (Optional[
TimingsDateArg
]) – Date for the prayer times. Default: Current date.params (Optional[
Parameters
]) – Default:Parameters()
- Returns
Prayer obj from the API response.
- Return type
- Raises
BadRequest – Invalid parameter was passed.
New in v1.2.0
-
get_timings
(longitude, latitude, date=None, params=None)[source]¶ Get prayer times from coordinates (longitude, latitude).
- Parameters
longitude (
int
orfloat
) – Longitude coordinate of the location.latitude (
int
orfloat
) – Latitude coordinate of the location.date (Optional[
TimingsDateArg
]) – Date for the prayer times. Default: Current date.params (Optional[
Parameters
]) – Default:Parameters()
- Returns
Timings obj from the API response.
- Return type
- Raises
BadRequest – Invalid parameter was passed.
-
get_timings_by_address
(address, date=None, params=None)[source]¶ Get prayer times from address.
- Parameters
address (
str
) – An address string. Example: “London, United Kingdom”date (Optional[
TimingsDateArg
]) – Date for the prayer times. Default: Current date.params (Optional[
Parameters
]) – Default:Parameters()
- Returns
Timings obj from the API response.
- Return type
- Raises
BadRequest – Invalid parameter was passed.
-
get_timings_by_city
(city, country, state=None, date=None, params=None)[source]¶ Get prayer times from city, country and state.
- Parameters
city (
str
) – The city name. Example: “London”country (
str
) – The country name or 2 character alpha ISO 3166 code. Example: “GB” or “United Kingdom”state (Optional[
str
]) – State or province. The state name or abbreviation.. Example: “Bexley”date (Optional[
TimingsDateArg
]) – Date for the prayer times. Default: Current date.params (Optional[
Parameters
]) – Default:Parameters()
- Returns
Timings obj from the API response.
- Return type
- Raises
BadRequest – Invalid parameter was passed.
-
get_calendar
(longitude, latitude, date, params=None)[source]¶ Get all prayer times for a specific calendar month/year from coordinates (longitude, latitudes).
- Parameters
longitude (
int
orfloat
) – Longitude coordinate of the location.latitude (
int
orfloat
) – Latitude coordinate of the location.date (
CalendarDateArg
) – Date for the prayer times.params (Optional[
Parameters
]) – Default:Parameters()
- Returns
A month calendar if month parameter was given in date argument otherwise a year calendar.
- Return type
- Raises
BadRequest – Invalid parameter was passed.
-
get_calendar_by_address
(address, date, params=None)[source]¶ - Get all prayer times for a specific calendar month/year
from address.
- Parameters
address (
str
) – An address string. Example: “London, United Kingdom”date (
CalendarDateArg
) – Date for the prayer times.params (Optional[
Parameters
]) – Default:Parameters()
- Returns
A month calendar if month parameter was given in date argument otherwise a year calendar.
- Return type
- Raises
BadRequest – Invalid parameter was passed.
-
get_calendar_by_city
(city, country, date, state=None, params=None)[source]¶ - Get all prayer times for a specific calendar month/year
from address.
- Parameters
city (
str
) – The city name. Example: “London”country (
str
) – The country name or 2 character alpha ISO 3166 code. Example: “GB” or “United Kingdom”date (
CalendarDateArg
) – Date for the prayer times.state (Optional[
str
]) – State or province. The state name or abbreviation.. Example: “Bexley”params (Optional[
Parameters
]) – Default:Parameters()
- Returns
A month calendar if month parameter was given in date argument otherwise a year calendar.
- Return type
- Raises
BadRequest – Invalid parameter was passed.
-
get_qibla
(longitude, latitude)[source]¶ Get the Qibla direction from a pair of coordinates.
- Parameters
- Returns
The qibla.
- Return type
- Raises
BadRequest – Invalid parameter was passed.
New in v0.1.3
-
get_asma
(*n)[source]¶ Returns a list of asma from giving numbers.
- Parameters
n (
int
) – Numbers from range 1-99.- Returns
A list of asma.
- Return type
- Raises
BadRequest – Invalid parameter was passed.
New in v0.1.3
-
get_hijri_from_gregorian
(date=None, adjustment=0)[source]¶ Convert a gregorian date to a hijri date.
- Parameters
date (Optional[
TimingsDateArg
]) – Gregorian date. Default: Current dateadjustment (Optional[
int
]) – Number of days to adjust. Default: 0
- Returns
Date in hijri.
- Return type
- Raises
BadRequest – Invalid date or unable to convert it.
New in v1.1.0
-
get_gregorian_from_hijri
(date, adjustment=0)[source]¶ Convert a hijri date to a gregorian date.
- Parameters
date (Optional[
TimingsDateArg
]) – Gregorian date. Default: Current dateadjustment (Optional[
int
]) – Number of days to adjust. Default: 0
- Returns
Date in gregorian.
- Return type
- Raises
BadRequest – Invalid date or unable to convert it.
New in v1.1.0
-
get_hijri_calendar_from_gregorian
(month, year, adjustment=0)[source]¶ Get a hijri calendar for a gregorian month.
- Parameters
- Returns
Hijri Calendar.
- Return type
New in v1.1.0
-
get_gregorian_calendar_from_hijri
(month, year, adjustment=0)[source]¶ Get a gregorian calendar for a hijri month.
- Parameters
- Returns
Gregorian Calendar.
- Return type
New in v1.1.0
-
get_islamic_year_from_gregorian_for_ramadan
(year)[source]¶ Get which islamic year for ramadan from a gregorian year.
- Parameters
year (
int
) – Gregorian year.- Returns
Hijri year.
- Return type
- Raises
BadRequest – Unable to compute year.
-
get_current_time
(zone)[source]¶ - Parameters
zone (
str
) – Timezone string. ex: “Europe/London”- Returns
The current time for the specified time zone. ex: “13:56”
- Return type
- Raises
BadRequest – Invalid timezone.
-
get_current_date
(zone)[source]¶ - Parameters
zone (
str
) – Timezone string. ex: “Europe/London”- Returns
The current Date for the specified time zone in DD-MM-YYYY. ex: “23-02-2021”
- Return type
- Raises
BadRequest – Invalid timezone.
-
get_current_timestamp
(zone)[source]¶ - Parameters
zone (
str
) – Timezone string. ex: “Europe/London”- Returns
The current UNIX timestamp for the specified time zone. ex: 1503495668
- Return type
- Raises
BadRequest – Invalid timezone.
-
get_current_islamic_year
(adjustment=0)[source]¶ - Parameters
adjustment (
int
) – Number of days to adjust hijri date.- Returns
The current islamic year.
- Return type
- Raises
BadRequest – Unable to compute year.
-
get_current_islamic_month
(adjustment=0)[source]¶ - Parameters
adjustment (
int
) – Number of days to adjust hijri date.- Returns
The current islamic month.
- Return type
- Raises
BadRequest – Unable to compute month.
-
get_next_hijri_holiday
(adjustment=0)[source]¶ - Parameters
adjustment (
int
) – Number of days to adjust hijri date.- Returns
The Next upcoming hijri holiday.
- Return type
- Raises
BadRequest – Unable to compute next holiday.
-
get_hijri_holidays
(day, month)[source]¶ - Parameters
- Returns
All day’s holidays, can be empty list.
- Return type
- Raises
BadRequest – Invalid day or month.
-
get_islamic_holidays
(year, adjustment=0)[source]¶ - Parameters
- Returns
All year’s holidays, 19 in total.
- Return type
- Raises
BadRequest – Something went wrong.
-
get_status
()[source]¶ - Returns
Api’s status.
- Return type
- Raises
InternalServerError – Status Check Failed.
-
get_special_days
()[source]¶ Get all islamic special days (holidays).
- Returns
A list of all special days with
day,month,name
keys.- Return type
- Raises
BadRequest – Something went wrong.
Data Classes¶
Data¶
Meta¶
-
class
aladhan.
Meta
[source]¶ Represents the meta that is in returned
Data
Do not create this class yourself. Only get it through a getter.
-
data
¶ Original fetched Data.
- Type
-
timezone
¶ Used timezone to calculate.
- Type
pytz.UTC
-
property
parameters
¶ returns a Parameters obj
Warning
This will set method to ISNA if method was custom, and it will always set adjustment to 0.
- Type
-
Base Date¶
Date¶
-
class
aladhan.
Date
[source]¶ Represents the date that is in returned
Data
Do not create this class yourself. Only get it through a getter.
-
data
¶ Original fetched Data. None if it wasn’t from a timings getter.
Changed in v1.1.0: changed to Optional
- Type
Optional[
Data
]
-
readable
¶ Date in readable format. None if it wasn’t from a timings getter.
Changed in v1.1.0: changed to Optional
- Type
Optional[
str
]
-
DateType¶
-
class
aladhan.
DateType
[source]¶ A class for gregorian/hijri date.
Do not create this class yourself. Only get it through a getter.
-
weekday
¶ A dict with 2 keys, “en” and “ar” for hijri and only 1 key “en” for gregorian.
-
month
¶ A dict with 3 keys “number”, “en”, “ar” for hijri and 2 keys “number”, “en” for gregorian.
-
Ism¶
Enums¶
-
class
aladhan.enums.
MidnightModes
(value)[source]¶ Available midnight modes
-
STANDARD
= 0¶
-
JAFARI
= 1¶
-
Exceptions¶
The following exceptions are thrown by the library.
-
exception
aladhan.exceptions.
AladhanException
(message='')[source]¶ Base exception class for aladhan.py
- Ideally speaking, this could be caught to handle any exceptions
thrown from this library.
-
exception
aladhan.exceptions.
HTTPException
(response, message=None)[source]¶ Exception that’s thrown when an HTTP request operation fails.
-
exception
aladhan.exceptions.
BadRequest
(response, message=None)[source]¶ Exception that’s thrown for when status code 400 occurs.
-
exception
aladhan.exceptions.
TooManyRequests
(response, message=None)[source]¶ Exception that’s thrown for when status code 429 occurs.
Note
Current API’s rate limit is 14 requests/s.
New in v1.2.0
-
exception
aladhan.exceptions.
InternalServerError
(response, message=None)[source]¶ Exception that’s thrown for when status code 500 occurs.
-
exception
aladhan.exceptions.
InvalidArgument
(message='')[source]¶ Exception that’s thrown when an argument to a function is invalid some way (e.g. wrong value or wrong type).
-
exception
aladhan.exceptions.
InvalidMethod
(message='')[source]¶ Exception that’s thrown when method argument is invalid.
-
exception
aladhan.exceptions.
InvalidTune
(message='')[source]¶ Exception that’s thrown when tune argument is invalid.
-
exception
aladhan.exceptions.
InvalidSchool
(message='')[source]¶ Exception that’s thrown when school argument is invalid.
-
exception
aladhan.exceptions.
InvalidMidnightMode
(message='')[source]¶ Exception that’s thrown when midnight mode argument is invalid.
-
exception
aladhan.exceptions.
InvalidTimezone
(message='')[source]¶ Exception that’s thrown when timezone argument is invalid.
-
exception
aladhan.exceptions.
InvalidLatAdjMethod
(message='')[source]¶ Exception that’s thrown when latitude adjustment method argument is invalid.