Adds type hints for improved code clarity

Adds type hints to function signatures and variable declarations across multiple modules.
This improves code readability, maintainability, and helps prevent potential type-related errors.

Author: WimDeMeester

pydeepskylog/config.py

@@ -2,6 +2,7 @@
 Configuration file for pydeepskylog package.
 Contains constants and configuration values used across the package.
 """
+from typing import List
 
 # Constants for contrast reserve calculations
 class ContrastReserveConfig:
@@ -13,19 +14,19 @@ class ContrastReserveConfig:
     # ANGLE is a 1D array of log10(angular size in arcminutes) values.
     # Each entry defines a grid point for the angular size axis in the LTC table.
     # Used for interpolation of threshold contrast as a function of object angular size.
-    ANGLE = [
+    ANGLE: List[float] = [
         -0.2255, 0.5563, 0.9859, 1.260,
         1.742, 2.083, 2.556,
     ]
 
-    ANGLE_SIZE = len(ANGLE)
+    ANGLE_SIZE: int = len(ANGLE)
 
     # LTC: Log Threshold Contrast Table
     # LTC is a 2D array where each row corresponds to a specific sky background brightness (integer values from 4 to 23).
     # Each column corresponds to a log10(angular size) value as defined in the ANGLE array.
     # LTC[sb][i] gives the log threshold contrast for sky brightness index sb and angle index i.
     # Used for interpolating the minimum contrast required for detection at given sky brightness and object size.
-    LTC = [
+    LTC: List[List[float]] = [
         [
             4, -0.3769, -1.8064, -2.3368, -2.4601,
             -2.5469, -2.5610, -2.5660,
@@ -124,4 +125,4 @@ class ContrastReserveConfig:
         ],
     ]
 
-    LTC_SIZE = len(LTC)
+    LTC_SIZE: int = len(LTC)

pydeepskylog/contrast_reserve.py

@@ -1,5 +1,6 @@
 import logging
 import math
+from typing import Optional, Tuple, List
 from pydeepskylog.config import ContrastReserveConfig
 
 
@@ -31,8 +32,8 @@ def surface_brightness(magnitude: float, object_diameter1: float, object_diamete
 
 def validate_contrast_reserve_inputs(
         sqm: float, telescope_diameter: float, magnification: float, 
-        surf_brightness: float, magnitude: float,
-        object_diameter1: float, object_diameter2: float
+        surf_brightness: Optional[float], magnitude: Optional[float],
+        object_diameter1: Optional[float], object_diameter2: Optional[float]
 ) -> None:
     """
     Validates the inputs for the contrast_reserve function.
@@ -85,7 +86,7 @@ def validate_contrast_reserve_inputs(
 def calculate_initial_parameters(
         sqm: float, telescope_diameter: float, 
         object_diameter1: float, object_diameter2: float
-) -> tuple:
+) -> Tuple[float, float, float, float]:
     """
     Calculates initial parameters needed for contrast reserve calculation.
     
@@ -119,8 +120,8 @@ def calculate_initial_parameters(
 
 
 def calculate_log_object_contrast(
-        sqm: float, surf_brightness: float, magnitude: float,
-        object_diameter1: float, object_diameter2: float
+        sqm: float, surf_brightness: Optional[float], magnitude: Optional[float],
+        object_diameter1: Optional[float], object_diameter2: Optional[float]
 ) -> float:
     """
     Calculates the log object contrast.
