astral v1 - read the docs · astral v1.7, release 1.7 astral is a python module for calculating the...

Astral v1.10Release 1.10

Simon Kennedy

Feb 04, 2019

Contents

1 Examples 31.1 Sun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Moon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3 Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.4 Geolocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 Effect of Elevation 7

3 Note on Localized Timezones 9

4 License 11

5 Dependencies 13

6 Installation 15

7 Cities 177.1 US Cities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

8 Thanks 19

9 Contact 21

10 Version History 2310.1 The astral Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Python Module Index 41

i

Astral v1.10, Release 1.10

Astral is a python module for calculating the times of various aspects of the sun and moon.

It calculates the following

Dawn The time in the morning when the sun is a specific number of degrees below the horizon.

Sunrise The time in the morning when the top of the sun breaks the horizon (asuming a location with no obscuringfeatures.)

Solar Noon The time when the sun is at its highest point.

Solar Midnight The time when the sun is at its lowest point.

Sunset The time in the evening when the sun is about to disappear below the horizon (asuming a location with noobscuring features.)

Dusk The time in the evening when the sun is a specific number of degrees below the horizon.

Daylight The time when the sun is up i.e. between sunrise and sunset

Night The time between astronomical dusk of one day and astronomical dawn of the next

Twilight The time between dawn and sunrise or between sunset and dusk

The Golden Hour The time when the sun is between 4 degrees below the horizon and 6 degrees above.

The Blue Hour The time when the sun is between 6 and 4 degrees below the horizon.

Time At Elevation the time when the sun is at a specific elevation for either a rising or a setting sun.

Solar Azimuth The number of degrees clockwise from North at which the sun can be seen

Solar Elevation The number of degrees up from the horizon at which the sun can be seen

Rahukaalam “Rahukaalam or the period of Rahu is a certain amount of time every day that is considered inauspiciousfor any new venture according to Indian Vedic astrology”.

Moon Phase Calculates the phase of the moon for a specified date.

Contents 1

https://travis-ci.org/sffjunkie/astral

https://pypi.org/project/astral/

http://en.wikipedia.org/wiki/Rahukaalam


2 Contents

CHAPTER 1

Examples

The following examples demonstrate the functionality available in the module

1.1 Sun

>>> import datetime>>> from astral import Astral

>>> city_name = 'London'

>>> a = Astral()>>> a.solar_depression = 'civil'

>>> city = a[city_name]

>>> print('Information for %s/%s\n' % (city_name, city.region))Information for London/England

>>> timezone = city.timezone>>> print('Timezone: %s' % timezone)Timezone: Europe/London

>>> print('Latitude: %.02f; Longitude: %.02f\n' % \>>> (city.latitude, city.longitude))Latitude: 51.60; Longitude: 0.08

>>> sun = city.sun(date=datetime.date(2009, 4, 22), local=True)>>> print('Dawn: %s' % str(sun['dawn']))>>> print('Sunrise: %s' % str(sun['sunrise']))>>> print('Noon: %s' % str(sun['noon']))>>> print('Sunset: %s' % str(sun['sunset']))>>> print('Dusk: %s' % str(sun['dusk']))Dawn: 2009-04-22 05:12:56+01:00

(continues on next page)

3


(continued from previous page)

Sunrise: 2009-04-22 05:49:36+01:00Noon: 2009-04-22 12:58:48+01:00Sunset: 2009-04-22 20:09:07+01:00Dusk: 2009-04-22 20:45:52+01:00

1.2 Moon

>>> import datetime>>> from astral import Astral>>> a = Astral()>>> moon_phase = a.moon_phase(date=datetime.date(2018, 1, 1))>>> print(moon_phase)13

The moon phase method returns an number describing the phase, where the value is between 0 and 27 (27.99 if youpass float as the return type). The following lists the mapping of various vales to the description of the phase of themoon.

0 = New Moon7 = First Quarter14 = Full Moon21 = Last Quarter

If for example the number returned was 27(.99) then the moon would be almost at the New Moon phase, and if it was24 it would be half way between the Last Quarter and a New Moon.

The return value can be cast to either an int (the default) or a float by passing the type required as the rtype parameterto moon_phase()

Note: The moon phase does not depend on your location. However what the moon actually looks like to you doesdepend on your location. If you’re in the southern hemisphere it looks different than if you were in the northernhemisphere.

See http://moongazer.x10.mx/website/astronomy/moon-phases/ for an example.

1.3 Locations

1.3.1 Additional Locations

