The astral Module

The astral module provides the means to calculate dawn, sunrise, solar noon, sunset, dusk and rahukaalam times, plus solar azimuth and elevation, for specific cities or at a specific latitude/longitude. It can also calculate moon phase for a specific date.

The module provides 2 main classes Astral and City.

Astral

Has 2 main responsibilities

  • Calculates the events in the UTC timezone.
  • Holds a dictionary of City classes
City
Holds information about a city and provides functions to calculate the event times for the city in the correct time zone.

For example

>>> from astral import *
>>> a = Astral()
>>> city = a['London']
>>> print('Information for %s' % city.name)
Information for London
>>> timezone = city.timezone
>>> print('Timezone: %s' % timezone)
Timezone: Europe/London
>>> print('Latitude: %.02f; Longitude: %.02f' % (city.latitude, city.longitude))
Latitude: 51.60; Longitude: 0.05
>>> sun = city.sun(local=True)
>>> print('Dawn:    %s' % str(sun['dawn']))
Dawn:    2009-04-22 05:12:56+01:00
class astral.Astral
__getitem__(value)

Returns a City object for the specified city.

city = astral['London']

You can supply an optional country name by adding a comma followed by the country name. Where multiple cities have the same name you may need to supply the country name otherwise the first result will be returned which may not be the one you’re looking for.

city = astral['Abu Dhabi,United Arab Emirates']

Handles city names with spaces and mixed case.

cities
Return type:Dictionary of cities indexed by city name.
dawn_utc(date, latitude, longitude)

Calculate dawn time in the UTC timezone.

Parameters:
  • date (datetime.date) – Date to calculate for.
  • latitude (float) – Latitude - Southern latitudes should be negative
  • longitude (float) – Longitude as a floating point number. Eastern latitudes should be negative
Return type:

date/time in UTC timezone

dusk_utc(date, latitude, longitude)

Calculate dusk time in the UTC timezone.

Parameters:
  • date (datetime.date) – Date to calculate for.
  • latitude (float) – Latitude - Southern latitudes should be negative
  • longitude (float) – Longitude as a floating point number. Eastern latitudes should be negative
Return type:

date/time in UTC timezone

moon(date)

Calculates the phase of the moon on the specified date.

Parameters:date (datetime.date) – The date to calculate the phase for.
Return type:Integer designating phase
0 = New moon
7 = First quarter
14 = Full moon
21 = Last quarter
rahukaalam_utc(date, latitude, longitude)

Calculate ruhakaalam times in the UTC timezone.

Parameters:
  • date (datetime.date) – Date to calculate for.
  • latitude (float) – Latitude - Southern latitudes should be negative
  • longitude (float) – Longitude as a floating point number. Eastern latitudes should be negative
Return type:

Dictionary with keys start and end

solar_azimuth(dateandtime, latitude, longitude)

Calculate the azimuth of the sun in the UTC timezone.

Parameters:
  • dateandtime (datetime.datetime) – Date/time to calculate for.
  • latitude (float) – Latitude - Southern latitudes should be negative
  • longitude (float) – Longitude as a floating point number. Eastern latitudes should be negative
Return type:

Azimuth in degrees

solar_depression

The number of degrees the sun must be below the horizon for the dawn/dusk calc.

Can either be set as a number of degrees below the horizon or as one of the following strings

String Degrees
civil 6.0
nautical 12.0
astronomical 18.0
solar_elevation(dateandtime, latitude, longitude)

Calculate the elevation of the sun.

Parameters:
  • dateandtime (datetime.datetime) – Date/time to calculate for.
  • latitude (float) – Latitude - Southern latitudes should be negative
  • longitude (float) – Longitude as a floating point number. Eastern latitudes should be negative
Return type:

Elevation in degrees

solar_noon_utc(date, longitude)

Calculate solar noon time in the UTC timezone.

Parameters:
  • date (datetime.date) – Date to calculate for.
  • latitude (float) – Latitude - Southern latitudes should be negative
  • longitude (float) – Longitude as a floating point number. Eastern latitudes should be negative
Return type:

date/time in UTC timezone

sun_utc(date, latitude, longitude)

Calculate all the info for the sun at once.

Parameters:
  • date (datetime.date) – Date to calculate for.
  • latitude (float) – Latitude - Southern latitudes should be negative
  • longitude (float) – Longitude as a floating point number. Eastern latitudes should be negative
Return type:

Dictionary with keys dawn, sunrise, noon, sunset and dusk

sunrise_utc(date, latitude, longitude)

Calculate sunrise time in the UTC timezone.

