API Reference

pydeepskylog.bortle_to_nelm(bortle, fst_offset=0.0)

Convert Bortle scale value to Naked Eye Limiting Magnitude (NELM).

This function maps a given Bortle scale class (a qualitative measure of night sky darkness) to a typical Naked Eye Limiting Magnitude (NELM) value, optionally applying an observer-specific offset. The mapping uses a lookup table based on observational standards.

Parameters:

  • bortle (int) – The Bortle scale value (1 to 9), where 1 indicates the darkest skies and 9 the brightest.

  • fst_offset (float, optional) – Observer-specific offset to adjust the NELM value. Defaults to 0.0.

Returns:

Estimated NELM value (maximum faintness visible to the naked eye).

Return type:

float

Raises:

InvalidParameterError – If the Bortle value is out of the valid range (1 to 9) or if parameters are invalid.

Example

>>> nelm = bortle_to_nelm(4)
>>> print(nelm)
pydeepskylog.bortle_to_sqm(bortle)

Convert Bortle scale value to Sky Quality Meter (SQM) value.

This function maps a given Bortle scale class (a qualitative measure of night sky darkness) to a typical Sky Quality Meter (SQM) value, representing sky brightness in magnitudes per square arcsecond. The mapping uses a lookup table based on observational standards.

Parameters:

bortle (int) – The Bortle scale value (1 to 9), where 1 indicates the darkest skies and 9 the brightest.

Returns:

Estimated SQM value (sky brightness in mag/arcsec²).

Return type:

float

Raises:

InvalidParameterError – If the Bortle value is out of the valid range (1 to 9).

Example

>>> sqm = bortle_to_sqm(4)
>>> print(sqm)
pydeepskylog.calculate_magnifications(instrument, eyepieces)

Compute all possible magnifications for a given telescope (instrument) and a list of eyepieces.

This function determines the set of magnifications achievable with the provided telescope and eyepieces. If the instrument specifies a fixed magnification (e.g., for binoculars), that value is returned as a single-item list. Otherwise, the function calculates the magnification for each active eyepiece using the formula:

magnification = (telescope diameter) * (focal ratio) / (eyepiece focal length in mm)

Only eyepieces marked as active (eyepieceactive is True) are considered.

Parameters:

  • instrument (Dict[str, Any]) – Dictionary with telescope specifications. Expected keys: - “fixedMagnification” (float or None): Fixed magnification, if applicable. - “diameter” (float): Telescope diameter (typically in mm). - “fd” (float): Telescope focal ratio (focal length / diameter).

  • eyepieces (List[Dict[str, Any]]) – List of eyepiece dictionaries. Each should have: - “eyepieceactive” (bool): Whether the eyepiece is active. - “focal_length_mm” (float): Eyepiece focal length in millimeters.

Returns:

List of possible magnifications for the telescope and eyepieces.

Return type:

List[float]

Example

>>> mags = calculate_magnifications(instrument, eyepieces)
>>> print(mags)
pydeepskylog.contrast_reserve(sqm, telescope_diameter, magnification, surf_brightness, magnitude, object_diameter1, object_diameter2)

Calculate the contrast reserve for visual detection of an astronomical object.

The contrast reserve quantifies how much the object’s contrast exceeds the minimum threshold required for detection, based on the observer’s sky brightness, telescope, magnification, and object properties.

The calculation involves:

  1. Computing the object’s log contrast relative to the sky background, using either its surface brightness or integrated magnitude and size.

  2. Estimating the sky background brightness and the object’s angular size at the given magnification.

  3. Interpolating the log threshold contrast from the Log Threshold Contrast (LTC) table, which models human visual detection limits as a function of sky brightness and object size.

  4. Subtracting the threshold from the object’s log contrast to yield the contrast reserve.

Interpretation of the result:

  • If contrast reserve < -0.2: Object is not visible.

  • -0.2 <= contrast reserve < 0.1: Questionable detection.

  • 0.1 <= contrast reserve < 0.35: Difficult.

  • 0.35 <= contrast reserve < 0.5: Quite difficult to see.

  • 0.5 <= contrast reserve < 1.0: Easy to see.

  • >= 1.0: Very easy to see.

