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 the 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__(key)

Returns the City instance specified by key.

citydb
Return type:The database of cities.
dawn_utc(date, latitude, longitude)

Calculate dawn time in the UTC timezone.

Parameters:
  • date (datetime.date) – Date to calculate for.
  • latitude (float) – Latitude - Northern latitudes should be positive
  • longitude (float) – Longitude - Eastern longitudes should be positive
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 - Northern latitudes should be positive
  • longitude (float) – Longitude - Eastern longitudes should be positive
Return type:

date/time in UTC timezone

moon_phase(date, tz)

Calculates the phase of the moon on the specified date.

Parameters:
  • date (datetime.date) – The date to calculate the phase for.
  • tz (pytz.tz) – The timezone 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 - Northern latitudes should be positive
  • longitude (float) – Longitude - Eastern longitudes should be positive
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 - Northern latitudes should be positive
  • longitude (float) – Longitude - Eastern longitudes should be positive
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 - Northern latitudes should be positive
  • longitude (float) – Longitude - Eastern longitudes should be positive
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 - Northern latitudes should be positive
  • longitude (float) – Longitude - Eastern longitudes should be positive
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 - Northern latitudes should be positive
  • longitude (float) – Longitude - Eastern longitudes should be positive
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 - Northern latitudes should be positive
  • longitude (float) – Longitude - Eastern longitudes should be positive
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 - Northern latitudes should be positive
  • longitude (float) – Longitude - Eastern longitudes should be positive
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

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 city’s 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 city’s 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, positive numbers signify latitudes to the North.

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, positive numbers signify longitudes to the West.

moon_phase(date=None)

Calculates the moon phase for a specific date.

Parameters:date (datetime.date) – The date to calculate the phase for. If ommitted the current date is used.
Return type:Integer designating phase
0 = New moon
7 = First quarter
14 = Full moon
21 = Last quarter
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 city’s 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_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=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 city’s 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 city’s 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 city’s 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 city’s time zone (Default); False = Time to be returned in UTC.
Return type:

datetime.datetime of sunset

timezone

The name of the time zone 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.6.1

This Page