pylunar 0.7.1__py3-none-any.whl

pylunar/__init__.py

@@ -0,0 +1,42 @@
+# This file is part of pylunar.
+#
+# Developed by Michael Reuter.
+#
+# See the LICENSE file at the top-level directory of this distribution
+# for details of code ownership.
+#
+# Use of this source code is governed by a 3-clause BSD-style
+# license that can be found in the LICENSE file.
+
+__all__ = [
+    "__author__",
+    "__email__",
+    "__version__",
+    "LunarFeature",
+    "LunarFeatureContainer",
+    "mjd_to_date_tuple",
+    "MoonInfo",
+    "tuple_to_string",
+    "version_info",
+]
+
+from importlib.metadata import PackageNotFoundError, version
+
+__author__ = "Michael Reuter"
+__email__ = "mareuternh@gmail.com"
+try:
+    __version__ = version("pylunar")
+except PackageNotFoundError:
+    # package is not installed
+    __version__ = "0.0.0"
+
+version_info = __version__.split(".")
+"""The decomposed version, split across "``.``."
+
+Use this for version comparison.
+"""
+
+from .helpers import mjd_to_date_tuple, tuple_to_string
+from .lunar_feature import LunarFeature
+from .lunar_feature_container import LunarFeatureContainer
+from .moon_info import MoonInfo

pylunar/helpers.py

@@ -0,0 +1,55 @@
+# This file is part of pylunar.
+#
+# Developed by Michael Reuter.
+#
+# See the LICENSE file at the top-level directory of this distribution
+# for details of code ownership.
+#
+# Use of this source code is governed by a 3-clause BSD-style
+# license that can be found in the LICENSE file.
+
+"""Module for helper functions."""
+
+from __future__ import annotations
+
+__all__ = ["mjd_to_date_tuple", "tuple_to_string"]
+
+import ephem
+
+from .types import DateTimeTuple, DmsCoordinate
+
+
+def mjd_to_date_tuple(mjd: float, round_off: bool = False) -> DateTimeTuple:
+    """Convert a Modified Julian date to a UTC time tuple.
+
+    Parameters
+    ----------
+    mjd : float
+        The Modified Julian Date to convert.
+    round_off : bool, optional
+        Flag to round the seconds.
+
+    Returns
+    -------
+    tuple
+        The UTC time for the MJD.
+    """
+    date_tuple: DateTimeTuple
+    date_tuple = tuple(int(x) for x in ephem.Date(mjd).tuple()) if round_off else ephem.Date(mjd).tuple()
+    return date_tuple
+
+
+def tuple_to_string(coord: DmsCoordinate) -> str:
+    """Return a colon-delimited string.
+
+    Parameters
+    ----------
+    coord : tuple of 3 ints
+        The coordinate to transform.
+
+    Returns
+    -------
+    str
+        The colon-delimited coordinate string.
+    """
+    return ":".join([str(x) for x in coord])

pylunar/lunar_feature.py