Parameters:

  • sqm (float) – Sky Quality Meter reading (sky brightness) in magnitudes per square arcsecond.

  • telescope_diameter (float) – Diameter of the telescope in millimeters.

  • magnification (float) – Magnification used.

  • surf_brightness (Optional[float]) – Surface brightness of the object in magnitudes per square arcsecond.

  • magnitude (Optional[float]) – Integrated magnitude of the object (required if surface brightness is not given).

  • object_diameter1 (Optional[float]) – Major axis diameter of the object in arcseconds.

  • object_diameter2 (Optional[float]) – Minor axis diameter of the object in arcseconds.

Returns:

The contrast reserve (difference between object and threshold log contrast).

Return type:

float

Raises:

InvalidParameterError – If any parameter is missing or invalid.

Mathematical context:
  • Log object contrast is computed as:

    logC = -0.4 * (SB + 8.89 - SQM)

    or, if surface brightness is not given, SB is derived from magnitude and size.

  • Threshold contrast is interpolated from the LTC table using sky brightness and log10(angular size).

  • Contrast reserve = log object contrast - log threshold contrast.

pydeepskylog.convert_instrument_type_to_int(instrument_type)

Convert an instrument type string to its corresponding integer code.

This function maps a human-readable instrument type (e.g., “Refractor”, “Binoculars”) to an integer value as defined by the DeepskyLog system. The mapping is used for API communication and data storage consistency.

:param instrument_type : The instrument type as a string (e.g., “Refractor”, “Binoculars”). :type instrument_type : str

Returns:

The integer code corresponding to the instrument type.

Return type:

int

Raises:

KeyError – If the instrument type string is not recognized.

Parameters:

instrument_type (str)

Example

>>> convert_instrument_type_to_int\("Refractor"\)
2
pydeepskylog.convert_instrument_type_to_string(instrument_type)

Convert an instrument type integer code to its corresponding string representation.

This function maps an integer instrument type code (as used by the DeepskyLog system) to a human-readable instrument type string (e.g., “Refractor”, “Binoculars”). This mapping is used for displaying instrument types and for interpreting API data.

:param instrument_type : The instrument type code as an integer (e.g., 2 for “Refractor”, 1 for “Binoculars”). :type instrument_type : int

Returns:

The string representation of the instrument type.

Return type:

str

Raises:

KeyError – If the instrument type code is not recognized.

Parameters:

instrument_type (int)

Example

>>> convert_instrument_type_to_string\(2\)
'Refractor'
pydeepskylog.dsl_eyepieces(username)

Retrieve all defined eyepieces for a DeepskyLog user via the DeepskyLog API.

This function queries the DeepskyLog API for the specified user and returns a dictionary containing all eyepieces registered in their account. The data typically includes specifications such as focal length, apparent field of view, and whether the eyepiece is active.

Parameters:

username (str) – The DeepskyLog username whose eyepieces are to be retrieved.

Returns:

A dictionary mapping eyepiece IDs to their specification dictionaries, as returned by the DeepskyLog API.

Return type:

Dict[str, Any]

Raises:

Example

>>> eyepieces = dsl_eyepieces("astro_user")
>>> for ep_id, ep in eyepieces.items():
...     print(ep["name"], ep["focal_length_mm"])
pydeepskylog.dsl_filters(username)

Retrieve all defined filters for a DeepskyLog user via the DeepskyLog API.

This function queries the DeepskyLog API for the specified user and returns a dictionary containing all filters registered in their account. The data typically includes specifications such as filter type, bandpass, and other relevant properties.

Parameters:

username (str) – The DeepskyLog username whose filters are to be retrieved.

Returns:

A dictionary mapping filter IDs to their specification dictionaries, as returned by the DeepskyLog API.

Return type:

Dict[str, Any]

Raises:

Example

>>> filters = dsl_filters("astro_user")
>>> for filter_id, flt in filters.items():
...     print(flt["name"], flt["type"])
pydeepskylog.dsl_instruments(username)

Retrieve all defined astronomical instruments for a DeepskyLog user via the DeepskyLog API.

This function queries the DeepskyLog API for the specified user and returns a dictionary containing all telescopes and observing instruments registered in their account. The data typically includes specifications such as instrument type, diameter, focal length, and other relevant properties.

