{"id":4339,"library":"astral","title":"Astral Library","description":"Astral is a Python package for calculating the times of various aspects of the sun and moon, including dawn, sunrise, noon, sunset, dusk, and moon phases. It also provides functions for solar azimuth and elevation. The library includes a self-contained geocoder for looking up location information by name. The current version is 3.2, and it maintains an active release cadence, frequently adding new features and improvements.","status":"active","version":"3.2","language":"python","source_language":"en","source_url":"https://github.com/sffjunkie/astral","tags":["astronomy","sun","moon","time","geocoder","daylight","datetime"],"install":[{"cmd":"pip install astral","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for Python versions prior to 3.9 when timezone functionality is used, as `astral` transitioned from `pytz` to `zoneinfo` in version 3.0.","package":"backports.zoneinfo","optional":true}],"imports":[{"symbol":"LocationInfo","correct":"from astral.location import LocationInfo"},{"symbol":"Observer","correct":"from astral.geocoder import lookup\nfrom astral import Observer"},{"symbol":"sun","correct":"from astral.sun import sun"},{"symbol":"moonphase","correct":"from astral.moon import moonphase"},{"note":"The `Astral` class and direct dictionary-like access for cities (`a[city_name]`) are part of an older API. Modern usage prefers `lookup` from `astral.geocoder` to retrieve `LocationInfo` objects.","wrong":"from astral import Astral\na = Astral()\ncity = a['London']","symbol":"Astral","correct":"from astral.geocoder import lookup, database\ncity = lookup(\"London\", database())"}],"quickstart":{"code":"import datetime\nfrom astral.location import LocationInfo\nfrom astral.sun import sun\n\n# Define a location\nl = LocationInfo('London', 'England', 'Europe/London', 51.5, 0.1)\n\n# Get an Observer object from the LocationInfo\nobserver = l.observer\n\n# Get sun times for today\ntoday = datetime.date.today()\ns = sun(observer, date=today)\n\nprint(f\"Sun Information for {l.name} on {today}:\")\nprint(f\"  Dawn: {s['dawn']}\")\nprint(f\"  Sunrise: {s['sunrise']}\")\nprint(f\"  Noon: {s['noon']}\")\nprint(f\"  Sunset: {s['sunset']}\")\nprint(f\"  Dusk: {s['dusk']}\")","lang":"python","description":"This example demonstrates how to define a location using `LocationInfo`, retrieve an `Observer` object, and then calculate the sun's key events (dawn, sunrise, noon, sunset, dusk) for a specific date."},"warnings":[{"fix":"For Python < 3.9, install `backports.zoneinfo`: `pip install backports.zoneinfo`. Ensure your code handles `zoneinfo` objects instead of `pytz` timezone objects.","message":"In version 3.0, `astral` migrated from `pytz` to Python's built-in `zoneinfo` for timezone handling. This means for Python versions prior to 3.9, you will need to explicitly install `backports.zoneinfo` to ensure timezone functionality works correctly.","severity":"breaking","affected_versions":">=3.0"},{"fix":"Migrate to using `astral.geocoder.lookup(name, database())` to retrieve `LocationInfo` objects, and then access the `observer` attribute to get the `Observer` object.","message":"The direct use of `astral.Astral()` and accessing cities like `a['London']` is part of an older API and may not function as expected or be supported in future versions. The `Astral` class itself was removed in version 3.0.","severity":"deprecated","affected_versions":">=3.0"},{"fix":"Always use timezone-aware `datetime` objects. For Python >= 3.9, use `zoneinfo.ZoneInfo('timezone_name')`. For Python < 3.9, ensure `backports.zoneinfo` is installed and use its `ZoneInfo` for timezone localization.","message":"When passing `datetime` objects to functions like `sun()` or `azimuth()`, if the datetime object is 'naive' (i.e., lacks timezone information), `astral` will assume it represents a UTC time. This can lead to incorrect calculations if the user expects local time.","severity":"gotcha","affected_versions":"All"},{"fix":"When initializing `GoogleGeocoder`, pass your Google Maps API key as the `api_key` parameter: `GoogleGeocoder(api_key='YOUR_API_KEY')`. For simple location lookups without an API key, use the built-in `astral.geocoder.database()` and `lookup()`.","message":"The Google Geocoder (`astral.geocoder.GoogleGeocoder`) requires an API key, as mandated by Google. Attempting to use it without providing a valid API key will result in errors.","severity":"gotcha","affected_versions":">=1.6"},{"fix":"Be aware of this limitation when performing highly precise solar elevation calculations, particularly for observers at very high altitudes. The documentation indicates the difference is usually negligible for most applications.","message":"The `astral` package currently does not adjust solar elevation calculations for changes in observer elevation. While the effect is generally very small, users requiring extreme precision for high elevations might find this behavior unexpected.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"search_vec":"'3.2':57 'activ':62 'ad':66 'also':30 'aspect':14 'astral':1,3 'astronomi':71 'azimuth':35 'cadenc':64 'calcul':9 'contain':44 'current':54 'datetim':77 'dawn':21 'daylight':76 'dusk':25 'elev':37 'featur':68 'frequent':65 'function':32 'geocod':45,75 'improv':70 'includ':20,40 'inform':50 'librari':2,39 'locat':49 'look':47 'maintain':60 'moon':19,27,73 'name':52 'new':67 'noon':23 'packag':7 'phase':28 'provid':31 'python':6 'releas':63 'self':43 'self-contain':42 'solar':34 'sun':17,72 'sunris':22 'sunset':24 'time':11,74 'various':13 'version':55","created_at":"2026-04-12T08:51:32.703985+00:00","updated_at":"2026-04-15T21:13:58.832336+00:00","problems":[{"fix":"Adjust the parameters or handle exceptions for locations where the sun does not meet the expected conditions.","cause":"This error occurs when calculating sun events at high latitudes where the sun does not dip below 6 degrees below the horizon, making certain calculations invalid.","error":"ValueError: Sun never reaches 6.0 degrees below the horizon, at this location"},{"fix":"Verify the location and date parameters to ensure they are within valid ranges for sun transit calculations.","cause":"This error arises when attempting to calculate sun transit events at locations or dates where the sun does not reach the specified zenith angle.","error":"ValueError: Sun never transits at a zenith of 96.0 on YYYY-MM-DD"},{"fix":"Install the Astral library using pip: `pip install astral`.","cause":"This error indicates that the Astral library is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'astral'"},{"fix":"Update the import statement to: `from astral import LocationInfo`.","cause":"This error occurs due to changes in the Astral library's API, where 'Location' has been replaced with 'LocationInfo'.","error":"ImportError: cannot import name 'Location' from 'astral'"},{"fix":"Ensure that the 'observer' parameter is provided when calling the 'sun' function, e.g., `sun(observer=location.observer, date=datetime.date.today())`.","cause":"This error happens when the 'sun' function is called without providing the required 'observer' parameter.","error":"TypeError: sun() missing 1 required positional argument: 'observer'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.2","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/sffjunkie/astral","docs":"https://sffjunkie.github.io/astral","changelog":null,"pypi":"https://pypi.org/project/astral/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}