@@ -0,0 +1,179 @@
+# This file is part of pylunar.
+#
+# Developed by Michael Reuter.
+#
+# See the LICENSE file at the top-level directory of this distribution
+# for details of code ownership.
+#
+# Use of this source code is governed by a 3-clause BSD-style
+# license that can be found in the LICENSE file.
+
+"""Module for the LunarFeature class."""
+
+from __future__ import annotations
+
+__all__ = ["LunarFeature"]
+
+import math
+import os
+
+from .types import FeatureRow, Range
+
+
+class LunarFeature:
+    """Class keeping all the information for a given Lunar feature.
+
+    Parameters
+    ----------
+    name : str
+        The name of the Lunar feature (no unicode).
+    diameter : float
+        The diameter (km) of the Lunar feature.
+    latitude : float
+        The latitude (degrees) of the Lunar feature. Negative is South,
+        positive is North.
+    longitude : float
+        The longitude (degrees) of the Lunar feature. Negative is West,
+        positive is East.
+    delta_latitude : float
+        The size (degrees) in latitude of the Lunar feature.
+    delta_longitude : float
+        The size (degrees) in longitude of the Lunar feature.
+    feature_type : str
+        The classification of the Lunar feature: i.e. Crater, Mons.
+    quad_name : str
+        Name of lunar quadrant containing feature's center point as
+        determined by the International Astronomical Union (IAU) Working
+        Group for Planetary System Nomenclature (WGPSN).
+    quad_code : str
+        Specific lunar quadrant containing feature's center point as
+        determined by the IAU WGPSN.
+    code_name : str
+        The AstroLeague club name for the Lunar feature. Can be: Lunar,
+        LunarII or Both.
+    lunar_club_type : str or None
+        The Lunar Club classification of the feature: Naked Eye, Binocular,
+        Telescope. For a LunarII only feature this is None.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        diameter: float,
+        latitude: float,
+        longitude: float,
+        delta_latitude: float,
+        delta_longitude: float,
+        feature_type: str,
+        quad_name: str,
+        quad_code: str,
+        code_name: str,
+        lunar_club_type: str | None,
+    ):
+        self.name = name
+        self.diameter = diameter
+        self.latitude = latitude
+        self.longitude = longitude
+        self.delta_latitude = delta_latitude
+        self.delta_longitude = delta_longitude
+        self.feature_type = feature_type
+        self.quad_name = quad_name
+        self.quad_code = quad_code
+        self.code_name = code_name
+        self.lunar_club_type = str(lunar_club_type)
+
+    def __str__(self) -> str:
+        """Class string representation.
+
+        Returns
+        -------
+        str
+            The string representation.
+        """
+        result = []
+        result.append(f"Name = {self.name}")
+        result.append(f"Lat/Long = ({self.latitude:.2f}, {self.longitude:.2f})")
+        result.append(f"Type = {self.feature_type}")
+        result.append(f"Delta Lat/Long = ({self.delta_latitude:.2f}, {self.delta_longitude:.2f})")
+        return os.linesep.join(result)
+
+    @classmethod
+    def from_row(cls: type[LunarFeature], row: FeatureRow) -> LunarFeature:
+        """Initialize from a database row.
+
+        Parameters
+        ----------
+        row : list
+            The database row containing the information.
+
+        Returns
+        -------
+        :class:`.LunarFeature`
+            Class initialized from database row.
+        """
+        return cls(*row[1:])
+
+    def feature_angle(self) -> float:
+        """Get the angle of the feature on the lunar face relative to North.
+
+        The feature angle is determined by calculating atan2(lon, lat) and
+        then adding 360 degrees if the result is less than zero. This makes
+        North zero degrees, East 90 degrees, South 180 degrees and West 270
+        degrees.
+
+        Returns
+        -------
+        float
+            The feature angle in degrees.
+        """
+        lat_rad = math.radians(self.latitude)
+        lon_rad = math.radians(self.longitude)
+        fa = math.degrees(math.atan2(lon_rad, lat_rad))
+        fa += 360.0 if fa < 0 else 0.0
+        return fa
+
+    def latitude_range(self) -> Range:
+        """Get the latitude range of the feature.
+
+        Returns
+        -------
+        tuple(float, float)
+            The (minimum, maximum) latitude values for the feature.
+        """
+        min_lat = self.latitude - (self.delta_latitude / 2.0)
+        max_lat = self.latitude + (self.delta_latitude / 2.0)
+        return (min_lat, max_lat)
+
+    def list_from_feature(self) -> list[object]:
+        """Convert the feature information into a list.
+
+        Returns
+        -------
+        list
+            The list of lunar features.
+        """
+        return [
+            self.name,
+            self.diameter,
+            self.latitude,
+            self.longitude,
+            self.delta_latitude,
+            self.delta_longitude,
+            self.feature_type,
+            self.quad_name,
+            self.quad_code,
+            self.code_name,
+            self.lunar_club_type,
+        ]
+
+    def longitude_range(self) -> Range:
+        """Get the longitude range of the feature.
+
+        Returns
+        -------
+        tuple(float, float)
+            The (minimum, maximum) longitude values for the feature.
+        """
+        min_lon = self.longitude - (self.delta_longitude / 2.0)
+        max_lon = self.longitude + (self.delta_longitude / 2.0)
+        return (min_lon, max_lon)

pylunar/lunar_feature_container.py

@@ -0,0 +1,97 @@
+# This file is part of pylunar.
+#
+# Developed by Michael Reuter.
+#
+# See the LICENSE file at the top-level directory of this distribution
+# for details of code ownership.
+#
+# Use of this source code is governed by a 3-clause BSD-style
+# license that can be found in the LICENSE file.
+
+"""Module for the LunarFeatureContainer class."""
+
+from __future__ import annotations
+
+__all__ = ["LunarFeatureContainer"]
+
+import collections
+import sys
+from typing import Generator
+
+if sys.version_info >= (3, 10):
+    from importlib.resources import files
+else:
+    from importlib_resources import files
+
+import sqlite3
+
+from .lunar_feature import LunarFeature
+from .moon_info import MoonInfo
+
+
+class LunarFeatureContainer:
+    """Collection of Lunar features available from the database.
+
+    Parameters
+    ----------
+    club_name : str
+        The name of the observing club to sort on. Values are Lunar and
+        LunarII.
+    """
+
+    def __init__(self, club_name: str):
+        dbname = str(files("pylunar.data").joinpath("lunar.db"))
+        self.conn = sqlite3.connect(dbname)
+        self.club_name = club_name
+        self.features: dict[int, LunarFeature] = collections.OrderedDict()
+        self.club_type: set[str] = set()
+        self.feature_type: set[str] = set()
+
+    def __iter__(self) -> Generator[LunarFeature, None, None]:
+        """Create iterator for container.
+
+        Yields
+        ------
+        :class:`.LunarFeature`
+            The current lunar feature.
+        """
+        yield from self.features.values()
+
+    def __len__(self) -> int:
+        """Length of the container.
+
+        Returns
+        -------
+        int
+            The length of the container.
+        """
+        return len(self.features)
+
+    def load(self, moon_info: MoonInfo | None = None, limit: int | None = None) -> None:
+        """Read the Lunar features from the database.
+
+        Parameters
+        ----------
+        moon_info : :class:`.MoonInfo`, optional
+            Instance of the Lunar information class.
+        limit : int, optional
+            Restrict the number of features read to the given value.
+        """
+        if len(self.features) != 0:
+            self.features = collections.OrderedDict()
+
+        cur = self.conn.cursor()
+        sql = f'select * from Features where Lunar_Code = "{self.club_name}" or ' 'Lunar_Code = "Both"'
+        if limit is not None:
+            sql += f" limit {limit}"
+        cur.execute(sql)
+
+        for row in cur:
+            feature = LunarFeature.from_row(row)
+            is_visible = True if moon_info is None else moon_info.is_visible(feature)
+            if is_visible:
+                self.features[id(feature)] = feature
+                self.club_type.add(row[11])
+                self.feature_type.add(row[7])
+
+        cur.close()

pylunar/moon_info.py

@@ -0,0 +1,656 @@
+# This file is part of pylunar.
+#
+# Developed by Michael Reuter.
+#
+# See the LICENSE file at the top-level directory of this distribution
+# for details of code ownership.
+#
+# Use of this source code is governed by a 3-clause BSD-style
+# license that can be found in the LICENSE file.
+
+"""Module for the MoonInfo class."""
+
+from __future__ import annotations
+
+__all__ = ["MoonInfo"]
+
+from datetime import datetime
+from enum import Enum
+import math
+from operator import itemgetter
+
+import ephem
+import pytz
+
+from .helpers import mjd_to_date_tuple, tuple_to_string
+from .lunar_feature import LunarFeature
+from .types import DateTimeTuple, DmsCoordinate, MoonPhases
+
+
+class PhaseName(Enum):
+    """Phase names for the lunar cycle."""
+
+    NEW_MOON = 0
+    WAXING_CRESCENT = 1
+    FIRST_QUARTER = 2
+    WAXING_GIBBOUS = 3
+    FULL_MOON = 4
+    WANING_GIBBOUS = 5
+    LAST_QUARTER = 6
+    WANING_CRESCENT = 7
+
+
+class TimeOfDay(Enum):
+    """Time of day from the lunar terminator."""
+
+    MORNING = 0
+    EVENING = 1
+
+
+class MoonInfo:
+    """Handle all moon information.
+
+    Attributes
+    ----------
+    observer : ephem.Observer instance.
+        The instance containing the observer's location information.
+    moon : ephem.Moon instance
+        The instance of the moon object.
+
+    Parameters
+    ----------
+    latitude : tuple of 3 ints
+        The latitude of the observer in GPS DMS(Degrees, Minutes and
+        Seconds) format.
+    longitude : tuple of 3 ints
+        The longitude of the observer in GPS DMS(Degrees, Minutes and
+        Seconds) format.
+    name : str, optional
+        A name for the observer's location.
+    """
+
+    DAYS_TO_HOURS = 24.0
+    MAIN_PHASE_CUTOFF = 2.0
+    # Time cutoff (hours) around the NM, FQ, FM, and LQ phases
+    FEATURE_CUTOFF = 15.0
+    # The offset (degrees) from the colongitude used for visibility check
+    NO_CUTOFF_TYPE = ("Landing Site", "Mare", "Oceanus")
+    # Feature types that are not subject to longitude cutoffs
+    LIBRATION_ZONE = 80.0
+    # Latitude and/or longitude where librations have a big effect
+    MAXIMUM_LIBRATION_PHASE_ANGLE_CUTOFF = 65.0
+    # The maximum value of the libration phase angle difference for a feature
+
+    reverse_phase_lookup = {
+        "new_moon": (ephem.previous_last_quarter_moon, "last_quarter"),
+        "first_quarter": (ephem.previous_new_moon, "new_moon"),
+        "full_moon": (ephem.previous_first_quarter_moon, "first_quarter"),
+        "last_quarter": (ephem.previous_full_moon, "full_moon"),
+    }
+
+    def __init__(self, latitude: DmsCoordinate, longitude: DmsCoordinate, name: str | None = None):
+        self.observer = ephem.Observer()
+        self.observer.lat = tuple_to_string(latitude)
+        self.observer.long = tuple_to_string(longitude)
+        self.moon = ephem.Moon()
+
+    def age(self) -> float:
+        """Lunar age in days.
+
+        Returns
+        -------
+        float
+            The lunar age.
+        """
+        prev_new = ephem.previous_new_moon(self.observer.date)
+        return float(self.observer.date - prev_new)
+
+    def fractional_age(self) -> float:
+        """Lunar fractional age which is always less than 1.0.
+
+        Returns
+        -------
+        float
+            The fractional lunar age.
+        """
+        prev_new = ephem.previous_new_moon(self.observer.date)
+        next_new = ephem.next_new_moon(self.observer.date)
+        return float((self.observer.date - prev_new) / (next_new - prev_new))
+
+    def altitude(self) -> float:
+        """Lunar altitude in degrees.
+
+        Returns
+        -------
+        float
+            The lunar altitiude.
+        """
+        return math.degrees(self.moon.alt)
+
+    def angular_size(self) -> float:
+        """Lunar current angular size in degrees.
+
+        Returns
+        -------
+        float
+            The lunar angular size.
+        """
+        moon_size: float = self.moon.size
+        return moon_size / 3600.0
+
+    def azimuth(self) -> float:
+        """Lunar azimuth in degrees.
+
+        Returns
+        -------
+        float
+            The lunar azimuth.
+        """
+        return math.degrees(self.moon.az)
+
+    def colong(self) -> float:
+        """Lunar selenographic colongitude in degrees.
+
+        Returns
+        -------
+        float
+            The lunar seleographic colongitude.
+        """
+        return math.degrees(self.moon.colong)
+
+    def dec(self) -> float:
+        """Lunar current declination in degrees.
+
+        Returns
+        -------
+        float
+            The lunar declination.
+        """
+        return math.degrees(self.moon.dec)
+
+    def earth_distance(self) -> float:
+        """Lunar current distance from the earth in km.
+
+        Returns
+        -------
+        float
+            THe earth-moon distance.
+        """
+        return float(self.moon.earth_distance * ephem.meters_per_au / 1000.0)
+
+    def elongation(self) -> float:
+        """Lunar elongation from the sun in degrees.
+
+        Returns
+        -------
+        float
+            The lunar solar elongation.
+        """
+        elongation = math.degrees(self.moon.elong)
+        if elongation < 0:
+            elongation += 360.0
+        return elongation
+
+    def fractional_phase(self) -> float:
+        """Lunar fractional illumination which is always less than 1.0.
+
+        Returns
+        -------
+        float
+            The lunar fractional phase.
+        """
+        return float(self.moon.moon_phase)
+
+    def libration_lat(self) -> float:
+        """Lunar current latitudinal libration in degrees.
+
+        Returns
+        -------
+        float
+            The lunar libration latitude.
+        """
+        return math.degrees(self.moon.libration_lat)
+
+    def libration_lon(self) -> float:
+        """Lunar current longitudinal libration in degrees.
+
+        Returns
+        -------
+        float
+            The lunar libration longitude.
+        """
+        return math.degrees(self.moon.libration_long)
+
+    def libration_phase_angle(self) -> float:
+        """Phase angle of lunar current libration in degrees.
+
+        Returns
+        -------
+        float
+            The lunar libration phase angle.
+        """
+        phase_angle = math.atan2(self.moon.libration_long, self.moon.libration_lat)
+        phase_angle += 2.0 * math.pi if phase_angle < 0 else 0.0
+        return math.degrees(phase_angle)
+
+    def magnitude(self) -> float:
+        """Lunar current magnitude.
+
+        Returns
+        -------
+        float
+            The lunar magnitude.
+        """
+        return float(self.moon.mag)
+
+    def colong_to_long(self) -> float:
+        """Selenographic longitude in degrees based on the terminator.
+
+        Returns
+        -------
+        float
+            The lunar seleographic longitude.
+        """
+        colong: float = self.colong()
+        if 90.0 <= colong < 270.0:
+            longitude = 180.0 - colong
+        elif 270.0 <= colong < 360.0:
+            longitude = 360.0 - colong
+        else:
+            longitude = -colong
+
+        return longitude
+
+    def is_libration_ok(self, feature: LunarFeature) -> bool:
+        """Determine if lunar feature is visible due to libration effect.
+
+        Parameters
+        ----------
+        feature : :class:`.LunarFeature`
+            The lunar feature instance to check.
+
+        Returns
+        -------
+        bool
+            True if visible, False if not.
+        """
+        is_lon_in_zone = math.fabs(feature.longitude) > self.LIBRATION_ZONE
+        is_lat_in_zone = math.fabs(feature.latitude) > self.LIBRATION_ZONE
+        if is_lat_in_zone or is_lon_in_zone:
+            feature_angle = feature.feature_angle()
+            libration_phase_angle = self.libration_phase_angle()
+            delta_phase_angle = libration_phase_angle - feature_angle
+            delta_phase_angle -= 360.0 if delta_phase_angle > 180.0 else 0.0
+
+            return math.fabs(delta_phase_angle) <= self.MAXIMUM_LIBRATION_PHASE_ANGLE_CUTOFF
+
+        return True
+
+    def is_visible(self, feature: LunarFeature) -> bool:
+        """Determine if lunar feature is visible.
+
+        Parameters
+        ----------
+        feature : :class:`.LunarFeature`
+            The lunar feature instance to check.
+
+        Returns
+        -------
+        bool
+            True if visible, False if not.
+        """
+        selco_lon = self.colong_to_long()
+        current_tod = self.time_of_day()
+
+        min_lon = feature.longitude - feature.delta_longitude / 2
+        max_lon = feature.longitude + feature.delta_longitude / 2
+
+        if min_lon > max_lon:
+            min_lon, max_lon = max_lon, min_lon
+
+        is_visible = False
+        latitude_scaling = math.cos(math.radians(feature.latitude))
+        if feature.feature_type not in MoonInfo.NO_CUTOFF_TYPE:
+            cutoff = MoonInfo.FEATURE_CUTOFF / latitude_scaling
+        else:
+            cutoff = MoonInfo.FEATURE_CUTOFF
+
+        if current_tod == TimeOfDay.MORNING.name:
+            # Minimum longitude for morning visibility
+            lon_cutoff = min_lon - cutoff
+            if feature.feature_type in MoonInfo.NO_CUTOFF_TYPE:
+                is_visible = selco_lon <= min_lon
+            else:
+                is_visible = lon_cutoff <= selco_lon <= min_lon
+        else:
+            # Maximum longitude for evening visibility
+            lon_cutoff = max_lon + cutoff
+            if feature.feature_type in MoonInfo.NO_CUTOFF_TYPE:
+                is_visible = max_lon <= selco_lon
+            else:
+                is_visible = max_lon <= selco_lon <= lon_cutoff
+
+        return is_visible and self.is_libration_ok(feature)
+
+    def next_four_phases(self) -> MoonPhases:
+        """Next four phases in date sorted order (closest phase first).
+
+        Returns
+        -------
+        list[(str, float)]
+            Set of lunar phases specified by an abbreviated phase name and
+            Modified Julian Date.
+        """
+        phases = {}
+        phases["new_moon"] = ephem.next_new_moon(self.observer.date)
+        phases["first_quarter"] = ephem.next_first_quarter_moon(self.observer.date)
+        phases["full_moon"] = ephem.next_full_moon(self.observer.date)
+        phases["last_quarter"] = ephem.next_last_quarter_moon(self.observer.date)
+
+        sorted_phases = sorted(phases.items(), key=itemgetter(1))
+        sorted_phases = [(phase[0], mjd_to_date_tuple(phase[1])) for phase in sorted_phases]
+
+        return sorted_phases
+
+    def phase_name(self) -> str:
+        """Return standard name of lunar phase, i.e. Waxing Cresent.
+
+        This function returns a standard name for lunar phase based on the
+        current selenographic colongitude.
+
+        Returns
+        -------
+        str
+            The lunar phase name.
+        """
+        next_phase_name = self.next_four_phases()[0][0]
+        try:
+            next_phase_time = getattr(ephem, f"next_{next_phase_name}")(self.observer.date)
+        except AttributeError:
+            next_phase_time = getattr(ephem, f"next_{next_phase_name}_moon")(self.observer.date)
+        previous_phase = self.reverse_phase_lookup[next_phase_name]
+        time_to_next_phase = math.fabs(next_phase_time - self.observer.date) * self.DAYS_TO_HOURS
+        time_to_previous_phase = (
+            math.fabs(self.observer.date - previous_phase[0](self.observer.date)) * self.DAYS_TO_HOURS
+        )
+        previous_phase_name = previous_phase[1]
+
+        phase_name = ""
+        if time_to_previous_phase < self.MAIN_PHASE_CUTOFF:
+            phase_name = getattr(PhaseName, previous_phase_name.upper()).name
+        elif time_to_next_phase < self.MAIN_PHASE_CUTOFF:
+            phase_name = getattr(PhaseName, next_phase_name.upper()).name
+        else:
+            if previous_phase_name == "new_moon" and next_phase_name == "first_quarter":
+                phase_name = PhaseName.WAXING_CRESCENT.name
+            elif previous_phase_name == "first_quarter" and next_phase_name == "full_moon":
+                phase_name = PhaseName.WAXING_GIBBOUS.name
+            elif previous_phase_name == "full_moon" and next_phase_name == "last_quarter":
+                phase_name = PhaseName.WANING_GIBBOUS.name
+            elif previous_phase_name == "last_quarter" and next_phase_name == "new_moon":
+                phase_name = PhaseName.WANING_CRESCENT.name
+        return phase_name
+
+    def phase_shape_in_ascii(self) -> str:
+        """Display lunar phase shape in ASCII art.
+
+        This function returns a multi-line string demonstrate current lunar
+        shape in ASCII format.
+
+        Returns
+        -------
+        str
+            The lunar phase shape.
+        """
+        phase = self.phase_name()
+
+        if phase == PhaseName.NEW_MOON.name:
+            return """   _..._
+ .:::::::.
+:::::::::::
+:::::::::::
+`:::::::::'
+  `':::''        """
+        elif phase == PhaseName.WAXING_CRESCENT.name:
+            return """   _..._
+ .::::. `.
+:::::::.  :
+::::::::  :
+`::::::' .'
+  `'::'-'        """
+        elif phase == PhaseName.FIRST_QUARTER.name:
+            return """   _..._
+ .::::  `.
+::::::    :
+::::::    :
+`:::::   .'
+  `'::.-'        """
+        elif phase == PhaseName.WAXING_GIBBOUS.name:
+            return """   _..._
+ .::'   `.
+:::       :
+:::       :
+`::.     .'
+  `':..-'        """
+        elif phase == PhaseName.FULL_MOON.name:
+            return """   _..._
+ .'     `.
+:         :
+:         :
+`.       .'
+  `-...-'        """
+        elif phase == PhaseName.WANING_GIBBOUS.name:
+            return """   _..._
+ .'   `::.
+:       :::
+:       :::
+`.     .::'
+  `-..:''        """
+        elif phase == PhaseName.LAST_QUARTER.name:
+            return """   _..._
+ .'  ::::.
+:    ::::::
+:    ::::::
+`.   :::::'
+  `-.::''        """
+        elif phase == PhaseName.WAXING_CRESCENT.name:
+            return """   _..._
+ .' .::::.
+:  ::::::::
+:  ::::::::
+`. '::::::'
+  `-.::''        """
+        else:
+            return phase
+
+    def phase_emoji(self) -> str:
+        """Return standard emoji of lunar phase, i.e. '🌒'.
+
+        This function returns a standard emoji for lunar phase based on the
+        current selenographic colongitude.
+
+        Returns
+        -------
+        str
+            The lunar phase emoji.
+        """
+        return {
+            "NEW_MOON": "🌑",
+            "WAXING_CRESCENT": "🌒",
+            "FIRST_QUARTER": "🌓",
+            "WAXING_GIBBOUS": "🌔",
+            "FULL_MOON": "🌕",
+            "WANING_GIBBOUS": "🌖",
+            "LAST_QUARTER": "🌗",
+            "WANING_CRESCENT": "🌘",
+        }[self.phase_name()]
+
+    def ra(self) -> float:
+        """Lunar current right ascension in degrees.
+
+        Returns
+        -------
+        float
+            The lunar right ascension.
+        """
+        return math.degrees(self.moon.ra)
+
+    def rise_set_times(self, timezone: str) -> MoonPhases:
+        """Calculate the rise, set and transit times in the local time system.
+
+        Parameters
+        ----------
+        timezone : str
+            The timezone identifier for the calculations.
+
+        Returns
+        -------
+        list[(str, tuple)]
+            Set of rise, set, and transit times in the local time system. If
+            event does not happen, 'Does not xxx' is tuple value.
+        """
+        utc = pytz.utc
+        try:
+            tz = pytz.timezone(timezone)
+        except pytz.UnknownTimeZoneError:
+            tz = utc
+
+        func_map = {"rise": "rising", "transit": "transit", "set": "setting"}
+
+        # Need to set observer's horizon and pressure to get times
+        old_pressure = self.observer.pressure
+        old_horizon = self.observer.horizon
+
+        self.observer.pressure = 0
+        self.observer.horizon = "-0:34"
+
+        current_date_utc = datetime(*mjd_to_date_tuple(self.observer.date, round_off=True), tzinfo=utc)  # type: ignore
+        current_date = current_date_utc.astimezone(tz)
+        current_day = current_date.day
+        times = {}
+        does_not = None
+        for time_type in ("rise", "transit", "set"):
+            mjd_time = getattr(self.observer, "{}_{}".format("next", func_map[time_type]))(self.moon)
+            utc_time = datetime(*mjd_to_date_tuple(mjd_time, round_off=True), tzinfo=utc)  # type: ignore
+            local_date = utc_time.astimezone(tz)
+            if local_date.day == current_day:
+                times[time_type] = local_date
+            else:
+                mjd_time = getattr(self.observer, "{}_{}".format("previous", func_map[time_type]))(self.moon)
+                utc_time = datetime(*mjd_to_date_tuple(mjd_time, round_off=True), tzinfo=utc)  # type: ignore
+                local_date = utc_time.astimezone(tz)
+                if local_date.day == current_day:
+                    times[time_type] = local_date
+                else:
+                    does_not = (time_type, f"Does not {time_type}")
+
+        # Return observer and moon to previous state
+        self.observer.pressure = old_pressure
+        self.observer.horizon = old_horizon
+        self.moon.compute(self.observer)
+
+        original_sorted_times = sorted(times.items(), key=itemgetter(1))
+        sorted_times: MoonPhases = [(xtime[0], xtime[1].timetuple()[:6]) for xtime in original_sorted_times]
+        if does_not is not None:
+            sorted_times.insert(0, does_not)
+
+        return sorted_times
+
+    def subsolar_lat(self) -> float:
+        """Latitude in degress on the moon where the sun is overhead.
+
+        Returns
+        -------
+        float
+            The lunar subsolar latitude.
+        """
+        return math.degrees(self.moon.subsolar_lat)
+
+    def time_of_day(self) -> str:
+        """Terminator time of day.
+
+        This function determines if the terminator is sunrise (morning) or
+        sunset (evening).
+
+        Returns
+        -------
+        str
+            The lunar time of day.
+        """
+        colong = self.colong()
+        if 90.0 <= colong < 270.0:
+            return TimeOfDay.EVENING.name
+        else:
+            return TimeOfDay.MORNING.name
+
+    def time_from_new_moon(self) -> float:
+        """Time (hours) from the previous new moon.
+
+        This function calculates the time from the previous new moon.
+
+        Returns
+        -------
+        float
+            The time from new moon.
+        """
+        previous_new_moon = ephem.previous_new_moon(self.observer.date)
+        return float(MoonInfo.DAYS_TO_HOURS * (self.observer.date - previous_new_moon))
+
+    def time_to_full_moon(self) -> float:
+        """Time (days) to the next full moon.
+
+        This function calculates the time to the next full moon.
+
+        Returns
+        -------
+        float
+            The time to full moon.
+        """
+        next_full_moon = ephem.next_full_moon(self.observer.date)
+        return float(next_full_moon - self.observer.date)
+
+    def time_to_new_moon(self) -> float:
+        """Time (hours) to the next new moon.
+
+        This function calculates the time to the next new moon.
+
+        Returns
+        -------
+        float
+            The time to new moon.
+        """
+        next_new_moon = ephem.next_new_moon(self.observer.date)
+        return float(MoonInfo.DAYS_TO_HOURS * (next_new_moon - self.observer.date))
+
+    def update(self, datetime: DateTimeTuple) -> None:
+        """Update the moon information based on time.
+
+        This fuction updates the Observer instance's datetime setting. The
+        incoming datetime tuple should be in UTC with the following placement
+        of values: (YYYY, m, d, H, M, S) as defined below::
+
+            YYYY
+                Four digit year
+
+            m
+                month (1-12)
+
+            d
+                day (1-31)
+
+            H
+                hours (0-23)
+
+            M
+                minutes (0-59)
+
+            S
+                seconds (0-59)
+
+        Parameters
+        ----------
+        datetime : tuple
+            The current UTC time in a tuple of numbers.
+        """
+        self.observer.date = datetime
+        self.moon.compute(self.observer)