Parameters:

username (str) – The DeepskyLog username whose instruments are to be retrieved.

Returns:

A dictionary mapping instrument IDs to their specification dictionaries, as returned by the DeepskyLog API.

Return type:

Dict[str, Any]

Raises:

Example

>>> instruments = dsl_instruments("astro_user")
>>> for inst_id, inst in instruments.items():
...     print(inst["name"], inst["diameter"])
pydeepskylog.dsl_lenses(username)

Retrieve all defined lenses for a DeepskyLog user via the DeepskyLog API.

This function queries the DeepskyLog API for the specified user and returns a dictionary containing all lenses registered in their account. The data typically includes specifications such as lens type, focal length, and other relevant properties.

Parameters:

username (str) – The DeepskyLog username whose lenses are to be retrieved.

Returns:

A dictionary mapping lens IDs to their specification dictionaries, as returned by the DeepskyLog API.

Return type:

Dict[str, Any]

Raises:

Example

>>> lenses = dsl_lenses("astro_user")
>>> for lens_id, lens in lenses.items():
...     print(lens["name"], lens["focal_length_mm"])
pydeepskylog.nelm_to_bortle(nelm)

Convert Naked Eye Limiting Magnitude (NELM) to the Bortle scale value.

This function maps the limiting magnitude visible to the naked eye (NELM) to the corresponding Bortle scale class, which is a qualitative measure of night sky darkness. The mapping uses established threshold values based on observational standards and is valid for NELM values up to 6.7.

Parameters:

nelm (float) – Naked Eye Limiting Magnitude (maximum faintness visible to the naked eye).

Returns:

The Bortle scale value (1 to 9), where 1 indicates the darkest skies and 9 the brightest.

Return type:

int

Raises:

InvalidParameterError – If the NELM value is out of the valid range (0 to 6.7).

Example

>>> bortle = nelm_to_bortle(6.2)
>>> print(bortle)
pydeepskylog.nelm_to_sqm(nelm, fst_offset=0.0)

Convert Naked Eye Limiting Magnitude (NELM) to Sky Quality Meter (SQM) value.

This function estimates the sky brightness (SQM, in magnitudes per square arcsecond) from the limiting magnitude visible to the naked eye (NELM), optionally applying an observer-specific offset. The calculation is based on established astronomical formulas and is valid for NELM values up to 6.7.

The formula used is:

SQM = 21.58 - 5 * log10(10^(1.586 - (NELM + fst_offset)/5) - 1)

Parameters:

  • nelm (float) – Naked Eye Limiting Magnitude (maximum faintness visible to the naked eye).

  • fst_offset (float, optional) – Observer-specific offset to adjust the NELM value. Defaults to 0.0.

Returns:

Estimated SQM value (sky brightness in mag/arcsec²), capped at 22.0.

Return type:

float

Raises:

InvalidParameterError – If input values are out of range or result in invalid calculations.

Example

>>> sqm = nelm_to_sqm(6.2)
>>> print(sqm)
pydeepskylog.optimal_detection_magnification(sqm, telescope_diameter, surf_brightness, magnitude, object_diameter1, object_diameter2, magnifications)

Determine the optimal magnification for visually detecting an astronomical object.

This function evaluates a list of possible magnifications and selects the one that maximizes the contrast reserve, i.e., the difference between the object’s contrast and the minimum threshold required for detection. The calculation considers the observer’s sky brightness (SQM), telescope diameter, object properties, and available magnifications.

The process involves:

  1. For each magnification, compute the contrast reserve using the object’s surface brightness or integrated magnitude and size, the telescope’s parameters, and the sky background.

  2. The contrast reserve is calculated as the difference between the object’s log contrast and the threshold contrast interpolated from the Log Threshold Contrast (LTC) table.

  3. The magnification yielding the highest contrast reserve is returned as optimal for detection.

Parameters:

  • sqm (float) – Sky Quality Meter reading (sky brightness) in magnitudes per square arcsecond.

  • telescope_diameter (float) – Diameter of the telescope in millimeters.

  • surf_brightness (Optional[float]) – Surface brightness of the object in magnitudes per square arcsecond.

  • magnitude (Optional[float]) – Integrated magnitude of the object (required if surface brightness is not given).

  • object_diameter1 (Optional[float]) – Major axis diameter of the object in arcseconds.

  • object_diameter2 (Optional[float]) – Minor axis diameter of the object in arcseconds.

  • magnifications (List[float]) – List of available magnifications to evaluate.