If you are using AstralGeocoder you can add to the list of available locations using the add_locations()method and passing either a string with one line per location or by passing a list containing strings, lists or tuples (listsand tuples are passed directly to the Location constructor).

1.3.2 Custom Location

If the location you want is not in the Astral geocoder then you can construct a Location and fill in the values, eitherwith a tuple on initialization:

4 Chapter 1. Examples

http://moongazer.x10.mx/website/astronomy/moon-phases/


l = Location(('name', 'region',0.1, 1.2, 'timezone/name', 0))

l.sun()

or set the attributes after initialization:

l = Location()l.name = 'name'l.region = 'region'l.latitude = 0.1l.longitude = 1.2l.timezone = 'US/Central'l.elevation = 0l.sun()

Note: name and region can be anything you like.

1.4 Geolocation

1.4.1 Access to Geocoder Instance

Access to the current geocoder can be made through the Astral class:

>>> a = Astral()>>> geo = a.geocoder>>> london = geo['London']

1.4.2 Timezone Groups

Timezone groups such as Europe can be accessed via attributes on the AstralGeocoder:

>>> geo = AstralGeocoder()>>> europe = geo.europe.locations>>> europe.sort()>>> europe['Aberdeen', 'Amsterdam', 'Andorra la Vella', 'Ankara', 'Athens', ...]

1.4. Geolocation 5


6 Chapter 1. Examples

CHAPTER 2

Effect of Elevation

An attempt has been made to allow for the effect of elevation on the times for the sun. Higher elevations cause the sunto rise earlier and to set later for the observer.

This is performed by calculating the angle 𝛼 in the image below and adding this to the depression angle for the suncalculations.

Warning: This may not be the correct calculation for the angle. Please raise an issue if you know how it shouldbe calculated.

7

https://github.com/sffjunkie/astral/issues


8 Chapter 2. Effect of Elevation

CHAPTER 3

Note on Localized Timezones

When creating a datetime object in a specific timezone do not use the tzinfo parameter to the datetime constructor.Instead please use the localize() method on the correct pytz timezone:

dt = datetime.datetime(2015, 1, 1, 9, 0, 0)dt = pytz.timezone('Europe/London').localize(dt)

9


10 Chapter 3. Note on Localized Timezones

CHAPTER 4

License

This module is licensed under the terms of the Apache V2.0 license.

11

http://www.opensource.org/licenses/apache2.0.php


12 Chapter 4. License

CHAPTER 5

Dependencies

Astral has one external Python dependency on ‘pytz’.

13


14 Chapter 5. Dependencies

CHAPTER 6

Installation

To install Astral you should use the pip tool:

pip install astral

15


16 Chapter 6. Installation

CHAPTER 7

Cities

The module includes location and time zone data for the following cities. The list includes all capital cities plus somefrom the UK. The list also includes the US state capitals and some other US cities.