pylunar/types.py

@@ -0,0 +1,31 @@
+# This file is part of pylunar.
+#
+# Developed by Michael Reuter.
+#
+# See the LICENSE file at the top-level directory of this distribution
+# for details of code ownership.
+#
+# Use of this source code is governed by a 3-clause BSD-style
+# license that can be found in the LICENSE file.
+
+"""Module for holding types."""
+
+from __future__ import annotations
+
+import sys
+
+if sys.version_info >= (3, 10):
+    from typing import TypeAlias
+else:
+    from typing_extensions import TypeAlias
+
+from typing import List, Tuple, Union
+
+DateTimeTuple: TypeAlias = Tuple[int, int, int, int, int, Union[int, float]]
+MoonPhases: TypeAlias = List[Tuple[str, Union[DateTimeTuple, str]]]
+DmsCoordinate: TypeAlias = Tuple[int, int, int]
+Range: TypeAlias = Tuple[float, float]
+LunarFeatureList: TypeAlias = Tuple[
+    str, float, float, float, float, float, str, str, str, str, Union[str, None]
+]
+FeatureRow: TypeAlias = Tuple[int, str, float, float, float, float, float, str, str, str, str, str]

pylunar-0.7.1.dist-info/AUTHORS.rst

@@ -0,0 +1,16 @@
+=======
+Credits
+=======
+
+Development Lead
+----------------
+
+* Michael Reuter <mareuternh@gmail.com>
+
+Contributors
+------------
+
+* `1kastner <https://github.com/1kastner>`_
+* `Louis Knapp <https://github.com/lknapp>`_
+* `Bryan Neal Garrison <https://github.com/noblecloud>`_
+* `Peyman Majidi Moein <https://github.com/peymanmajidi>`_