Returns:

The magnification that provides the highest contrast reserve (i.e., optimal for detection).

Return type:

float

Raises:

InvalidParameterError – If any parameter is missing or invalid.

Mathematical context:

  • For each magnification, the function computes the contrast reserve using the contrast_reserve function.

  • The optimal magnification is the one that maximizes this value, improving the likelihood of visual detection.

pydeepskylog.sqm_to_bortle(sqm)

Convert Sky Quality Meter (SQM) value to the Bortle scale class.

This function maps the measured sky brightness (SQM, in magnitudes per square arcsecond) to the corresponding Bortle scale value, which qualitatively describes night sky darkness. The mapping uses established threshold values based on observational standards and is valid for SQM values up to 22.

Parameters:

sqm (float) – Sky Quality Meter value (sky brightness in mag/arcsec²).

Returns:

The Bortle scale value (1 to 9), where 1 indicates the darkest skies and 9 the brightest.

Return type:

int

Raises:

InvalidParameterError – If the SQM value is out of the valid range (0 to 22).

Example

>>> bortle = sqm_to_bortle(21.0)
>>> print(bortle)
pydeepskylog.sqm_to_nelm(sqm, fst_offset=0.0)

Convert Sky Quality Meter (SQM) value to Naked Eye Limiting Magnitude (NELM).

This function estimates the faintest star visible to the naked eye (NELM) from the measured sky brightness (SQM), optionally applying an observer-specific offset. The calculation is based on established astronomical formulas and is valid for SQM values up to 22.

The formula used is:

NELM = 7.93 - 5 * log10(1 + 10^(4.316 - SQM/5))

Parameters:

  • sqm (float) – Sky Quality Meter value (sky brightness in mag/arcsec²).

  • fst_offset (float, optional) – Observer-specific offset to adjust the NELM value. Defaults to 0.0.

Returns:

Estimated NELM value (maximum faintness visible to the naked eye).

Return type:

float

Raises:

InvalidParameterError – If input values are out of range or result in invalid calculations.

Example

>>> nelm = sqm_to_nelm(21.0)
>>> print(nelm)
pydeepskylog.surface_brightness(magnitude, object_diameter1, object_diameter2)

Calculate the surface brightness of an astronomical object. This is needed to calculate the contrast of the target.

Surface brightness (SB) is the brightness of an extended object per unit area, expressed in magnitudes per square arcsecond. It is calculated using the formula:

SB = m + 2.5 * log10(2827 * (D1 / 60) * (D2 / 60))

where:

  • m is the integrated magnitude of the object,

  • D1 and D2 are the major and minor axis diameters in arcseconds,

  • 2827 is the number of square arcseconds in one square arcminute.

This formula converts the total magnitude into a per-area brightness, which is important for visual detection thresholds.

Parameters:

  • magnitude (float) – Integrated magnitude of the object.

  • object_diameter1 (float) – Major axis diameter in arcseconds.

  • object_diameter2 (float) – Minor axis diameter in arcseconds.

Returns:

Surface brightness in magnitudes per square arcsecond.

Return type:

float

Raises:

InvalidParameterError – If any parameter is invalid.

Configuration file for pydeepskylog package. Contains constants and configuration values used across the package.

class pydeepskylog.config.ContrastReserveConfig

Bases: object

Configuration class for contrast reserve calculations. Contains constants used in the contrast_reserve.py module.