Aberdeen, Abu Dhabi, Abu Dhabi, Abuja, Accra, Addis Ababa, Adelaide, Al Jubail, Albany, Albuquerque, Al-giers, Amman, Amsterdam, Anchorage, Andorra la Vella, Ankara, Annapolis, Antananarivo, Apia, Ashgabat, As-mara, Astana, Asuncion, Athens, Atlanta, Augusta, Austin, Avarua, Baghdad, Baku, Baltimore, Bamako, BandarSeri Begawan, Bangkok, Bangui, Banjul, Barrow-In-Furness, Basse-Terre, Basseterre, Baton Rouge, Beijing, Beirut,Belfast, Belgrade, Belmopan, Berlin, Bern, Billings, Birmingham, Birmingham, Bishkek, Bismarck, Bissau, Bloem-fontein, Bogota, Boise, Bolton, Boston, Bradford, Brasilia, Bratislava, Brazzaville, Bridgeport, Bridgetown, Brisbane,Bristol, Brussels, Bucharest, Bucuresti, Budapest, Buenos Aires, Buffalo, Bujumbura, Burlington, Cairo, Canberra,Cape Town, Caracas, Cardiff, Carson City, Castries, Cayenne, Charleston, Charlotte, Charlotte Amalie, Cheyenne,Chicago, Chisinau, Cleveland, Columbia, Columbus, Conakry, Concord, Copenhagen, Cotonou, Crawley, Dakar, Dal-las, Damascus, Dammam, Denver, Des Moines, Detroit, Dhaka, Dili, Djibouti, Dodoma, Doha, Douglas, Dover,Dublin, Dushanbe, Edinburgh, El Aaiun, Fargo, Fort-de-France, Frankfort, Freetown, Funafuti, Gaborone, GeorgeTown, Georgetown, Gibraltar, Glasgow, Greenwich, Guatemala, Hanoi, Harare, Harrisburg, Hartford, Havana, He-lena, Helsinki, Hobart, Hong Kong, Honiara, Honolulu, Houston, Indianapolis, Islamabad, Jackson, Jacksonville,Jakarta, Jefferson City, Jerusalem, Juba, Jubail, Juneau, Kabul, Kampala, Kansas City, Kathmandu, Khartoum, Kiev,Kigali, Kingston, Kingston, Kingstown, Kinshasa, Koror, Kuala Lumpur, Kuwait, La Paz, Lansing, Las Vegas, Leeds,Leicester, Libreville, Lilongwe, Lima, Lincoln, Lisbon, Little Rock, Liverpool, Ljubljana, Lome, London, Los Ange-les, Louisville, Luanda, Lusaka, Luxembourg, Macau, Madinah, Madison, Madrid, Majuro, Makkah, Malabo, Male,Mamoudzou, Managua, Manama, Manchester, Manchester, Manila, Maputo, Maseru, Masqat, Mbabane, Mecca,Medina, Memphis, Mexico, Miami, Milwaukee, Minneapolis, Minsk, Mogadishu, Monaco, Monrovia, Montevideo,Montgomery, Montpelier, Moroni, Moscow, Moskva, Mumbai, Muscat, N’Djamena, Nairobi, Nashville, Nassau,Naypyidaw, New Delhi, New Orleans, New York, Newark, Newcastle, Newcastle Upon Tyne, Ngerulmud, Niamey,Nicosia, Norwich, Nouakchott, Noumea, Nuku’alofa, Nuuk, Oklahoma City, Olympia, Omaha, Oranjestad, Orlando,Oslo, Ottawa, Ouagadougou, Oxford, P’yongyang, Pago Pago, Palikir, Panama, Papeete, Paramaribo, Paris, Perth,Philadelphia, Phnom Penh, Phoenix, Pierre, Plymouth, Podgorica, Port Louis, Port Moresby, Port of Spain, Port-Vila,Port-au-Prince, Portland, Portland, Porto-Novo, Portsmouth, Prague, Praia, Pretoria, Pristina, Providence, Quito, Ra-bat, Raleigh, Reading, Reykjavik, Richmond, Riga, Riyadh, Road Town, Rome, Roseau, Sacramento, Saint Helier,Saint Paul, Saint Pierre, Saipan, Salem, Salt Lake City, San Diego, San Francisco, San Jose, San Juan, San Marino,San Salvador, Sana, Sana’a, Santa Fe, Santiago, Santo Domingo, Sao Tome, Sarajevo, Seattle, Seoul, Sheffield, Sin-gapore, Sioux Falls, Skopje, Sofia, Southampton, Springfield, Sri Jayawardenapura Kotte, St. George’s, St. John’s,St. Peter Port, Stanley, Stockholm, Sucre, Suva, Swansea, Swindon, Sydney, T’bilisi, Taipei, Tallahassee, Tallinn,

17


Tarawa, Tashkent, Tbilisi, Tegucigalpa, Tehran, Thimphu, Tirana, Tirane, Tokyo, Toledo, Topeka, Torshavn, Tren-ton, Tripoli, Tunis, Ulaanbaatar, Ulan Bator, Vaduz, Valletta, Vienna, Vientiane, Vilnius, Virginia Beach, W. Indies,Warsaw, Washington DC, Wellington, Wichita, Willemstad, Wilmington, Windhoek, Wolverhampton, Yamoussoukro,Yangon, Yaounde, Yaren, Yerevan, Zagreb

7.1 US Cities

Albany, Albuquerque, Anchorage, Annapolis, Atlanta, Augusta, Austin, Baltimore, Baton Rouge, Billings, Birm-ingham, Bismarck, Boise, Boston, Bridgeport, Buffalo, Burlington, Carson City, Charleston, Charlotte, Cheyenne,Chicago, Cleveland, Columbia, Columbus, Concord, Dallas, Denver, Des Moines, Detroit, Dover, Fargo, Frankfort,Harrisburg, Hartford, Helena, Honolulu, Houston, Indianapolis, Jackson, Jacksonville, Jefferson City, Juneau, KansasCity, Lansing, Las Vegas, Lincoln, Little Rock, Los Angeles, Louisville, Madison, Manchester, Memphis, Miami,Milwaukee, Minneapolis, Montgomery, Montpelier, Nashville, New Orleans, New York, Newark, Oklahoma City,Olympia, Omaha, Orlando, Philadelphia, Phoenix, Pierre, Portland, Portland, Providence, Raleigh, Richmond, Sacra-mento, Saint Paul, Salem, Salt Lake City, San Diego, San Francisco, Santa Fe, Seattle, Sioux Falls, Springfield,Tallahassee, Toledo, Topeka, Trenton, Virginia Beach, Wichita, Wilmington