pylunar-0.7.1.dist-info/LICENSE

@@ -0,0 +1,26 @@
+Copyright 2016-2024 Michael Reuter
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pylunar-0.7.1.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.1
+Name: pylunar
+Version: 0.7.1
+Summary: Information for completing the Astronomical League's Lunar and Lunar II observing programs.
+Author-email: Michael Reuter <mareuternh@gmail.com>
+Project-URL: Documentation, http://pylunar.readthedocs.io
+Project-URL: Repository, https://github.com/mareuter/pylunar
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+License-File: AUTHORS.rst
+Requires-Dist: ephem ==4.1.5
+Requires-Dist: pytz ==2024.1
+Requires-Dist: importlib-resources ==6.1.1 ; python_version < "3.10"
+Requires-Dist: typing-extensions ==4.9.0 ; python_version < "3.10"
+Provides-Extra: build
+Requires-Dist: build ==1.0.3 ; extra == 'build'
+Requires-Dist: twine ==4.0.2 ; extra == 'build'
+Provides-Extra: dev
+Requires-Dist: pylunar[build,docs,lint,test] ; extra == 'dev'
+Requires-Dist: tox ==4.11.4 ; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx ~=7.1 ; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme ==2.0.0 ; extra == 'docs'
+Provides-Extra: lint
+Requires-Dist: pre-commit ~=3.5.0 ; extra == 'lint'
+Provides-Extra: test
+Requires-Dist: coverage[toml] ==7.4.0 ; extra == 'test'
+Requires-Dist: pytest ==7.4.4 ; extra == 'test'
+
+=============================
+Python Lunar
+=============================
+
+.. |license| image:: https://img.shields.io/pypi/l/pylunar.svg
+   :target: http://opensource.org/licenses/BSD
+   :alt: BSD License
+
+.. |version| image:: http://img.shields.io/pypi/v/pylunar.svg
+   :target: https://pypi.python.org/pypi/pylunar
+   :alt: Software Version
+
+.. |github| image:: https://github.com/mareuter/pylunar/actions/workflows/ci.yaml/badge.svg
+  :target: https://github.com/mareuter/pylunar
+  :alt: Github build status
+
+.. |python| image:: https://img.shields.io/pypi/pyversions/pylunar.svg
+  :target: https://pypi.python.org/pypi/pylunar
+  :alt: Supported Python
+
+.. |docs| image:: https://readthedocs.org/projects/pylunar/badge/?version=latest
+  :target: https://pylunar.readthedocs.io
+  :alt: Readthedocs status
+
+.. |pre-commit| image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit
+  :target: https://github.com/pre-commit/pre-commit
+  :alt: Uses pre-commit
+
+|license| |python| |version| |github| |docs| |pre-commit|
+
+Information for completing the Astronomical League's Lunar and Lunar II observing programs. Uses the `pyephem <https://rhodesmill.org/pyephem>`_ package to calculate lunar information.
+
+
+Features
+--------
+
+* Offer moon information based on location and date/time.
+* Offer lunar targets for AL observing clubs based on terminator location.
+