ANGLE: List[float] = [-0.2255, 0.5563, 0.9859, 1.26, 1.742, 2.083, 2.556]
ANGLE_SIZE: int = 7
LTC: List[List[float]] = [[4, -0.3769, -1.8064, -2.3368, -2.4601, -2.5469, -2.561, -2.566], [5, -0.3315, -1.7747, -2.3337, -2.4608, -2.5465, -2.5607, -2.5658], [6, -0.2682, -1.7345, -2.331, -2.4605, -2.5467, -2.5608, -2.5658], [7, -0.1982, -1.6851, -2.314, -2.4572, -2.5481, -2.5615, -2.5665], [8, -0.1238, -1.6252, -2.2791, -2.4462, -2.5463, -2.5597, -2.5646], [9, -0.0424, -1.5529, -2.2297, -2.4214, -2.5343, -2.5501, -2.5552], [10, 0.0498, -1.4655, -2.1659, -2.3763, -2.5047, -2.5269, -2.5333], [11, 0.1596, -1.3581, -2.081, -2.3036, -2.4499, -2.4823, -2.4937], [12, 0.2934, -1.2256, -1.9674, -2.1965, -2.3631, -2.4092, -2.4318], [13, 0.4557, -1.0673, -1.8186, -2.0531, -2.2445, -2.3083, -2.3491], [14, 0.65, -0.8841, -1.6292, -1.8741, -2.0989, -2.1848, -2.2505], [15, 0.8808, -0.6687, -1.3967, -1.6611, -1.9284, -2.0411, -2.1375], [16, 1.1558, -0.3952, -1.1264, -1.4176, -1.73, -1.8727, -2.0034], [17, 1.4822, -0.0419, -0.8243, -1.1475, -1.5021, -1.6768, -1.842], [18, 1.8559, 0.3458, -0.4924, -0.8561, -1.2661, -1.4721, -1.6624], [19, 2.2669, 0.696, -0.1315, -0.551, -1.0562, -1.2892, -1.4827], [20, 2.676, 1.088, 0.206, -0.321, -0.88, -1.137, -1.362], [21, 2.7766, 1.2065, 0.3467, -0.1377, -0.7361, -0.9964, -1.2439], [22, 2.9304, 1.3821, 0.5353, 0.0328, -0.5605, -0.8606, -1.1187], [23, 3.1634, 1.6107, 0.7708, 0.2531, -0.3895, -0.703, -0.9681], [24, 3.4643, 1.9034, 1.0338, 0.4943, -0.2033, -0.5259, -0.8288], [25, 3.8211, 2.2564, 1.3265, 0.7605, 0.0172, -0.2992, -0.6394], [26, 4.221, 2.632, 1.699, 1.132, 0.286, -0.051, -0.408], [27, 4.61, 3.066, 2.132, 1.585, 0.652, 0.241, -0.121]]
LTC_SIZE: int = 24
pydeepskylog.deepskylog_interface.calculate_magnifications(instrument, eyepieces)

Compute all possible magnifications for a given telescope (instrument) and a list of eyepieces.

This function determines the set of magnifications achievable with the provided telescope and eyepieces. If the instrument specifies a fixed magnification (e.g., for binoculars), that value is returned as a single-item list. Otherwise, the function calculates the magnification for each active eyepiece using the formula:

magnification = (telescope diameter) * (focal ratio) / (eyepiece focal length in mm)

Only eyepieces marked as active (eyepieceactive is True) are considered.

Parameters:

  • instrument (Dict[str, Any]) – Dictionary with telescope specifications. Expected keys: - “fixedMagnification” (float or None): Fixed magnification, if applicable. - “diameter” (float): Telescope diameter (typically in mm). - “fd” (float): Telescope focal ratio (focal length / diameter).

  • eyepieces (List[Dict[str, Any]]) – List of eyepiece dictionaries. Each should have: - “eyepieceactive” (bool): Whether the eyepiece is active. - “focal_length_mm” (float): Eyepiece focal length in millimeters.

Returns:

List of possible magnifications for the telescope and eyepieces.

Return type:

List[float]

Example

>>> mags = calculate_magnifications(instrument, eyepieces)
>>> print(mags)
pydeepskylog.deepskylog_interface.convert_instrument_type_to_int(instrument_type)

Convert an instrument type string to its corresponding integer code.

This function maps a human-readable instrument type (e.g., “Refractor”, “Binoculars”) to an integer value as defined by the DeepskyLog system. The mapping is used for API communication and data storage consistency.

:param instrument_type : The instrument type as a string (e.g., “Refractor”, “Binoculars”). :type instrument_type : str

Returns:

The integer code corresponding to the instrument type.

Return type:

int

Raises:

KeyError – If the instrument type string is not recognized.

Parameters:

instrument_type (str)

Example

