solarmoonpy 1.0.1__tar.gz → 1.0.9__tar.gz

{solarmoonpy-1.0.1 → solarmoonpy-1.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: solarmoonpy
-Version: 1.0.1
+Version: 1.0.9
 Summary: Precise solar and lunar calculations for astronomical applications
 Author-email: figorr <jdcuartero@yahoo.es>
 License:                                  Apache License
@@ -221,6 +221,9 @@ License-File: LICENSE
 Dynamic: license-file
 
 # ☀️🌙 solarmoonpy
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+![Version](https://img.shields.io/pypi/v/solarmoonpy)
+
 Solar and moon calculations for Meteocat Home Assistant integration.
 
 **solarmoonpy** is a Python library that provides accurate calculations of solar and lunar positions, specifically designed to integrate with Home Assistant and Meteocat data. 
@@ -229,7 +232,7 @@ This project enables you to obtain information such as sunrise, sunset, moon pha
 
 ## 🚀 Features
 
-- ☀️ Solar position calculations (sunrise, sunset, zenith, etc.).
+- ☀️ Solar position calculations (sunrise, sunset, noon, etc.).
 - 🌙 Moon phase and position calculations.
 - Integration with meteorological data from Meteocat.
 - Compatible with Home Assistant for automations based on solar and lunar events.

{solarmoonpy-1.0.1 → solarmoonpy-1.0.9}/README.md

@@ -1,4 +1,7 @@
 # ☀️🌙 solarmoonpy
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+![Version](https://img.shields.io/pypi/v/solarmoonpy)
+
 Solar and moon calculations for Meteocat Home Assistant integration.
 
 **solarmoonpy** is a Python library that provides accurate calculations of solar and lunar positions, specifically designed to integrate with Home Assistant and Meteocat data. 
@@ -7,7 +10,7 @@ This project enables you to obtain information such as sunrise, sunset, moon pha
 
 ## 🚀 Features
 
-- ☀️ Solar position calculations (sunrise, sunset, zenith, etc.).
+- ☀️ Solar position calculations (sunrise, sunset, noon, etc.).
 - 🌙 Moon phase and position calculations.
 - Integration with meteorological data from Meteocat.
 - Compatible with Home Assistant for automations based on solar and lunar events.

{solarmoonpy-1.0.1 → solarmoonpy-1.0.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "solarmoonpy"
-version = "1.0.1"
+version = "1.0.9"
 description = "Precise solar and lunar calculations for astronomical applications"
 readme = "README.md"
 authors = [{ name = "figorr", email = "jdcuartero@yahoo.es" }]

{solarmoonpy-1.0.1 → solarmoonpy-1.0.9}/solarmoonpy/location.py

@@ -1,9 +1,9 @@
 from dataclasses import dataclass
 from datetime import date, datetime, timezone
 from zoneinfo import ZoneInfo
-from typing import Optional, Union
+from typing import Optional, Union, Literal, Dict
 
-from .sun import sunrise_sunset, noon  # Importar funciones de sun.py
+from .sun import sunrise_sunset, noon, dawn, dusk, midnight, sun_position  # Importar funciones de sun.py
 
 @dataclass
 class LocationInfo:
@@ -253,20 +253,117 @@ class Location:
             date = datetime.now(self.tzinfo if local else timezone.utc).date()
 
         return noon(
-            latitude=self.latitude,
             longitude=self.longitude,
             date=date,
             timezone=self.tzinfo if local else timezone.utc
         )
+    
+    def dawn(
+        self,
+        date: Optional[date] = None,
+        local: bool = True,
+        twilight_type: Literal["civil", "nautical", "astronomical"] = "civil",
+        elevation: Optional[float] = None
+    ) -> Optional[datetime]:
+        """🌅 Calcula amanecer (inicio crepúsculo)."""
+        if local and self.timezone is None:
+            raise ValueError("Se solicitó hora local pero no se definió una zona horaria.")
 
-    def sun_events(
+        date = date or datetime.now(self.tzinfo if local else timezone.utc).date()
+        elevation = elevation if elevation is not None else self.elevation
+        
+        return dawn(
+            latitude=self.latitude,
+            longitude=self.longitude,
+            date=date,
+            twilight_type=twilight_type,
+            elevation=elevation,
+            timezone=self.tzinfo if local else timezone.utc,
+            with_refraction=True
+        )
+
+    def dusk(
         self,
         date: Optional[date] = None,
         local: bool = True,
+        twilight_type: Literal["civil", "nautical", "astronomical"] = "civil",
+        elevation: Optional[float] = None
+    ) -> Optional[datetime]:
+        """🌙 Calcula anochecer (fin crepúsculo)."""
+        if local and self.timezone is None:
+            raise ValueError("Se solicitó hora local pero no se definió una zona horaria.")
+
+        date = date or datetime.now(self.tzinfo if local else timezone.utc).date()
+        elevation = elevation if elevation is not None else self.elevation
+        
+        return dusk(
+            latitude=self.latitude,
+            longitude=self.longitude,
+            date=date,
+            twilight_type=twilight_type,
+            elevation=elevation,
+            timezone=self.tzinfo if local else timezone.utc,
+            with_refraction=True
+        )
+
+    def midnight(
+        self,
+        date: Optional[date] = None,
+        local: bool = True
+    ) -> datetime:
+        """🌑 Calcula medianoche solar."""
+        if local and self.timezone is None:
+            raise ValueError("Se solicitó hora local pero no se definió una zona horaria.")
+
+        date = date or datetime.now(self.tzinfo if local else timezone.utc).date()
+        
+        return midnight(
+            longitude=self.longitude,
+            date=date,
+            timezone=self.tzinfo if local else timezone.utc
+        )
+    
+    def sun_position(
+        self,
+        dt: Optional[datetime] = None,
+        local: bool = True,
         elevation: Optional[float] = None
     ) -> dict:
         """
-        Devuelve un diccionario con sunrise, noon y sunset para una fecha dada.
+        Calcula la posición actual del Sol.
+
+        Args:
+            dt: Momento exacto. Si None, usa ahora.
+            local: True para usar zona horaria local.
+            elevation: Elevación del observador.
+
+        Returns:
+            dict: elevation, azimuth, above_horizon, rising
+        """
+        if local and self.timezone is None:
+            raise ValueError("Se solicitó hora local pero no se definió una zona horaria.")
+
+        tz = self.tzinfo if local else timezone.utc
+        dt = dt or datetime.now(tz)
+        elevation = elevation if elevation is not None else self.elevation
+
+        return sun_position(
+            latitude=self.latitude,
+            longitude=self.longitude,
+            dt=dt,
+            elevation=elevation,
+            timezone=tz,
+            with_refraction=True
+        )
+    
+    def sun_events(
+        self,
+        date: Optional[date] = None,
+        local: bool = True,
+        elevation: Optional[float] = None,
+    ) -> Dict:
+        """
+        Devuelve un diccionario con los eventos solares para una fecha dada, incluyendo todos los tipos de crepúsculo.
 
         Args:
             date: Fecha para la cual calcular los eventos solares. Si es None, usa la fecha actual.
@@ -275,16 +372,25 @@ class Location:
 
         Returns:
             dict: {
+                "dawn_civil": datetime | None,
+                "dawn_nautical": datetime | None,
+                "dawn_astronomical": datetime | None,
                 "sunrise": datetime,
                 "noon": datetime,
-                "sunset": datetime
+                "sunset": datetime,
+                "dusk_civil": datetime | None,
+                "dusk_nautical": datetime | None,
+                "dusk_astronomical": datetime | None,
+                "midnight": datetime,
+                "daylight_duration": float | None
             }
         """
         if local and self.timezone is None:
             raise ValueError("Se solicitó hora local pero no se definió una zona horaria.")
 
         tz = self.tzinfo if local else timezone.utc
-        date = date or datetime.now(tz).date()
+        now = datetime.now(tz)
+        date = date or now.date()
         elevation = elevation if elevation is not None else self.elevation
 
         # Calcular amanecer y atardecer
@@ -299,14 +405,96 @@ class Location:
 
         # Calcular mediodía solar
         noon_time = noon(
+            longitude=self.longitude,
+            date=date,
+            timezone=tz,
+        )
+
+        # Calcular medianoche solar
+        midnight_time = midnight(
+            longitude=self.longitude,
+            date=date,
+            timezone=tz,
+        )
+
+        # Calcular duración del día (en horas)
+        daylight_duration = None
+        if sunrise and sunset:
+            daylight_duration = (sunset - sunrise).total_seconds() / 3600
+
+        # Calcular dawn y dusk para cada tipo de crepúsculo
+        dawn_civil = dawn(
+            latitude=self.latitude,
+            longitude=self.longitude,
+            date=date,
+            twilight_type="civil",
+            elevation=elevation,
+            timezone=tz,
+            with_refraction=True,
+        )
+        dusk_civil = dusk(
             latitude=self.latitude,
             longitude=self.longitude,
             date=date,
+            twilight_type="civil",
+            elevation=elevation,
             timezone=tz,
+            with_refraction=True,
         )
+        dawn_nautical = dawn(
+            latitude=self.latitude,
+            longitude=self.longitude,
+            date=date,
+            twilight_type="nautical",
+            elevation=elevation,
+            timezone=tz,
+            with_refraction=True,
+        )
+        dusk_nautical = dusk(
+            latitude=self.latitude,
+            longitude=self.longitude,
+            date=date,
+            twilight_type="nautical",
+            elevation=elevation,
+            timezone=tz,
+            with_refraction=True,
+        )
+        dawn_astronomical = dawn(
+            latitude=self.latitude,
+            longitude=self.longitude,
+            date=date,
+            twilight_type="astronomical",
+            elevation=elevation,
+            timezone=tz,
+            with_refraction=True,
+        )
+        dusk_astronomical = dusk(
+            latitude=self.latitude,
+            longitude=self.longitude,
+            date=date,
+            twilight_type="astronomical",
+            elevation=elevation,
+            timezone=tz,
+            with_refraction=True,
+        )
+
+        # Posición actual del Sol
+        pos = self.sun_position(dt=now, local=local, elevation=elevation)
 
         return {
+            "dawn_civil": dawn_civil,
+            "dawn_nautical": dawn_nautical,
+            "dawn_astronomical": dawn_astronomical,
             "sunrise": sunrise,
             "noon": noon_time,
             "sunset": sunset,
-        }
+            "dusk_civil": dusk_civil,
+            "dusk_nautical": dusk_nautical,
+            "dusk_astronomical": dusk_astronomical,
+            "midnight": midnight_time,
+            "daylight_duration": daylight_duration,
+            "sun_elevation": pos["elevation"],
+            "sun_azimuth": pos["azimuth"],
+            "sun_horizon_position": pos["horizon_position"],
+            "sun_rising": pos["rising"],
+        }

{solarmoonpy-1.0.1 → solarmoonpy-1.0.9}/solarmoonpy/moon.py

@@ -374,4 +374,50 @@ def moon_elongation(date_utc: date) -> float:
     jc = julianday_to_juliancentury(jd)
     lambda_m, _, _, _ = _moon_ecliptic_position(jd)
     lambda_s = sun_apparent_long(jc)
-    return _normalize_angle(lambda_m - lambda_s)
+    return _normalize_angle(lambda_m - lambda_s)
+
+def get_moon_phase_name(d: date) -> str:
+    """Determina el nombre de la fase lunar para la fecha dada."""
+    percentage = illuminated_percentage(d)
+    elongation = moon_elongation(d)
+
+    # Determinar nombre intermedio basado en elongación y porcentaje iluminado
+    is_waxing = elongation < 180.0  # <180° creciente, >=180° menguante
+    if percentage < 50.0:
+        phase_name = "waxing_crescent" if is_waxing else "waning_crescent"
+    else:
+        phase_name = "waxing_gibbous" if is_waxing else "waning_gibbous"
+
+    # Verificar fases primarias exactas y override si corresponde
+    last_new = find_last_phase_exact(d, 0.0)
+    if last_new and last_new.date() == d:
+        return "new_moon"
+
+    last_first = find_last_phase_exact(d, 90.0)
+    if last_first and last_first.date() == d:
+        return "first_quarter"
+
+    last_full = find_last_phase_exact(d, 180.0)
+    if last_full and last_full.date() == d:
+        return "full_moon"
+
+    last_last = find_last_phase_exact(d, 270.0)
+    if last_last and last_last.date() == d:
+        return "last_quarter"
+
+    return phase_name
+
+def get_lunation_duration(date_utc: date) -> str:
+    """Calcula la duración exacta de la lunación actual (desde la última luna nueva hasta la siguiente)."""
+    last_new = find_last_phase_exact(date_utc, 0.0)
+    # Buscar la siguiente luna nueva: empezar ~25 días después (buffer seguro)
+    search_date = (last_new + timedelta(days=25)).date()
+    next_new = find_last_phase_exact(search_date + timedelta(days=10), 0.0)  # Buffer para asegurar el cruce
+    if next_new <= last_new:
+        next_new = find_last_phase_exact(search_date + timedelta(days=35), 0.0)  # Seguridad extra si falla
+    duration = next_new - last_new
+    days = duration.days
+    secs = duration.seconds
+    hours = secs // 3600
+    minutes = (secs % 3600) // 60
+    return f"{days}d {hours}h {minutes}m"

{solarmoonpy-1.0.1 → solarmoonpy-1.0.9}/solarmoonpy/sun.py

@@ -1,5 +1,15 @@
 import datetime
 from math import acos, asin, atan2, cos, degrees, radians, sin, tan, sqrt
+from typing import Optional, Tuple, Literal
+
+# Constantes estándar para diferentes eventos solares
+SUN_APPARENT_RADIUS = 959.63 / 3600.0  # ≈ 0.2666° (radio aparente del Sol)
+
+# Zenith angles estándar (90° = horizonte)
+ZENITH_SUNRISE_SUNSET = 90.0 + SUN_APPARENT_RADIUS
+ZENITH_CIVIL_DAWN_DUSK = 96.0
+ZENITH_NAUTICAL_DAWN_DUSK = 102.0
+ZENITH_ASTRONOMICAL_DAWN_DUSK = 108.0
 
 def julianday(date_or_dt: datetime.date | datetime.datetime) -> float:
     """
@@ -239,4 +249,185 @@ def noon(
     time_utc = (720.0 - (4 * longitude) - eqtime)  # minutos
     noon_utc = datetime.datetime(date.year, date.month, date.day, tzinfo=datetime.timezone.utc) \
         + datetime.timedelta(minutes=time_utc)
-    return noon_utc.astimezone(timezone)
+    return noon_utc.astimezone(timezone)
+
+def dawn(
+    latitude: float, longitude: float, date: datetime.date,
+    twilight_type: Literal["civil", "nautical", "astronomical"] = "civil",
+    elevation: float = 0.0,
+    timezone: datetime.timezone = datetime.timezone.utc,
+    with_refraction: bool = True
+) -> Optional[datetime.datetime]:
+    """🌅 Calcula amanecer (inicio crepúsculo)."""
+    zeniths = {"civil": 96.0, "nautical": 102.0, "astronomical": 108.0}
+    zenith = zeniths[twilight_type]
+    
+    # Reutiliza la misma lógica que sunrise_sunset pero para un zenith específico
+    adjustment_for_elevation = adjust_to_horizon(elevation)
+    adjusted_zenith = zenith + adjustment_for_elevation
+    if with_refraction:
+        adjusted_zenith += refraction_at_zenith(adjusted_zenith)
+
+    latitude = max(min(latitude, 89.8), -89.8)
+    jd = julianday(date)
+    jc = julianday_to_juliancentury(jd)
+    declination = sun_declination(jc)
+    eqtime = eq_of_time(jc)
+
+    try:
+        ha_rising = hour_angle(latitude, declination, adjusted_zenith, "rising")
+    except ValueError:
+        return None
+
+    delta = -longitude - degrees(ha_rising)
+    time_utc_minutes = 720.0 + (delta * 4.0) - eqtime
+    if time_utc_minutes < -720.0:
+        time_utc_minutes += 1440
+
+    base_dt = datetime.datetime(date.year, date.month, date.day, tzinfo=datetime.timezone.utc)
+    result_utc = base_dt + datetime.timedelta(minutes=time_utc_minutes)
+    return result_utc.astimezone(timezone)
+
+def dusk(
+    latitude: float, longitude: float, date: datetime.date,
+    twilight_type: Literal["civil", "nautical", "astronomical"] = "civil",
+    elevation: float = 0.0,
+    timezone: datetime.timezone = datetime.timezone.utc,
+    with_refraction: bool = True
+) -> Optional[datetime.datetime]:
+    """🌙 Calcula anochecer (fin crepúsculo)."""
+    zeniths = {"civil": 96.0, "nautical": 102.0, "astronomical": 108.0}
+    zenith = zeniths[twilight_type]
+    
+    adjustment_for_elevation = adjust_to_horizon(elevation)
+    adjusted_zenith = zenith + adjustment_for_elevation
+    if with_refraction:
+        adjusted_zenith += refraction_at_zenith(adjusted_zenith)
+
+    latitude = max(min(latitude, 89.8), -89.8)
+    jd = julianday(date)
+    jc = julianday_to_juliancentury(jd)
+    declination = sun_declination(jc)
+    eqtime = eq_of_time(jc)
+
+    try:
+        ha_setting = hour_angle(latitude, declination, adjusted_zenith, "setting")
+    except ValueError:
+        return None
+
+    delta = -longitude - degrees(ha_setting)
+    time_utc_minutes = 720.0 + (delta * 4.0) - eqtime
+    if time_utc_minutes < -720.0:
+        time_utc_minutes += 1440
+
+    base_dt = datetime.datetime(date.year, date.month, date.day, tzinfo=datetime.timezone.utc)
+    result_utc = base_dt + datetime.timedelta(minutes=time_utc_minutes)
+    return result_utc.astimezone(timezone)
+
+def midnight(
+    longitude: float,
+    date: datetime.date,
+    timezone: datetime.timezone = datetime.timezone.utc
+) -> datetime.datetime:
+    """🌑 Medianoche solar (12h después del mediodía solar)."""
+    noon_time = noon(longitude, date, timezone)
+    return noon_time + datetime.timedelta(hours=12)
+
+def sun_position(
+    latitude: float,
+    longitude: float,
+    dt: datetime.datetime,
+    elevation: float = 0.0,
+    timezone: datetime.timezone = datetime.timezone.utc,
+    with_refraction: bool = True
+) -> dict:
+    """
+    Calcula la posición del Sol con alta precisión.
+    """
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone)
+    dt_utc = dt.astimezone(datetime.timezone.utc)
+
+    jd = julianday(dt_utc)
+    jc = julianday_to_juliancentury(jd)
+    declination = sun_declination(jc)
+    eqtime = eq_of_time(jc)
+
+    # Tiempo solar verdadero en minutos desde medianoche
+    true_solar_time = (
+        dt_utc.hour * 60 + dt_utc.minute + dt_utc.second / 60.0
+        + eqtime + 4.0 * longitude
+    )
+
+    # Ángulo horario
+    hour_angle = (true_solar_time / 4.0) - 180.0
+    if hour_angle < -180:
+        hour_angle += 360
+    elif hour_angle > 180:
+        hour_angle -= 360
+
+    # Convertir a radianes
+    ha_rad = radians(hour_angle)
+    lat_rad = radians(latitude)
+    dec_rad = radians(declination)
+
+    # Elevación geométrica
+    sin_elev = sin(lat_rad) * sin(dec_rad) + cos(lat_rad) * cos(dec_rad) * cos(ha_rad)
+    elevation_geom = degrees(asin(max(min(sin_elev, 1.0), -1.0)))
+
+    # Corrección por altura del observador
+    elevation_adj = elevation_geom + adjust_to_horizon(elevation)
+
+    # Refracción atmosférica
+    if with_refraction and -10 <= elevation_adj <= 90:
+        refraction = refraction_at_zenith(90.0 - elevation_adj)
+        elevation_final = elevation_adj + refraction
+    else:
+        elevation_final = elevation_adj
+
+    # Azimut (0° = Norte)
+    sin_elev_final = sin(radians(elevation_final))
+    cos_elev_final = cos(radians(elevation_final))
+    cos_lat = cos(lat_rad)
+    sin_lat = sin(lat_rad)
+    sin_dec = sin(dec_rad)
+
+    if abs(cos_elev_final * cos_lat) < 1e-12:
+        azimuth = 180.0 if ha_rad < 0 else 0.0
+    else:
+        cos_az = (sin_dec - sin_elev_final * sin_lat) / (cos_elev_final * cos_lat)
+        cos_az = max(min(cos_az, 1.0), -1.0)
+        azimuth = degrees(acos(cos_az))
+        if hour_angle > 0:  # PM
+            azimuth = 360.0 - azimuth
+
+    horizon_position: Literal["above_horizon", "below_horizon"] = (
+        "above_horizon" if elevation_final > 0 else "below_horizon"
+    )
+    rising = elevation_final > 0 and hour_angle < 0
+
+    return {
+        "elevation": round(elevation_final, 2),
+        "azimuth": round(azimuth, 2),
+        "horizon_position": horizon_position,
+        "rising": rising
+    }
+
+# 🎁 FUNCIÓN BONUS: Todo junto (opcional)
+def all_sun_events(
+    latitude: float, longitude: float, date: datetime.date,
+    twilight_type: Literal["civil", "nautical", "astronomical"] = "civil",
+    elevation: float = 0.0,
+    timezone: datetime.timezone = datetime.timezone.utc,
+    with_refraction: bool = True
+) -> dict:
+    """🔥 Calcula TODOS los eventos solares del día."""
+    sr, ss = sunrise_sunset(latitude, longitude, date, elevation, timezone, with_refraction)
+    return {
+        "dawn": dawn(latitude, longitude, date, twilight_type, elevation, timezone, with_refraction),
+        "sunrise": sr,
+        "noon": noon(longitude, date, timezone),
+        "sunset": ss,
+        "dusk": dusk(latitude, longitude, date, twilight_type, elevation, timezone, with_refraction),
+        "midnight": midnight(longitude, date, timezone)
+    }

solarmoonpy-1.0.9/solarmoonpy/version.py

@@ -0,0 +1,2 @@
+# version.py
+__version__ = "1.0.9"

{solarmoonpy-1.0.1 → solarmoonpy-1.0.9}/solarmoonpy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: solarmoonpy
-Version: 1.0.1
+Version: 1.0.9
 Summary: Precise solar and lunar calculations for astronomical applications
 Author-email: figorr <jdcuartero@yahoo.es>
 License:                                  Apache License
@@ -221,6 +221,9 @@ License-File: LICENSE
 Dynamic: license-file
 
 # ☀️🌙 solarmoonpy
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+![Version](https://img.shields.io/pypi/v/solarmoonpy)
+
 Solar and moon calculations for Meteocat Home Assistant integration.
 
 **solarmoonpy** is a Python library that provides accurate calculations of solar and lunar positions, specifically designed to integrate with Home Assistant and Meteocat data. 
@@ -229,7 +232,7 @@ This project enables you to obtain information such as sunrise, sunset, moon pha
 
 ## 🚀 Features
 
-- ☀️ Solar position calculations (sunrise, sunset, zenith, etc.).
+- ☀️ Solar position calculations (sunrise, sunset, noon, etc.).
 - 🌙 Moon phase and position calculations.
 - Integration with meteorological data from Meteocat.
 - Compatible with Home Assistant for automations based on solar and lunar events.

solarmoonpy-1.0.1/solarmoonpy/version.py

@@ -1,2 +0,0 @@
-# version.py
-__version__ = "1.0.1"