0
# Utilities
1

2
Common utility functions and classes used throughout the astropy ecosystem including data downloading, metadata handling, and helper functions.
3

4
## Core Imports
5

6
```python
7
from astropy.utils.data import download_file, get_pkg_data_filename
8
from astropy.utils.decorators import deprecated, lazyproperty
9
from astropy.utils.console import ProgressBar
10
from astropy.utils.misc import isiterable
11
```
12

13
## Capabilities
14

15
### Data Management
16

17
Functions for downloading, caching, and managing data files.
18

19
```python { .api }
20
def download_file(remote_url, cache=True, show_progress=True, timeout=None):
21
    """
22
    Download a file from a remote URL.
23
    
24
    Parameters:
25
    - remote_url: URL of file to download
26
    - cache: whether to cache downloaded file
27
    - show_progress: whether to show progress bar
28
    - timeout: timeout for download
29
    
30
    Returns:
31
    str: path to downloaded file
32
    """
33

34
def get_pkg_data_filename(data_name, package=None, show_progress=True):
35
    """
36
    Get path to package data file.
37
    
38
    Parameters:
39
    - data_name: name of data file
40
    - package: package containing data
41
    - show_progress: show progress if downloading
42
    
43
    Returns:
44
    str: path to data file
45
    """
46

47
def data_dir():
48
    """Return the data directory for astropy."""
49

50
def cache_dir():
51
    """Return the cache directory for astropy."""
52

53
def clear_download_cache():
54
    """Clear the download cache."""
55
```
56

57
### Decorators
58

59
Decorator functions for common programming patterns.
60

61
```python { .api }
62
def deprecated(since, message='', name='', alternative='', pending=False):
63
    """
64
    Decorator to mark functions/classes as deprecated.
65
    
66
    Parameters:
67
    - since: version when deprecated
68
    - message: deprecation message
69
    - name: name of deprecated item
70
    - alternative: suggested alternative
71
    - pending: whether deprecation is pending
72
    """
73

74
def lazyproperty(func):
75
    """
76
    Decorator for lazy property evaluation.
77
    
78
    The property is computed only once and cached.
79
    """
80

81
def classproperty(func):
82
    """Decorator for class properties."""
83

84
def format_doc(*args, **kwargs):
85
    """Decorator to format docstrings."""
86
```
87

88
### Console Utilities
89

90
Utilities for console output and progress reporting.
91

92
```python { .api }
93
class ProgressBar:
94
    """
95
    Progress bar for long-running operations.
96
    
97
    Parameters:
98
    - total: total number of iterations
99
    - ipython_widget: use IPython widget if available
100
    """
101
    def __init__(self, total, ipython_widget=False): ...
102
    
103
    def update(self, value=None):
104
        """Update progress bar."""
105
    
106
    def close(self):
107
        """Close progress bar."""
108

109
def human_time(dt):
110
    """
111
    Format time duration in human-readable form.
112
    
113
    Parameters:
114
    - dt: time duration in seconds
115
    
116
    Returns:
117
    str: formatted duration
118
    """
119

120
def human_file_size(size, si=False):
121
    """
122
    Format file size in human-readable form.
123
    
124
    Parameters:
125
    - size: size in bytes
126
    - si: use SI units (1000) vs binary (1024)
127
    
128
    Returns:
129
    str: formatted size
130
    """
131
```
132

133
### Miscellaneous Utilities
134

135
Various utility functions for common tasks.
136

137
```python { .api }
138
def isiterable(obj):
139
    """
140
    Check if object is iterable.
141
    
142
    Parameters:
143
    - obj: object to check
144
    
145
    Returns:
146
    bool: True if iterable
147
    """
148

149
def silence():
150
    """Context manager to silence warnings."""
151

152
def find_api_page(obj):
153
    """
154
    Find API documentation page for object.
155
    
156
    Parameters:
157
    - obj: object to find documentation for
158
    
159
    Returns:
160
    str: URL of documentation page
161
    """
162

163
def resolve_name(name):
164
    """
165
    Resolve dotted name to object.
166
    
167
    Parameters:
168
    - name: dotted name string
169
    
170
    Returns:
171
    object: resolved object
172
    """
173

174
def indent(s, shift=1, width=4):
175
    """
176
    Indent a string.
177
    
178
    Parameters:
179
    - s: string to indent
180
    - shift: number of indentation levels
181
    - width: width of each indentation level
182
    
183
    Returns:
184
    str: indented string
185
    """
186
```
187

188
## Usage Examples
189

190
### Downloading Data
191

192
```python
193
from astropy.utils.data import download_file
194

195
# Download a file with caching
196
url = 'https://example.com/data.fits'
197
local_path = download_file(url, cache=True)
198
print(f'Downloaded to: {local_path}')
199
```
200

201
### Progress Bar
202

203
```python
204
from astropy.utils.console import ProgressBar
205
import time
206

207
# Show progress for long operation
208
with ProgressBar(100) as bar:
209
    for i in range(100):
210
        time.sleep(0.01)  # Simulate work
211
        bar.update(i + 1)
212
```
213

214
### Deprecation Warning
215

216
```python
217
from astropy.utils.decorators import deprecated
218

219
@deprecated('1.0', message='Use new_function instead')
220
def old_function():
221
    """This function is deprecated."""
222
    return "old result"
223

224
# Using deprecated function will show warning
225
result = old_function()
226
```
227

228
## Types
229

230
```python { .api }
231
# Utility types
232
ProgressBar = astropy.utils.console.ProgressBar
233
```