Skip to content

API Reference: Utils Module

utils

Utility functions for the ndastro_engine package.

This module provides: - get_app_data_dir: Get the application data directory for the given app name.

dd2dms(decimal_degrees)

Convert decimal degrees to degrees, minutes, and seconds.

Parameters:

Name Type Description Default
decimal_degrees float

The angle in decimal degrees.

 required

Returns:

Type Description
tuple[int, int, float, int]

tuple[int, int, float, int]: A tuple containing degrees, minutes, seconds, and sign.
Source code in .venv/lib/python3.11/site-packages/ndastro_engine/utils.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
def dd2dms(decimal_degrees: float) -> tuple[int, int, float, int]:
    """Convert decimal degrees to degrees, minutes, and seconds.

    Args:
        decimal_degrees (float): The angle in decimal degrees.

    Returns:
        tuple[int, int, float, int]: A tuple containing degrees, minutes, seconds, and sign.

    """
    sign = 1 if decimal_degrees >= 0 else -1
    abs_degrees = abs(decimal_degrees)
    degrees = int(abs_degrees)
    minutes_full = (abs_degrees - degrees) * 60
    minutes = int(minutes_full)
    seconds = (minutes_full - minutes) * 60
    return degrees, minutes, seconds, sign

dd2dmsstr(decimal_degrees)

Convert decimal degrees to a formatted DMS string.

Parameters:

Name Type Description Default
decimal_degrees float

The angle in decimal degrees.

 required

Returns:

Name Type Description
str str

The angle in DMS format as a string.
Source code in .venv/lib/python3.11/site-packages/ndastro_engine/utils.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def dd2dmsstr(decimal_degrees: float) -> str:
    """Convert decimal degrees to a formatted DMS string.

    Args:
        decimal_degrees (float): The angle in decimal degrees.

    Returns:
        str: The angle in DMS format as a string.

    """
    degrees, minutes, seconds, sign = dd2dms(decimal_degrees)
    sign_str = "" if sign >= 0 else "-"
    return f"{sign_str}{degrees}° {minutes}' {seconds:.2f}\""

dms2dd(degrees, minutes, seconds, sign=1)

Convert degrees, minutes, and seconds to decimal degrees.

Parameters:

Name Type Description Default
degrees int

The degrees component.

 required
minutes int

The minutes component.

 required
seconds float

The seconds component.

 required
sign int

The sign of the angle. Defaults to 1 (positive).

 1

Returns:

Name Type Description
float float

The angle in decimal degrees.
Source code in .venv/lib/python3.11/site-packages/ndastro_engine/utils.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
def dms2dd(degrees: int, minutes: int, seconds: float, sign: int = 1) -> float:
    """Convert degrees, minutes, and seconds to decimal degrees.

    Args:
        degrees (int): The degrees component.
        minutes (int): The minutes component.
        seconds (float): The seconds component.
        sign (int, optional): The sign of the angle. Defaults to 1 (positive).

    Returns:
        float: The angle in decimal degrees.

    """
    decimal_degrees = abs(degrees) + minutes / 60 + seconds / 3600
    return sign * decimal_degrees

get_app_data_dir(appname)

Get the application data directory for the given app name.

Parameters

appname : str Name of the application.

Returns

Path Path to the application data directory.

Source code in .venv/lib/python3.11/site-packages/ndastro_engine/utils.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
def get_app_data_dir(appname: str) -> Path:
    """Get the application data directory for the given app name.

    Parameters
    ----------
    appname : str
        Name of the application.

    Returns
    -------
    Path
        Path to the application data directory.

    """
    home = Path.home()
    if sys.platform == OS_WIN:
        return home / "AppData/Local" / appname

    if sys.platform == OS_MAC:
        return home / "Library/Application Support" / appname

    # Linux and other Unix-like systems (uses XDG spec fallback)
    data_home = os.getenv("XDG_DATA_HOME", "~/.local/share")
    return Path(data_home).expanduser() / appname

normalize_degree(degree)

Normalize the degree to be within 0-360.

Parameters:

Name Type Description Default
degree float

The degree to normalize.

 required

Returns:

Name Type Description
float float

The normalized degree.
Source code in .venv/lib/python3.11/site-packages/ndastro_engine/utils.py 
40
41
42
43
44
45
46
47
48
49
50
def normalize_degree(degree: float) -> float:
    """Normalize the degree to be within 0-360.

    Args:
        degree (float): The degree to normalize.

    Returns:
        float: The normalized degree.

    """
    return (degree % DEGREE_MAX + DEGREE_MAX) % DEGREE_MAX