Parameters:
  • date (datetime.date) – Date to calculate for.
  • latitude (float) – Latitude - Southern latitudes should be negative
  • longitude (float) – Longitude as a floating point number. Eastern latitudes should be negative
Return type:

date/time in UTC timezone

sunset_utc(date, latitude, longitude)

Calculate sunset time in the UTC timezone.

Parameters:
  • date (datetime.date) – Date to calculate for.
  • latitude (float) – Latitude - Southern latitudes should be negative
  • longitude (float) – Longitude as a floating point number. Eastern latitudes should be negative
Return type:

date/time in UTC timezone

class astral.City(info=None)

Provides access to information for single city.

__init__(info=None)

Initializes the object with a tuple of information.

Parameters:info

A tuple of information to fill in the city info.

The tuple should contain items in the following order

Field Default
name Greenwich
country England
latitude 51.168
longitude 0
time zone name Europe/London

See timezone property for a method of obtaining time zone names

country

The country in which the city is located.

dawn(date=None, local=True)

Calculates the time in the morning when the sun is a certain number of degrees below the horizon. By default this is 6 degrees but can be changed by setting the Astral.solar_depression property.

Parameters:
  • date – The date for which to calculate the dawn time. A value of None uses the current date.
  • local – True = Time to be returned in cities time zone (Default); False = Time to be returned in UTC.
Return type:

datetime.datetime of dawn

dusk(date=None, local=True)

Calculates the dusk time (the time in the evening when the sun is a certain number of degrees below the horizon. By default this is 6 degrees but can be changed by setting the Astral.solar_depression property.)

Parameters:
  • date – The date for which to calculate the dusk time. A value of None uses the current date.
  • local – True = Time to be returned in cities time zone (Default); False = Time to be returned in UTC.
Return type:

datetime.datetime of dusk

latitude

The city’s latitude

latitude can be set either as a string or as a number

For strings they must be of the form:

degrees°minutes'[N|S] e.g. 51°31'N

For numbers, negative numbers signify latitudes to the South.

longitude

The city’s longitude.

longitude can be set either as a string or as a number

For strings they must be of the form:

degrees°minutes'[E|W] e.g. 51°31'W

For numbers, negative numbers signify longitudes to the East. This is opposite to the normal convention of +ve being to the West but is required for the calculations.

name

The city name.

rahukaalam(date=None, local=True)

Calculates the period of rahukaalam.

Parameters:
  • date – The date for which to calculate the rahukaalam period. A value of None uses the current date.
  • local – True = Time to be returned in cities time zone (Default); False = Time to be returned in UTC.
Return type:

datetime.datetime of dusk

solar_azimuth(dateandtime=None)

Calculates the solar azimuth angle for a specific date/time.

Parameters:dateandtime (datetime.datetime) – The date and time for which to calculate the angle.
Return type:The angle in degrees clockwise from North as a float.
solar_elevation(dateandtime=None)

Calculates the solar elevation angle for a specific time.

Parameters:dateandtime (datetime.datetime) – The date and time for which to calculate the angle.
Return type:The angle in degrees from the horizon as a float.
solar_noon(date=None, local=True)

Calculates the solar noon (the time when the sun is at its highest point.)

Parameters:
  • date – The date for which to calculate the noon time. A value of None uses the current date.
  • local – True = Time to be returned in cities time zone (Default); False = Time to be returned in UTC.
Return type:

datetime.datetime of noon

sun(date=None, local=True)

Returns dawn, sunrise, noon, sunset and dusk as a dictionary.

Parameters:
  • date – The date for which to calculate the times. A value of None uses the current date.
  • local – True = Time to be returned in cities time zone (Default); False = Time to be returned in UTC.
Return type:

datetime.datetime of dusk

sunrise(date=None, local=True)

Return sunrise time.

Calculates the time in the morning when the sun is a 0.833 degrees below the horizon. This is to account for refraction.

Parameters:
  • date – The date for which to calculate the sunrise time. A value of None uses the current date.
  • local – True = Time to be returned in cities time zone (Default); False = Time to be returned in UTC.
Return type:

datetime.datetime of sunrise

sunset(date=None, local=True)

Calculates sunset time (the time in the evening when the sun is a 0.833 degrees below the horizon. This is to account for refraction.)

Parameters:
  • date – The date for which to calculate the sunset time. A value of None uses the current date.
  • local – True = Time to be returned in cities time zone (Default); False = Time to be returned in UTC.
Return type:

datetime.datetime of sunset

timezone

The time zone name in which the city is located.

A list of time zone names can be obtained from pytz. For example.

>>> from pytz import all_timezones
>>> for tz in all_timezones:
...     print tz
tz

The timezone.

Previous topic

Welcome to Astral V0.4

This Page