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 provides 2 main classes Astral and City.

Astral

Has 2 main capabilities

  • Calculates the events in the UTC timezone.
  • Holds a dictionary of City classes to provide information and calculations for a specific city.
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.08
>>> 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.

Handles city names with spaces and mixed case.

cities
Returns a dictionary of cities indexed by city name.
dawn_utc(date, latitude, longitude)

Calculate dawn time for a specific date at a particular position.

Returns date/time in UTC

dusk_utc(date, latitude, longitude)

Calculate dusk time for a specific date at a particular position.

Returns date/time in UTC

rahukaalam_utc(date, latitude, longitude)
Calculate ruhakaalam times at a particular location.
solar_azimuth(dateandtime, latitude, longitude)
Calculate the azimuth of the sun as a specific date/time and location.
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 as a specific date/time and location.
solar_noon_utc(date, longitude)

Calculate solar noon time for a specific date at a particular position.

Returns date/time in UTC

sun_utc(date, latitude, longitude)
Returns dawn, sunrise, noon, sunset and dusk times as a dictionary.
sunrise_utc(date, latitude, longitude)

Calculate sunrise time for a specific date at a particular position.

Returns date/time in UTC

sunset_utc(date, latitude, longitude)

Calculate sunset time for a specific date at a particular position.

Returns date/time in UTC

class astral.City(info=None)

Provides access to information for single city.

__init__(info=None)

Initializes the object with a tuple of information.

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)

Return dawn time.

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 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.
dusk(date=None, local=True)

Return dusk time.

Calculates 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.
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 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.
solar_azimuth(dateandtime=None)

Calculates the solar azimuth angle for a specific time.

The angle returned is in degrees clockwise from North.

Parameters:

dateandtime - The date and time for which to calculate the angle.
solar_elevation(dateandtime=None)

Calculates the solar elevation angle for a specific time.

The angle returned is in degrees from the horizon

Parameters:

dateandtime - The date and time for which to calculate the angle.
solar_noon(date=None, local=True)

Return the solar noon time.

Calculates 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.
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.
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.
sunset(date=None, local=True)

Return sunset time.

Calculates 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.
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.3

This Page