feat: Added get_night to celerity/night module.

src/celerity/night.py

@@ -7,8 +7,7 @@
 # *****************************************************************************************************************
 
 from datetime import datetime, timedelta
-from math import radians
-from typing import List, Optional, Tuple
+from typing import List, Optional, Tuple, TypedDict
 
 from .common import GeographicCoordinate, HorizontalCoordinate
 from .coordinates import convert_equatorial_to_horizontal
@@ -18,6 +17,14 @@
 # *****************************************************************************************************************
 
 
+class Night(TypedDict):
+    start: datetime
+    end: datetime
+
+
+# *****************************************************************************************************************
+
+
 def get_solar_transit(
     date: datetime, observer: GeographicCoordinate, horizon: float = 0
 ) -> Tuple[Optional[datetime], Optional[datetime], Optional[datetime]]:
@@ -81,6 +88,32 @@ def get_solar_transit(
 # *****************************************************************************************************************
 
 
+def get_night(
+    date: datetime, observer: GeographicCoordinate, horizon: float = 0
+) -> Optional[Night]:
+    """
+    Determine the start and end of the night for the given date and location.
+
+    :param date: The date to check.
+    :param observer: The geographic coordinates of the observer.
+    :param horizon: The altitude of the horizon in degrees.
+    """
+    # Get the time of the sunset for the given date::
+    _, _, sunset = get_solar_transit(date, observer, horizon)
+
+    # Get the time of the sunrise for the following date:
+    sunrise, _, _ = get_solar_transit(date + timedelta(days=1), observer, horizon)
+
+    # The observer could be in perpetual daylight or perpetual night, e.g., the North Pole or South Pole:
+    if sunset is None or sunrise is None:
+        return None
+
+    return {"start": sunset, "end": sunrise}
+
+
+# *****************************************************************************************************************
+
+
 def is_night(
     date: datetime, observer: GeographicCoordinate, horizon: float = 0
 ) -> bool:

tests/test_night.py

@@ -1,7 +1,7 @@
 from datetime import datetime, timezone
 
 from src.celerity.common import GeographicCoordinate
-from src.celerity.night import get_solar_transit, is_night
+from src.celerity.night import get_night, get_solar_transit, is_night
 
 # For testing we need to specify a date because most calculations are
 # differential w.r.t a time component. We set it to the author's birthday:
@@ -44,6 +44,12 @@ def test_get_solar_transit():
     assert d[2] == datetime(2021, 5, 14, 22, 43, 0, 0, tzinfo=timezone.utc)
 
 
+def test_get_night():
+    d = get_night(date, observer)
+    assert d["start"] == datetime(2021, 5, 14, 19, 56, 0, 0, tzinfo=timezone.utc)
+    assert d["end"] == datetime(2021, 5, 15, 4, 45, 0, 0, tzinfo=timezone.utc)
+
+
 def test_is_night():
     # At 2am UTC on the specified date, it should be night:
     date = datetime(2021, 5, 14, 2, 0, 0, 0, tzinfo=timezone.utc)