{"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":"en","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,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}