@@ -237,8 +238,8 @@ def calculate_threshold_contrast(sky_background_brightness: float, angular_size_
 
 
 def contrast_reserve(
-        sqm: float, telescope_diameter: float, magnification: float, surf_brightness: float, magnitude: float,
-        object_diameter1: float, object_diameter2: float
+        sqm: float, telescope_diameter: float, magnification: float, surf_brightness: Optional[float],
+        magnitude: Optional[float], object_diameter1: Optional[float], object_diameter2: Optional[float]
 ) -> float:
     """
     Calculate the contrast reserve
@@ -300,8 +301,9 @@ def contrast_reserve(
 
 
 def optimal_detection_magnification(
-        sqm: float, telescope_diameter: float, surf_brightness: float, magnitude: float, object_diameter1: float, object_diameter2: float,
-        magnifications: list) -> float:
+        sqm: float, telescope_diameter: float, surf_brightness: Optional[float],
+        magnitude: Optional[float], object_diameter1: Optional[float], object_diameter2: Optional[float],
+        magnifications: List[float]) -> float:
     """
     Calculate the best magnification to use for the object to detect it
 

pydeepskylog/deepskylog_interface.py

@@ -1,13 +1,14 @@
 import requests
 import time
+from typing import Dict, List, Any, Optional
 
-DSL_API_BASE_URL = "https://test.deepskylog.org/api/"  # Change this as needed
+DSL_API_BASE_URL: str = "https://test.deepskylog.org/api/"  # Change this as needed
 
 # Simple in-memory cache: {url: (timestamp, data)}
-_DSL_API_CACHE = {}
-_DSL_API_CACHE_TTL = 300  # seconds (5 minutes)
+_DSL_API_CACHE: Dict[str, tuple[float, Any]] = {}
+_DSL_API_CACHE_TTL: int = 300  # seconds (5 minutes)
 
-def dsl_instruments(username: str) -> dict:
+def dsl_instruments(username: str) -> Dict[str, Any]:
     """
     Get all defined instruments of a DeepskyLog user.
 
@@ -21,7 +22,7 @@ def dsl_instruments(username: str) -> dict:
     """
     return _dsl_api_call("instrument", username)
 
-def dsl_eyepieces(username: str) -> dict:
+def dsl_eyepieces(username: str) -> Dict[str, Any]:
     """
     Get all defined eyepieces of a DeepskyLog user.
 
@@ -35,7 +36,7 @@ def dsl_eyepieces(username: str) -> dict:
     """
     return _dsl_api_call("eyepieces", username)
 
-def dsl_lenses(username: str) -> dict:
+def dsl_lenses(username: str) -> Dict[str, Any]:
     """
     Get all defined lenses of a DeepskyLog user.
 
@@ -49,7 +50,7 @@ def dsl_lenses(username: str) -> dict:
     """
     return _dsl_api_call("lenses", username)
 
-def dsl_filters(username: str) -> dict:
+def dsl_filters(username: str) -> Dict[str, Any]:
     """
     Get all defined filters of a DeepskyLog user.
 
@@ -64,7 +65,7 @@ def dsl_filters(username: str) -> dict:
     return _dsl_api_call("filters", username)
 
 
-def calculate_magnifications(instrument: dict, eyepieces: dict) -> list:
+def calculate_magnifications(instrument: Dict[str, Any], eyepieces: List[Dict[str, Any]]) -> List[float]:
     """
     Calculate possible magnifications for a given telescope and eyepieces.
 
@@ -87,7 +88,7 @@ def calculate_magnifications(instrument: dict, eyepieces: dict) -> list:
     Returns:
         list: A list of possible magnifications for the telescope.
     """
-    magnifications = []
+    magnifications: List[float] = []
     # Check if the instrument has a fixed magnification
     if instrument["fixedMagnification"]:
         magnifications.append(instrument["fixedMagnification"])
@@ -105,7 +106,7 @@ def convert_instrument_type_to_int(instrument_type: str) -> int:
     :param instrument_type: The instrument type as a string.
     :return: The instrument type as an integer.
     """
-    instrument_types = {
+    instrument_types: Dict[str, int] = {
         "Naked Eye": 0,
         "Binoculars": 1,
         "Refractor": 2,
@@ -126,7 +127,7 @@ def convert_instrument_type_to_string(instrument_type: int) -> str:
     :param instrument_type: The instrument type as an integer.
     :return: The instrument type as a string.
     """
-    instrument_types = {
+    instrument_types: Dict[str, int] = {
         0: "Naked Eye",
         1: "Binoculars",
         2: "Refractor",
@@ -141,7 +142,7 @@ def convert_instrument_type_to_string(instrument_type: int) -> str:
 
     return instrument_types[instrument_type]
 
-def _dsl_api_call(api_call: str, username: str) -> dict:
+def _dsl_api_call(api_call: str, username: str) -> Dict[str, Any]:
     """
     Make an API call to the DeepskyLog system.
 
@@ -155,8 +156,8 @@ def _dsl_api_call(api_call: str, username: str) -> dict:
     Returns:
         dict: The response from the API call, parsed as a JSON dictionary.
     """
-    api_url = f"{DSL_API_BASE_URL}{api_call}/{username}"
-    now = time.time()
+    api_url: str = f"{DSL_API_BASE_URL}{api_call}/{username}"
+    now: float = time.time()
 
     # Check cache
     cache_entry = _DSL_API_CACHE.get(api_url)