pylunar-0.7.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+pylunar/__init__.py,sha256=-I-kK_YCtnOkwYPs2Qe9mCaanU5XJLnXxhHzNbKJpAk,1056
+pylunar/helpers.py,sha256=Ip1koGrhbay318QLOhQCMwBLDA_Q1bKXHDkU_Un3EZE,1323
+pylunar/lunar_feature.py,sha256=oK-ALplg29DtGzKXqPUbssri3K0_1Ftz97SPzNhP8v8,5521
+pylunar/lunar_feature_container.py,sha256=ud8-B_CqQ_0x9FSbkj2eHMPRT5PAwSai6D6tU9dGkQY,2796
+pylunar/moon_info.py,sha256=AdYdfgKgwnL2nRs9QF9x28_pflCaxsX10VKFvqaXLGY,19958
+pylunar/types.py,sha256=DbPCc9_kzRuSOxOfeKaLJdWfykdbzRPnOTY-EN2xrsc,973
+pylunar/data/lunar.db,sha256=y2u5wR_DpHjPYH7fuR-T_q0nbPzN1GuP8_OXorjVr14,28672
+pylunar-0.7.1.dist-info/AUTHORS.rst,sha256=mqGQzrJPFGm44DZxZFs0d080QDWXdtfFlv1i_fdJerg,332
+pylunar-0.7.1.dist-info/LICENSE,sha256=EF_CKfNhkKjEynpn9Msb6HaGNIBN9VfeGyrJFJQ5FYk,1479
+pylunar-0.7.1.dist-info/METADATA,sha256=Jkl2_uVETgCknLpOeWwUhE4bBH0P1kReYzSbldNXxOA,3035
+pylunar-0.7.1.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
+pylunar-0.7.1.dist-info/top_level.txt,sha256=vEQZCgYlUuoq6D4q99Kj5fSpNs2Mo-jW8vKV3dnpI-U,8
+pylunar-0.7.1.dist-info/RECORD,,

pylunar-0.7.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.42.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pylunar-0.7.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+pylunar