18 Chapter 7. Cities

CHAPTER 8

Thanks

The sun calculations in this module were adapted, for Python, from the spreadsheets on the following page.

https://www.esrl.noaa.gov/gmd/grad/solcalc/calcdetails.html

The moon phase calculation is based on some javascript code from Sky and Telescope magazine

Moon-phase calculationRoger W. Sinnott, Sky & Telescope, June 16, 2006.

Also to Sphinx for making doc generation an easy thing (not that the writing of the docs is any easier.)

19

https://www.esrl.noaa.gov/gmd/grad/solcalc/calcdetails.html

http://www.skyandtelescope.com/wp-content/observing-tools/moonphase/moon.html

http://sphinx.pocoo.org/


20 Chapter 8. Thanks

CHAPTER 9

Contact

Simon Kennedy <[email protected]>

21

mailto:[email protected]


22 Chapter 9. Contact

CHAPTER 10

Version History

Version Description1.10 Added support to AstralGeocoder to add additional lo-

cations to the database.1.9.2 1.9 broke the sun_utc method. Sun UTC calculation

passed incorrect parameter to more specific methodse.g. sunrise, sunset etc.

1.9.1 Correct version number in astral.py1.9 Now takes elevation into account.1.8

• Location methods now allow the timezone to beNone which returns all times as UTC.

• Added command line interface to return ‘sun’ val-ues

1.7.1• Changed GoogleGeocoder test to not use

raise. . . from as this is not valid for Python 2

1.7• Requests is now only needed when using Google-

Geocoder• GoogleGeocoder now requires the api_key pa-

rameter to be passed to the constructor as Googlenow require it for their API calls.

1.6.1• Updates for Travis CI integration / Github signed

release.

Continued on next page

23


Table 1 – continued from previous pageVersion Description1.6

• Added api_key parameter to the GoogleGeocoder__init__() method

1.5• Added parameter rtype to moon_phase() to

determine the return type of the method.• Added example for calculating the phase of the

moon.

1.4.1• Using versioneer to manage version numbers

1.4• Changed to use calculations from NOAA spread-

sheets• Changed some exception error messages for

when sun does not reach a requested elevation.• Added more tests

1.3.4• Changes to project configuration files. No user

facing changes.

1.3.3• Fixed call to twilight_utc as date and direction pa-

rameters were reversed.

1.3.2• Updated URL to point to gitgub.com• Added Apache 2.0 boilerplate to source file

1.3.1• Added LICENSE file to sdist

1.3• Corrected solar zenith to return the angle from the

vertical.• Added solar midnight calculation.

1.2• Added handling for when unicode literals are

used. This may possibly affect your code if you’reusing Python 2 (there are tests for this but theymay not catch all uses.) (Bug 1588198)

• Changed timezone for Phoenix, AZ to Amer-ica/Phoenix (Bug 1561258)

Continued on next page

24 Chapter 10. Version History

https://bugs.launchpad.net/astral/+bug/1588198




• Added methods to calculate Twilight, the GoldenHour and the Blue Hour.

1.0• It’s time for a version 1.0• Added examples where the location you want is

not in the Astral geocoder.

0.9• Added a method to calculate the date and time

when the sun is at a specific elevation, for either arising or a setting sun.

• Added daylight and night methods to Locationand Astral classes.

• Rahukaalam methods now return a tuple.

0.8.2• Fix for moon phase calcualtions which were off

by 1.• Use pytz.timezone().localize method instead of

passing tzinfo parameter to datetime.datetime.See the pytz docs for info

0.8.1• Fix for bug 1417641: solar_elevation()

and solar_azimuth() fail when a naivedatetime object is used.

• Added solar_zenith() methods toAstral and Location as an alias forsolar_elevation()

• Added tzinfo as an alias for tz

0.8 Fix for bug 1407773: Moon phase calculation changedto remove time zone parameter (tz) as it is not requiredfor the calculation.

0.7.5 Fix for bug 1402103: Buenos Aires incorrect timezone0.7.4 Added Canadian cities from Yip Shing Ho0.7.3 Fix for bug 1239387 submitted by Torbjörn Lönnemark0.7.2 Minor bug fix in GoogleGeocoder. location name