>>> convert_instrument_type_to_int\("Refractor"\)
2
pydeepskylog.deepskylog_interface.convert_instrument_type_to_string(instrument_type)

Convert an instrument type integer code to its corresponding string representation.

This function maps an integer instrument type code (as used by the DeepskyLog system) to a human-readable instrument type string (e.g., “Refractor”, “Binoculars”). This mapping is used for displaying instrument types and for interpreting API data.

:param instrument_type : The instrument type code as an integer (e.g., 2 for “Refractor”, 1 for “Binoculars”). :type instrument_type : int

Returns:

The string representation of the instrument type.

Return type:

str

Raises:

KeyError – If the instrument type code is not recognized.

Parameters:

instrument_type (int)

Example

>>> convert_instrument_type_to_string\(2\)
'Refractor'
pydeepskylog.deepskylog_interface.dsl_eyepieces(username)

Retrieve all defined eyepieces for a DeepskyLog user via the DeepskyLog API.

This function queries the DeepskyLog API for the specified user and returns a dictionary containing all eyepieces registered in their account. The data typically includes specifications such as focal length, apparent field of view, and whether the eyepiece is active.

Parameters:

username (str) – The DeepskyLog username whose eyepieces are to be retrieved.

Returns:

A dictionary mapping eyepiece IDs to their specification dictionaries, as returned by the DeepskyLog API.

Return type:

Dict[str, Any]

Raises:

Example

>>> eyepieces = dsl_eyepieces("astro_user")
>>> for ep_id, ep in eyepieces.items():
...     print(ep["name"], ep["focal_length_mm"])
pydeepskylog.deepskylog_interface.dsl_filters(username)

Retrieve all defined filters for a DeepskyLog user via the DeepskyLog API.

This function queries the DeepskyLog API for the specified user and returns a dictionary containing all filters registered in their account. The data typically includes specifications such as filter type, bandpass, and other relevant properties.

Parameters:

username (str) – The DeepskyLog username whose filters are to be retrieved.

Returns:

A dictionary mapping filter IDs to their specification dictionaries, as returned by the DeepskyLog API.

Return type:

Dict[str, Any]

Raises:

Example

>>> filters = dsl_filters("astro_user")
>>> for filter_id, flt in filters.items():
...     print(flt["name"], flt["type"])
pydeepskylog.deepskylog_interface.dsl_instruments(username)

Retrieve all defined astronomical instruments for a DeepskyLog user via the DeepskyLog API.

This function queries the DeepskyLog API for the specified user and returns a dictionary containing all telescopes and observing instruments registered in their account. The data typically includes specifications such as instrument type, diameter, focal length, and other relevant properties.

Parameters:

username (str) – The DeepskyLog username whose instruments are to be retrieved.

Returns:

A dictionary mapping instrument IDs to their specification dictionaries, as returned by the DeepskyLog API.

Return type:

Dict[str, Any]

Raises:

Example

>>> instruments = dsl_instruments("astro_user")
>>> for inst_id, inst in instruments.items():
...     print(inst["name"], inst["diameter"])
pydeepskylog.deepskylog_interface.dsl_lenses(username)

Retrieve all defined lenses for a DeepskyLog user via the DeepskyLog API.

This function queries the DeepskyLog API for the specified user and returns a dictionary containing all lenses registered in their account. The data typically includes specifications such as lens type, focal length, and other relevant properties.

Parameters:

username (str) – The DeepskyLog username whose lenses are to be retrieved.

Returns:

A dictionary mapping lens IDs to their specification dictionaries, as returned by the DeepskyLog API.

Return type:

Dict[str, Any]

Raises:

Example

>>> lenses = dsl_lenses("astro_user")
>>> for lens_id, lens in lenses.items():
...     print(lens["name"], lens["focal_length_mm"])
pydeepskylog.deepskylog_interface.rate_limited(max_calls, period)
Parameters:

  • max_calls (int)

  • period (float)

exception pydeepskylog.exceptions.APIAuthenticationError

Bases: PyDeepSkyLogError

Raised when API authentication fails.

add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception pydeepskylog.exceptions.APIConnectionError

Bases: PyDeepSkyLogError

Raised when API connection fails.

add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception pydeepskylog.exceptions.APIResponseError

