0
# Error Handling and Utilities
1

2
Error management, debugging utilities, and general-purpose functions for SPICE operations. These functions help manage error conditions and provide useful utilities for SPICE programming.
3

4
## Capabilities
5

6
### Error Status Functions
7

8
Check and manage SPICE error conditions.
9

10
```python { .api }
11
def failed() -> bool:
12
    """
13
    Check if a SPICE error has occurred.
14
    
15
    Returns:
16
    bool: True if SPICE error flag is set
17
    """
18

19
def reset() -> None:
20
    """
21
    Reset SPICE error status.
22
    
23
    Returns:
24
    None
25
    """
26

27
def getmsg(option: str, lenout: int) -> str:
28
    """
29
    Retrieve SPICE error message.
30
    
31
    Parameters:
32
    - option: str, message type ("SHORT", "EXPLAIN", "LONG")
33
    - lenout: int, maximum message length
34
    
35
    Returns:
36
    str: error message
37
    """
38
```
39

40
### Utility Functions
41

42
General-purpose utility functions.
43

44
```python { .api }
45
def exists(file: str) -> bool:
46
    """
47
    Test whether a file exists.
48
    
49
    Parameters:
50
    - file: str, file path
51
    
52
    Returns:
53
    bool: True if file exists
54
    """
55

56
def iswhsp(string: str) -> bool:
57
    """
58
    Test whether string is whitespace.
59
    
60
    Parameters:
61
    - string: str, input string
62
    
63
    Returns:
64
    bool: True if string contains only whitespace
65
    """
66
```
67

68
### Context Managers
69

70
Context managers for error handling control.
71

72
```python { .api }
73
def no_found_check():
74
    """
75
    Context manager to disable 'found' flag checking.
76
    
77
    Usage:
78
    with spice.no_found_check():
79
        # SPICE operations that might not find data
80
        pass
81
    """
82

83
def found_check():
84
    """
85
    Context manager to enable 'found' flag checking.
86
    
87
    Usage:
88
    with spice.found_check():
89
        # SPICE operations with strict error checking
90
        pass
91
    """
92
```
93

94
## Common Usage Patterns
95

96
### Basic Error Checking
97
```python
98
import spiceypy as spice
99

100
# Perform SPICE operation
101
spice.furnsh("nonexistent.bsp")
102

103
# Check for errors
104
if spice.failed():
105
    error_msg = spice.getmsg("SHORT", 40)
106
    print(f"SPICE error: {error_msg}")
107
    spice.reset()  # Clear error status
108
```
109

110
### Exception Handling
111
```python
112
from spiceypy.utils.exceptions import SpiceyError
113

114
try:
115
    # SPICE operations
116
    position, lt = spice.spkpos("MARS", et, "J2000", "NONE", "EARTH")
117
except SpiceyError as e:
118
    print(f"SPICE error occurred: {e.short}")
119
    print(f"Explanation: {e.explain}")
120
```