and region are now stripped of whitespace0.7.1 Bug fix. Missed a vital return statement in the

GoogleGeocoderContinued on next page

25

http://pytz.sourceforge.net/#localized-times-and-date-arithmetic


https://docs.python.org/3/library/datetime.html#datetime.datetime






• Added ability to lookup location infor-mation from Google’s mapping APIs (seeGoogleGeocoder)

• Renamed City class to Location• Renamed CityDB to AstralGeocoder• Added elevations of cities to database and prop-

erty to obtain elevation from Location class

0.6.2 Added various cities to database as per https://bugs.launchpad.net/astral/+bug/1040936

0.6.1• Docstrings were not updated to match changes to

code.• Other minor docstring changes made

0.6• Fix for bug 884716 submitted by Martin

Heemskerk regarding moon phase calculations• Fixes for bug report 944754 submitted by Hajo

Werder– Changed co-ordinate system so that eastern

longitudes are now positive– Added solar_depression property to City

class

0.5• Changed City to accept unicode name and coun-

try.• Moved city information into a database classCityDB

• Added attribute access to database for timezonegroups

0.4• Duplicate city names could not be accessed.• Sun calculations for some cities failed with times

outside valid ranges.• Fixes for city data.• Added calculation for moon phase.

0.3• Changed to Apache V2.0 license.• Fix for bug 555508 submitted by me.• US state capitals and other cities added.

0.2 Fix for bug 554041 submitted by Derek_ / John Dimatos0.1 First release






http://www.opensource.org/licenses/apache2.0.php




10.1 The astral Module

Calculations for the position of the sun and moon.

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

The module provides 2 main classes Astral and Location.

Astral Has 2 main responsibilities

• Calculates the events in the UTC timezone.

• Provides access to location data

Location Holds information about a location and provides functions to calculate the event times for the location inthe correct time zone.

For example

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

The module currently provides 2 methods of obtaining location information; AstralGeocoder (the default, whichuses information from within the module) and GoogleGeocoder (which obtains information from Google’s MapService.)

To use the GoogleGeocoder pass the class as the geocoder parameter to Astral.__init__() or by setting thegeocoder property to an instance of GoogleGeocoder:

>>> from astral import GoogleGeocoder>>> a = Astral(GoogleGeocoder)

or

>>> from astral import GoogleGeocoder>>> a = Astral()>>> a.geocoder = GoogleGeocoder()

10.1.1 Astral

class astral.Astral(geocoder=<class ’astral.AstralGeocoder’>)

10.1. The astral Module 27


__getitem__(key)Returns the Location instance specified by key.

solar_depressionThe number of degrees the sun must be below the horizon for the dawn/dusk calculation.

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

String Degreescivil 6.0nautical 12.0astronomical 18.0

sun_utc(date, latitude, longitude, observer_elevation=0)Calculate all the info for the sun at once. All times are returned 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

• elevation (int) – Elevation in metres to calculate sunrise for

Returns Dictionary with keys dawn, sunrise, noon, sunset and dusk whose values arethe results of the corresponding _utc methods.

Return type dict

dawn_utc(date, latitude, longitude, depression=0, observer_elevation=0)Calculate dawn time in the UTC timezone.

Parameters




• depression (float) – Override the depression used

Returns The UTC date and time at which dawn occurs.

Return type datetime

sunrise_utc(date, latitude, longitude, observer_elevation=0)Calculate sunrise time in the UTC timezone.

Parameters




Returns The UTC date and time at which sunrise occurs.


solar_noon_utc(date, longitude)Calculate solar noon time in the UTC timezone.


https://docs.python.org/3/library/datetime.html#datetime.date

https://docs.python.org/3/library/functions.html#float


https://docs.python.org/3/library/functions.html#int

https://docs.python.org/3/library/stdtypes.html#dict











Parameters



Returns The UTC date and time at which noon occurs.


sunset_utc(date, latitude, longitude, observer_elevation=0)Calculate sunset time in the UTC timezone.

Parameters




Returns The UTC date and time at which sunset occurs.


dusk_utc(date, latitude, longitude, depression=0, observer_elevation=0)Calculate dusk time in the UTC timezone.

Parameters




• depression (float) – Override the depression used

Returns The UTC date and time at which dusk occurs.


solar_midnight_utc(date, longitude)Calculate solar midnight time in the UTC timezone.

Note that this claculates the solar midgnight that is closest to 00:00:00 of the specified date i.e. it mayreturn a time that is on the previous day.

Parameters