Bases: PyDeepSkyLogError

Raised for invalid or unexpected API responses.

add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception pydeepskylog.exceptions.APITimeoutError

Bases: PyDeepSkyLogError

Raised when API request times out.

add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception pydeepskylog.exceptions.InvalidParameterError

Bases: PyDeepSkyLogError

Raised for invalid function parameters.

add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception pydeepskylog.exceptions.PyDeepSkyLogError

Bases: Exception

Base exception for pydeepskylog errors.

add_note()

Exception.add_note(note) – add a note to the exception

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

Validation utilities for the pydeepskylog package.

This module provides helper functions to validate input parameters for various astronomical calculations and API interfaces. These functions ensure that values are of the correct type, within valid ranges, and meet specific requirements (e.g., positivity, sequence type). If validation fails, an InvalidParameterError is raised with a descriptive message.

Functions:

  • validate_number: Ensure a value is a number (int or float).

  • validate_positive: Ensure a value is a positive number.

  • validate_in_range: Ensure a value falls within a specified range.

  • validate_sequence: Ensure a value is a sequence of a specified type.

All validation errors are logged and raise InvalidParameterError exceptions.

pydeepskylog.validation.validate_in_range(value, name, min_value, max_value)

Validate that a value falls within a specified numeric range.

This function checks whether the provided value is a number (int or float) and whether it lies within the inclusive range defined by min_value and max_value. If the value is outside this range or not a valid number, an InvalidParameterError is raised with a descriptive message.

Parameters:

  • value (Any) – The value to validate.

  • name (str) – The name of the parameter (used in error messages).

  • min_value (float) – The minimum allowed value (inclusive).

  • max_value (float) – The maximum allowed value (inclusive).

Raises:

InvalidParameterError – If the value is not a number or is outside the specified range.

Return type:

None

Example

>>> validate_in_range(5.5, "Magnitude", 0, 10)
pydeepskylog.validation.validate_number(value, name, allow_none=False)

Validate that a value is a number (int or float).

This function checks whether the provided value is an integer or floating-point number. If allow_none is True, the function allows the value to be None and returns without error. If the value is not a valid number, an InvalidParameterError is raised with a descriptive message.

Parameters:

  • value (Any) – The value to validate.

  • name (str) – The name of the parameter (used in error messages).

  • allow_none (bool, optional) – Whether None is accepted as a valid value. Defaults to False.

Raises:

InvalidParameterError – If the value is not a number (int or float), or is None when not allowed.

Return type:

None

Example

>>> validate_number(5.2, "Magnitude")
>>> validate_number(None, "Surface brightness", allow_none=True)
pydeepskylog.validation.validate_positive(value, name, allow_none=False)

Validate that a value is a positive number (greater than zero).

This function checks whether the provided value is a positive integer or floating-point number. If allow_none is True, the function allows the value to be None and returns without error. If the value is not positive, or not a valid number, an InvalidParameterError is raised with a descriptive message.

Parameters:

  • value (Any) – The value to validate.

  • name (str) – The name of the parameter (used in error messages).

  • allow_none (bool, optional) – Whether None is accepted as a valid value. Defaults to False.

Raises:

InvalidParameterError – If the value is not a positive number, or is None when not allowed.

Return type:

None

Example

>>> validate_positive(10, "Telescope diameter")
>>> validate_positive(None, "Object size", allow_none=True)
pydeepskylog.validation.validate_sequence(seq, name, item_type=<class 'float'>)

Validate that a value is a sequence containing items of a specified type.

This function checks whether the provided value is a sequence (such as a list or tuple) and that each item in the sequence is of the specified type (default: float). If the value is not a sequence, or any item is not of the required type, an InvalidParameterError is raised with a descriptive message.

Parameters:

  • seq (Any) – The value to validate as a sequence.

  • name (str) – The name of the parameter (used in error messages).

  • item_type (type, optional) – The expected type of each item in the sequence. Defaults to float.

Raises:

InvalidParameterError – If the value is not a sequence or contains items of the wrong type.

Return type:

None

Example

>>> validate_sequence([1.0, 2.5, 3.7], "Magnification list")
>>> validate_sequence((1, 2, 3), "Integer sequence", item_type=int)