suntimes

library1.1.2pypypi✓ verified 84d ago

The `suntimes` library (version 1.1.2) provides functions to calculate sunrise and sunset times for a given geographical location (longitude, latitude, altitude) and day. It returns times in UTC and local time, handles polar day/night scenarios, and can generate yearly timetables in JSON or CSV format. It is actively maintained and has a steady release cadence for minor updates.

data

pip install suntimes

github ↗package ↗

INSTALL

IMPORT

SIG · SUNTIMES

suntimes

datapythonv1.1.2

Install

1.8s avg

Import

164ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.1.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.230s · 21.2MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.8s · import 0.097s · 22MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SunTimes

✓ from suntimes import SunTimes

SunFiles

✓ from suntimes import SunFiles

Used for generating and saving yearly timetables.

datetime

✓ import datetime

Standard library for date/time objects.

This quickstart demonstrates how to initialize the `SunTimes` object with geographical coordinates and retrieve sunrise and sunset times for a given date in UTC and a specified local timezone using `pytz`. It also includes an example of handling dates near the poles where 'Polar Day' or 'Polar Night' strings are returned.

import datetime from suntimes import SunTimes import pytz # Required for specific timezone handling # Define location (e.g., Paris, France) longitude = 2.349902 latitude = 48.852968 altitude = 0 # meters, default is 0 # Create a SunTimes instance for the location sun = SunTimes(longitude, latitude, altitude) # Get today's sunrise and sunset in UTC today = datetime.date.today() utc_sunrise = sun.riseutc(today) utc_sunset = sun.setutc(today) print(f"Today (UTC): Sunrise at {utc_sunrise.strftime('%H:%M:%S')}, Sunset at {utc_sunset.strftime('%H:%M:%S')}") # Get sunrise and sunset in a specific timezone paris_tz = pytz.timezone('Europe/Paris') local_sunrise = sun.risewhere(today, paris_tz) local_sunset = sun.setwhere(today, paris_tz) print(f"Today (Paris): Sunrise at {local_sunrise.strftime('%H:%M:%S')}, Sunset at {local_sunset.strftime('%H:%M:%S')}") # Example for a date in the past some_date = datetime.date(2023, 7, 15) summer_sunrise = sun.risewhere(some_date, paris_tz) summer_sunset = sun.setwhere(some_date, paris_tz) print(f"On {some_date.isoformat()} (Paris): Sunrise at {summer_sunrise.strftime('%H:%M:%S')}, Sunset at {summer_sunset.strftime('%H:%M:%S')}") # Handling Polar Day/Night (returns specific string for rise/set times if applicable) polar_lat = 89.0 # Near North Pole polar_sun = SunTimes(0, polar_lat) polar_date = datetime.date(2023, 6, 21) # Summer solstice polar_rise = polar_sun.riseutc(polar_date) polar_set = polar_sun.setutc(polar_date) print(f"On {polar_date.isoformat()} at {polar_lat}°N (UTC): Sunrise: {polar_rise}, Sunset: {polar_set}")

suntimes --version

Debug

Known issues

gotchaThe library's calculations have a precision of 'one to several minutes'. Results are not guaranteed to be accurate to the second and should not be relied upon for high-precision applications requiring sub-minute accuracy.

fix

Do not expect sub-minute precision. Truncate or round results to the minute if presenting to users.

affects: All versions

gotchaAccuracy decreases significantly closer to the Earth's poles. While the library handles polar day/night scenarios by returning specific strings, the numerical results for times close to these periods may have lower accuracy.

fix

Be aware of reduced accuracy when using coordinates with high latitudes (close to +/- 90 degrees).

affects: All versions

deprecatedOlder versions of a *different* 'suntime' library (not 'suntimes' by p-mathis) had deprecated methods like 'get_local_sunrise_time()' and 'get_local_sunset_time()'. While not directly applicable to 'p-mathis/suntimes', ensure you are using the 'risewhere()' and 'setwhere()' methods with explicit timezone arguments for local times to avoid confusion.

fix

Always use 'sun.risewhere(date, timezone)' and 'sun.setwhere(date, timezone)' for local times with `p-mathis/suntimes` for clarity and correctness. For UTC, use `sun.riseutc(date)` and `sun.setutc(date)`.

affects: N/A (relevant to related 'suntime' library)

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'suntimes'

The `suntimes` package is not installed in your current Python environment.

fix

Install the package using pip: `pip install suntimes`

TypeError: risewhere() missing 1 required positional argument: 'timezone'

You called `risewhere()` or `setwhere()` without providing a timezone object, which is required for these methods.

fix

Provide a timezone object (e.g., from `pytz.timezone('Europe/Paris')`) as the second argument: `sun.risewhere(some_date, my_timezone)`.

NameError: name 'SunTimes' is not defined

The `SunTimes` class was not imported correctly.

fix

Ensure you have `from suntimes import SunTimes` at the top of your script.

Upgrade

Version history

1.1.2latest on PyPI · released Jul 1, 2022

Audit

Dependencies

pytzrequiredRequired for timezone handling.

tzlocalrequiredRequired for determining local timezone.

jdcalrequiredUsed for Julian date calculations.

Agent activity

5 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/p-mathis/suntimes ↗

packagehttps://pypi.org/project/suntimes/ ↗