Returns The UTC date and time at which midnight occurs.


daylight_utc(date, latitude, longitude, observer_elevation=0)Calculate daylight start and end times in the UTC timezone.

Parameters




Returns A tuple of the UTC date and time at which daylight starts and ends.





















Return type (datetime, datetime)

night_utc(date, latitude, longitude, observer_elevation=0)Calculate night start and end times in the UTC timezone.

Night is calculated to be between astronomical dusk on the date specified and astronomical dawn of thenext day.

Parameters




Returns A tuple of the UTC date and time at which night starts and ends.


twilight_utc(direction, date, latitude, longitude, observer_elevation=0)Returns the start and end times of Twilight in the UTC timezone when the sun is traversing in the specifieddirection.

This method defines twilight as being between the time when the sun is at -6 degrees and sunrise/sunset.

Parameters

• direction (int) – Determines whether the time is for the sun rising or setting. Useastral.SUN_RISING or astral.SUN_SETTING.

• date (datetime.date) – The date for which to calculate the times.



Returns A tuple of the UTC date and time at which twilight starts and ends.


golden_hour_utc(direction, date, latitude, longitude, observer_elevation=0)Returns the start and end times of the Golden Hour in the UTC timezone when the sun is traversing in thespecified direction.

This method uses the definition from PhotoPills i.e. the golden hour is when the sun is between 4 degreesbelow the horizon and 6 degrees above.

Parameters





Returns A tuple of the UTC date and time at which the Golden Hour starts and ends.


blue_hour_utc(direction, date, latitude, longitude, observer_elevation=0)Returns the start and end times of the Blue Hour in the UTC timezone when the sun is traversing in thespecified direction.






















This method uses the definition from PhotoPills i.e. the blue hour is when the sun is between 6 and 4degrees below the horizon.

Parameters





Returns A tuple of the UTC date and time at which the Blue Hour starts and ends.


time_at_elevation_utc(elevation, direction, date, latitude, longitude, observer_elevation=0)Calculate the time in the UTC timezone when the sun is at the specified elevation on the specified date.

Note: This method uses positive elevations for those above the horizon.

Parameters

• elevation (float) – Elevation in degrees above the horizon to calculate for.

• direction (int) – Determines whether the calculated time is for the sun rising orsetting. Use astral.SUN_RISING or astral.SUN_SETTING. Default is rising.




Returns The UTC date and time at which the sun is at the required elevation.


solar_azimuth(dateandtime, latitude, longitude)Calculate the azimuth angle of the sun.

Parameters

• dateandtime (datetime) – The date and time for which to calculate the angle.



Returns The azimuth angle in degrees clockwise from North.

Return type float

If dateandtime is a naive Python datetime then it is assumed to be in the UTC timezone.

solar_elevation(dateandtime, latitude, longitude)Calculate the elevation angle of the sun.

Parameters




Returns The elevation angle in degrees above the horizon.






















Return type float


solar_zenith(dateandtime, latitude, longitude)Calculates the solar zenith angle.

Parameters




Returns The zenith angle in degrees from vertical.

Return type float


moon_phase(date, rtype=<type ’int’>)Calculates the phase of the moon on the specified date.

Parameters

• date (datetime.date) – The date to calculate the phase for.

• rtype – The type to return either int (default) or float.

Returns

A number designating the phase.

0 = New moon7 = First quarter14 = Full moon21 = Last quarter

rahukaalam_utc(date, latitude, longitude, observer_elevation=0)Calculate ruhakaalam times in the UTC timezone.

Parameters




Returns Tuple containing the start and end times for Rahukaalam.

Return type tuple

10.1.2 Location

class astral.Location(info=None)Provides access to information for single location.

__init__(info=None)Initializes the object with a tuple of information.

Parameters info – A tuple of information to fill in the location info.

The tuple should contain items in the following order











https://docs.python.org/3/library/stdtypes.html#tuple


Field Defaultname Greenwichregion Englandlatitude 51.168longitude 0time zone name Europe/Londonelevation 24

See timezone property for a method of obtaining time zone names

latitudeThe location’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.

longitudeThe location’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 East.

elevationThe elevation in metres above sea level.

timezoneThe name of the time zone for the location.

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

>>> from pytz import all_timezones>>> for timezone in all_timezones:... print(timezone)

tzTime zone information.

tzinfoTime zone information.

solar_depressionThe number of degrees the sun must be below the horizon for the dawn/dusk calculation.

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

String Degreescivil 6.0nautical 12.0astronomical 18.0



sun(date=None, local=True, use_elevation=True)Returns dawn, sunrise, noon, sunset and dusk as a dictionary.

Parameters

• date (date) – The date for which to calculate the times. If no date is specified then thecurrent date will be used.

• local (bool) – True = Time to be returned in location’s time zone; False = Time to bereturned in UTC. If not specified then the time will be returned in local time

• use_elevation (bool) – True = Return times that allow for the location’s elevation;False = Return times that don’t use elevation If not specified then times will take elevationinto account.

Returns Dictionary with keys dawn, sunrise, noon, sunset and dusk whose values arethe results of the corresponding methods.

Return type dict

dawn(date=None, local=True, use_elevation=True)Calculates the time in the morning when the sun is a certain number of degrees below the horizon. Bydefault this is 6 degrees but can be changed by setting the Astral.solar_depression property.

Parameters

• date (date) – The date for which to calculate the dawn time. If no date is specified thenthe current date will be used.



Returns The date and time at which dawn occurs.


sunrise(date=None, local=True, use_elevation=True)Return sunrise time.

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

Parameters

• date (date) – The date for which to calculate the sunrise time. If no date is specifiedthen the current date will be used.



Returns The date and time at which sunrise occurs.


solar_noon(date=None, local=True)Calculates the solar noon (the time when the sun is at its highest point.)



https://docs.python.org/3/library/functions.html#bool


https://docs.python.org/3/library/stdtypes.html#dict










Parameters

• date (date) – The date for which to calculate the noon time. If no date is specified thenthe current date will be used.


Returns The date and time at which the solar noon occurs.


sunset(date=None, local=True, use_elevation=True)Calculates sunset time (the time in the evening when the sun is a 0.833 degrees below the horizon. This isto account for refraction.)

Parameters

• date (date) – The date for which to calculate the sunset time. If no date is specifiedthen the current date will be used.



Returns The date and time at which sunset occurs.


dusk(date=None, local=True, use_elevation=True)Calculates the dusk time (the time in the evening when the sun is a certain number of degrees below thehorizon. By default this is 6 degrees but can be changed by setting the solar_depression property.)

Parameters

• date (date) – The date for which to calculate the dusk time. If no date is specified thenthe current date will be used.



Returns The date and time at which dusk occurs.


daylight(date=None, local=True, use_elevation=True)Calculates the daylight time (the time between sunrise and sunset)

Parameters

• date (date) – The date for which to calculate daylight. If no date is specified then thecurrent date will be used.


















Returns A tuple containing the start and end times

Return type tuple(datetime, datetime)

night(date=None, local=True, use_elevation=True)Calculates the night time (the time between astronomical dusk and astronomical dawn of the next day)

Parameters

• date (date) – The date for which to calculate the start of the night time. If no date isspecified then the current date will be used.



Returns A tuple containing the start and end times

Return type tuple(datetime, datetime)

twilight(direction=SUN_RISING, date=None, local=True)Returns the start and end times of Twilight in the UTC timezone when the sun is traversing in the specifieddirection.

This method defines twilight as being between the time when the sun is at -6 degrees and sunrise/sunset.

Parameters





Returns A tuple of the UTC date and time at which twilight starts and ends.


golden_hour(direction=SUN_RISING, date=None, local=True)Returns the start and end times of the Golden Hour when the sun is traversing in the specified direction.

This method uses the definition from PhotoPills i.e. the golden hour is when the sun is between 4 degreesbelow the horizon and 6 degrees above.

Parameters

• direction (int) – Determines whether the time is for the sun rising or setting. Useastral.SUN_RISING or astral.SUN_SETTING. Default is rising.


• local (bool) – True = Times to be returned in location’s time zone; False = Times tobe returned in UTC. If not specified then the time will be returned in local time





















Returns A tuple of the date and time at which the Golden Hour starts and ends.


blue_hour(direction=SUN_RISING, date=None, local=True)Returns the start and end times of the Blue Hour when the sun is traversing in the specified direction.

This method uses the definition from PhotoPills i.e. the blue hour is when the sun is between 6 and 4degrees below the horizon.

Parameters


• date (date) – The date for which to calculate the times. If no date is specified then thecurrent date will be used.

• local (bool) – True = Times to be returned in location’s time zone; False = Times tobe returned in UTC. If not specified then the time will be returned in local time


Returns A tuple of the date and time at which the Blue Hour starts and ends.


time_at_elevation(elevation, direction=SUN_RISING, date=None, local=True)Calculate the time when the sun is at the specified elevation.

Note: This method uses positive elevations for those above the horizon.

Elevations greater than 90 degrees are converted to a setting sun i.e. an elevation of 110 will calculatea setting sun at 70 degrees.

Parameters

• elevation (float) – Elevation in degrees above the horizon to calculate for.


• date (date) – The date for which to calculate the elevation time. If no date is specifiedthen the current date will be used.


Returns The date and time at which dusk occurs.


solar_azimuth(dateandtime=None)Calculates the solar azimuth angle for a specific date/time.

Parameters dateandtime (datetime) – The date and time for which to calculate the angle.

Returns The azimuth angle in degrees clockwise from North.


















Return type float

solar_elevation(dateandtime=None)Calculates the solar elevation angle for a specific time.


Returns The elevation angle in degrees above the horizon.

Return type float

solar_zenith(dateandtime=None)Calculates the solar zenith angle for a specific time.


Returns The zenith angle in degrees from vertical.

Return type float

moon_phase(date=None, rtype=<type ’int’>)Calculates the moon phase for a specific date.

Parameters date (datetime.date) – The date to calculate the phase for. If ommitted thecurrent date is used.

Returns

A number designating the phase

0 = New moon7 = First quarter14 = Full moon21 = Last quarter

rahukaalam(date=None, local=True, use_elevation=True)Calculates the period of rahukaalam.

Parameters

• date (date) – The date for which to calculate the rahukaalam period. A value of Noneuses the current date.

• local (bool) – True = Time to be returned in location’s time zone; False = Time to bereturned in UTC.


Returns Tuple containing the start and end times for Rahukaalam.

Return type tuple

10.1.3 Geocoders

class astral.AstralGeocoderLooks up geographic information from the locations stored within the module

add_locations(locations)Add extra locations to AstralGeocoder.

Extra locations can be











https://docs.python.org/3/library/stdtypes.html#tuple


• A single string containing one or more locations separated by a newline.

• A list of strings

• A list of lists/tuples that are passed to a Location constructor

class astral.GoogleGeocoder(api_key, cache=False)Use Google Maps API Web Service to lookup GPS co-ordinates, timezone and elevation.

See the following for more info. https://developers.google.com/maps/documentation/


https://developers.google.com/maps/documentation/

Python Module Index

aastral, 27

41


42 Python Module Index

Index

Symbols__getitem__() (astral.Astral method), 27__init__() (astral.Location method), 32

Aadd_locations() (astral.AstralGeocoder method), 38Astral (class in astral), 27astral (module), 27AstralGeocoder (class in astral), 38

Bblue_hour() (astral.Location method), 37blue_hour_utc() (astral.Astral method), 30

Ddawn() (astral.Location method), 34dawn_utc() (astral.Astral method), 28daylight() (astral.Location method), 35daylight_utc() (astral.Astral method), 29dusk() (astral.Location method), 35dusk_utc() (astral.Astral method), 29

Eelevation (astral.Location attribute), 33

Ggolden_hour() (astral.Location method), 36golden_hour_utc() (astral.Astral method), 30GoogleGeocoder (class in astral), 39

Llatitude (astral.Location attribute), 33Location (class in astral), 32longitude (astral.Location attribute), 33

Mmoon_phase() (astral.Astral method), 32moon_phase() (astral.Location method), 38

Nnight() (astral.Location method), 36night_utc() (astral.Astral method), 30

Rrahukaalam() (astral.Location method), 38rahukaalam_utc() (astral.Astral method), 32

Ssolar_azimuth() (astral.Astral method), 31solar_azimuth() (astral.Location method), 37solar_depression (astral.Astral attribute), 28solar_depression (astral.Location attribute), 33solar_elevation() (astral.Astral method), 31solar_elevation() (astral.Location method), 38solar_midnight_utc() (astral.Astral method), 29solar_noon() (astral.Location method), 34solar_noon_utc() (astral.Astral method), 28solar_zenith() (astral.Astral method), 32solar_zenith() (astral.Location method), 38sun() (astral.Location method), 33sun_utc() (astral.Astral method), 28sunrise() (astral.Location method), 34sunrise_utc() (astral.Astral method), 28sunset() (astral.Location method), 35sunset_utc() (astral.Astral method), 29

Ttime_at_elevation() (astral.Location method), 37time_at_elevation_utc() (astral.Astral method), 31timezone (astral.Location attribute), 33twilight() (astral.Location method), 36twilight_utc() (astral.Astral method), 30tz (astral.Location attribute), 33tzinfo (astral.Location attribute), 33

43

astral v1 - read the docs · astral v1.7, release 1.7 astral is a python module for calculating the...

Documents