mpc-designation 1.0.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,138 @@
1
+ """
2
+ MPC Designation Converter - Convert between packed and unpacked MPC designations
3
+
4
+ Usage:
5
+ from mpc_designation import convert_simple, pack, unpack
6
+
7
+ # Auto-detect and flip format
8
+ result = convert_simple('1995 XA') # Returns 'J95X00A'
9
+ result = convert_simple('J95X00A') # Returns '1995 XA'
10
+
11
+ # Ensure specific format (idempotent)
12
+ packed = pack('1995 XA') # Returns 'J95X00A'
13
+ packed = pack('J95X00A') # Returns 'J95X00A' (already packed)
14
+ unpacked = unpack('J95X00A') # Returns '1995 XA'
15
+ unpacked = unpack('1995 XA') # Returns '1995 XA' (already unpacked)
16
+
17
+ # Validation without exceptions
18
+ if is_valid_designation(user_input):
19
+ result = convert_simple(user_input)
20
+
21
+ # Category-specific (for known input types)
22
+ packed = pack_asteroid('1995 XA')
23
+ packed = pack_comet('C/1995 O1')
24
+
25
+ # Batch processing (parallel, for large datasets)
26
+ from mpc_designation.batch import convert_batch, pack_batch, unpack_batch
27
+ results = convert_batch(designations, workers=4)
28
+ """
29
+
30
+ from .mpc_designation import (
31
+ # Core conversion functions
32
+ convert,
33
+ convert_simple,
34
+
35
+ # High-level pack/unpack (auto-detect, idempotent)
36
+ pack,
37
+ unpack,
38
+
39
+ # Category-specific pack/unpack
40
+ pack_asteroid,
41
+ unpack_asteroid,
42
+ pack_comet,
43
+ unpack_comet,
44
+ pack_satellite_designation,
45
+ unpack_satellite_designation,
46
+
47
+ # Validation and hygiene
48
+ detect_format,
49
+ is_valid_designation,
50
+ is_valid_mpc_chars,
51
+ sanitize,
52
+
53
+ # Low-level functions (for advanced use)
54
+ pack_permanent,
55
+ unpack_permanent,
56
+ pack_provisional,
57
+ unpack_provisional,
58
+ pack_comet_numbered,
59
+ unpack_comet_numbered,
60
+ pack_comet_provisional,
61
+ unpack_comet_provisional,
62
+ pack_comet_full,
63
+ unpack_comet_full,
64
+ pack_satellite,
65
+ unpack_satellite,
66
+
67
+ # Helper functions
68
+ to_report_format,
69
+ from_report_format,
70
+ has_fragment,
71
+ get_fragment,
72
+ get_parent,
73
+ designations_equal,
74
+
75
+ # Exception class
76
+ MPCDesignationError,
77
+ )
78
+
79
+ __all__ = [
80
+ # Core
81
+ 'convert',
82
+ 'convert_simple',
83
+
84
+ # High-level
85
+ 'pack',
86
+ 'unpack',
87
+
88
+ # Category-specific
89
+ 'pack_asteroid',
90
+ 'unpack_asteroid',
91
+ 'pack_comet',
92
+ 'unpack_comet',
93
+ 'pack_satellite_designation',
94
+ 'unpack_satellite_designation',
95
+
96
+ # Validation
97
+ 'detect_format',
98
+ 'is_valid_designation',
99
+ 'is_valid_mpc_chars',
100
+ 'sanitize',
101
+
102
+ # Low-level
103
+ 'pack_permanent',
104
+ 'unpack_permanent',
105
+ 'pack_provisional',
106
+ 'unpack_provisional',
107
+ 'pack_comet_numbered',
108
+ 'unpack_comet_numbered',
109
+ 'pack_comet_provisional',
110
+ 'unpack_comet_provisional',
111
+ 'pack_comet_full',
112
+ 'unpack_comet_full',
113
+ 'pack_satellite',
114
+ 'unpack_satellite',
115
+
116
+ # Helper functions
117
+ 'to_report_format',
118
+ 'from_report_format',
119
+ 'has_fragment',
120
+ 'get_fragment',
121
+ 'get_parent',
122
+ 'designations_equal',
123
+
124
+ # Exception
125
+ 'MPCDesignationError',
126
+ ]
127
+
128
+ # Version: use importlib.metadata for installed packages, fallback for development
129
+ def _get_version():
130
+ """Get package version from installed metadata or fallback."""
131
+ try:
132
+ from importlib.metadata import version
133
+ return version("mpc-designation")
134
+ except Exception:
135
+ # Fallback for development or if package not installed
136
+ return "1.0.0"
137
+
138
+ __version__ = _get_version()
@@ -0,0 +1,304 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ batch.py - Parallel batch processing for MPC designation conversions.
4
+
5
+ This module provides parallel processing capabilities for converting
6
+ large batches of designations. It uses Python's multiprocessing to
7
+ distribute work across CPU cores.
8
+
9
+ Usage:
10
+ from mpc_designation.batch import convert_batch, pack_batch, unpack_batch
11
+
12
+ # Convert a list of designations in parallel
13
+ results = convert_batch(designations, workers=4)
14
+
15
+ # Pack all designations
16
+ packed = pack_batch(designations, workers=4)
17
+
18
+ # Unpack all designations
19
+ unpacked = unpack_batch(designations, workers=4)
20
+
21
+ The batch functions automatically choose optimal chunk sizes and worker
22
+ counts based on input size. For small batches (< 1000), single-threaded
23
+ processing may be faster due to multiprocessing overhead.
24
+ """
25
+
26
+ import os
27
+ import multiprocessing as mp
28
+ from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor
29
+ from typing import List, Optional, Union, Callable
30
+ from functools import partial
31
+
32
+ # Import core functions
33
+ from .mpc_designation import (
34
+ convert_simple,
35
+ pack,
36
+ unpack,
37
+ MPCDesignationError
38
+ )
39
+
40
+
41
+ def _get_default_workers() -> int:
42
+ """Get default number of workers (CPU count, max 8)."""
43
+ return min(os.cpu_count() or 4, 8)
44
+
45
+
46
+ def _chunk_list(lst: List, chunk_size: int) -> List[List]:
47
+ """Split a list into chunks of specified size."""
48
+ return [lst[i:i + chunk_size] for i in range(0, len(lst), chunk_size)]
49
+
50
+
51
+ def _process_chunk_convert(chunk: List[str]) -> List[str]:
52
+ """Process a chunk of designations with convert_simple."""
53
+ return [convert_simple(d) for d in chunk]
54
+
55
+
56
+ def _process_chunk_pack(chunk: List[str]) -> List[str]:
57
+ """Process a chunk of designations with pack."""
58
+ return [pack(d) for d in chunk]
59
+
60
+
61
+ def _process_chunk_unpack(chunk: List[str]) -> List[str]:
62
+ """Process a chunk of designations with unpack."""
63
+ return [unpack(d) for d in chunk]
64
+
65
+
66
+ def _process_chunk_with_errors(chunk: List[str], func: Callable) -> List[Union[str, None]]:
67
+ """Process a chunk, returning None for errors instead of raising."""
68
+ results = []
69
+ for d in chunk:
70
+ try:
71
+ results.append(func(d))
72
+ except MPCDesignationError:
73
+ results.append(None)
74
+ return results
75
+
76
+
77
+ def convert_batch(
78
+ designations: List[str],
79
+ workers: Optional[int] = None,
80
+ chunk_size: Optional[int] = None,
81
+ ignore_errors: bool = False
82
+ ) -> List[str]:
83
+ """
84
+ Convert a batch of designations in parallel.
85
+
86
+ Each designation is converted between packed and unpacked formats
87
+ (auto-detects direction).
88
+
89
+ Args:
90
+ designations: List of designations to convert
91
+ workers: Number of parallel workers (default: CPU count, max 8)
92
+ chunk_size: Items per chunk (default: auto-calculated)
93
+ ignore_errors: If True, return None for invalid designations
94
+ instead of raising an exception
95
+
96
+ Returns:
97
+ List of converted designations (same order as input)
98
+
99
+ Raises:
100
+ MPCDesignationError: If any designation is invalid (unless ignore_errors=True)
101
+
102
+ Example:
103
+ >>> results = convert_batch(["1995 XA", "00001", "1P"])
104
+ >>> print(results)
105
+ ['J95X00A', '1', '0001P']
106
+ """
107
+ n = len(designations)
108
+
109
+ # For small batches, single-threaded is faster
110
+ if n < 1000:
111
+ if ignore_errors:
112
+ return [
113
+ convert_simple(d) if d else None
114
+ for d in designations
115
+ for _ in [None] # trick to catch errors
116
+ ]
117
+ return [convert_simple(d) for d in designations]
118
+
119
+ # Determine workers and chunk size
120
+ if workers is None:
121
+ workers = _get_default_workers()
122
+
123
+ if chunk_size is None:
124
+ # Aim for ~1000-5000 items per chunk, at least workers*2 chunks
125
+ chunk_size = max(1000, min(5000, n // (workers * 2)))
126
+
127
+ chunks = _chunk_list(designations, chunk_size)
128
+
129
+ # Use ProcessPoolExecutor for CPU-bound work
130
+ with ProcessPoolExecutor(max_workers=workers) as executor:
131
+ if ignore_errors:
132
+ chunk_results = list(executor.map(
133
+ partial(_process_chunk_with_errors, func=convert_simple),
134
+ chunks
135
+ ))
136
+ else:
137
+ chunk_results = list(executor.map(_process_chunk_convert, chunks))
138
+
139
+ # Flatten results
140
+ results = []
141
+ for chunk_result in chunk_results:
142
+ results.extend(chunk_result)
143
+
144
+ return results
145
+
146
+
147
+ def pack_batch(
148
+ designations: List[str],
149
+ workers: Optional[int] = None,
150
+ chunk_size: Optional[int] = None,
151
+ ignore_errors: bool = False
152
+ ) -> List[str]:
153
+ """
154
+ Pack a batch of designations in parallel.
155
+
156
+ Ensures all designations are in packed format.
157
+
158
+ Args:
159
+ designations: List of designations to pack
160
+ workers: Number of parallel workers (default: CPU count, max 8)
161
+ chunk_size: Items per chunk (default: auto-calculated)
162
+ ignore_errors: If True, return None for invalid designations
163
+
164
+ Returns:
165
+ List of packed designations (same order as input)
166
+
167
+ Example:
168
+ >>> packed = pack_batch(["1995 XA", "1", "C/1995 O1"])
169
+ >>> print(packed)
170
+ ['J95X00A', '00001', 'CJ95O010']
171
+ """
172
+ n = len(designations)
173
+
174
+ if n < 1000:
175
+ if ignore_errors:
176
+ results = []
177
+ for d in designations:
178
+ try:
179
+ results.append(pack(d))
180
+ except MPCDesignationError:
181
+ results.append(None)
182
+ return results
183
+ return [pack(d) for d in designations]
184
+
185
+ if workers is None:
186
+ workers = _get_default_workers()
187
+
188
+ if chunk_size is None:
189
+ chunk_size = max(1000, min(5000, n // (workers * 2)))
190
+
191
+ chunks = _chunk_list(designations, chunk_size)
192
+
193
+ with ProcessPoolExecutor(max_workers=workers) as executor:
194
+ if ignore_errors:
195
+ chunk_results = list(executor.map(
196
+ partial(_process_chunk_with_errors, func=pack),
197
+ chunks
198
+ ))
199
+ else:
200
+ chunk_results = list(executor.map(_process_chunk_pack, chunks))
201
+
202
+ results = []
203
+ for chunk_result in chunk_results:
204
+ results.extend(chunk_result)
205
+
206
+ return results
207
+
208
+
209
+ def unpack_batch(
210
+ designations: List[str],
211
+ workers: Optional[int] = None,
212
+ chunk_size: Optional[int] = None,
213
+ ignore_errors: bool = False
214
+ ) -> List[str]:
215
+ """
216
+ Unpack a batch of designations in parallel.
217
+
218
+ Ensures all designations are in unpacked (human-readable) format.
219
+
220
+ Args:
221
+ designations: List of designations to unpack
222
+ workers: Number of parallel workers (default: CPU count, max 8)
223
+ chunk_size: Items per chunk (default: auto-calculated)
224
+ ignore_errors: If True, return None for invalid designations
225
+
226
+ Returns:
227
+ List of unpacked designations (same order as input)
228
+
229
+ Example:
230
+ >>> unpacked = unpack_batch(["J95X00A", "00001", "CJ95O010"])
231
+ >>> print(unpacked)
232
+ ['1995 XA', '1', 'C/1995 O1']
233
+ """
234
+ n = len(designations)
235
+
236
+ if n < 1000:
237
+ if ignore_errors:
238
+ results = []
239
+ for d in designations:
240
+ try:
241
+ results.append(unpack(d))
242
+ except MPCDesignationError:
243
+ results.append(None)
244
+ return results
245
+ return [unpack(d) for d in designations]
246
+
247
+ if workers is None:
248
+ workers = _get_default_workers()
249
+
250
+ if chunk_size is None:
251
+ chunk_size = max(1000, min(5000, n // (workers * 2)))
252
+
253
+ chunks = _chunk_list(designations, chunk_size)
254
+
255
+ with ProcessPoolExecutor(max_workers=workers) as executor:
256
+ if ignore_errors:
257
+ chunk_results = list(executor.map(
258
+ partial(_process_chunk_with_errors, func=unpack),
259
+ chunks
260
+ ))
261
+ else:
262
+ chunk_results = list(executor.map(_process_chunk_unpack, chunks))
263
+
264
+ results = []
265
+ for chunk_result in chunk_results:
266
+ results.extend(chunk_result)
267
+
268
+ return results
269
+
270
+
271
+ # Thread-based alternatives (useful when GIL is released by I/O)
272
+ def convert_batch_threaded(
273
+ designations: List[str],
274
+ workers: Optional[int] = None,
275
+ chunk_size: Optional[int] = None
276
+ ) -> List[str]:
277
+ """
278
+ Convert a batch using threads instead of processes.
279
+
280
+ Generally slower than process-based for CPU-bound work, but useful
281
+ when process spawning overhead is significant (small batches) or
282
+ when running in environments that don't support multiprocessing.
283
+ """
284
+ n = len(designations)
285
+
286
+ if n < 500:
287
+ return [convert_simple(d) for d in designations]
288
+
289
+ if workers is None:
290
+ workers = _get_default_workers()
291
+
292
+ if chunk_size is None:
293
+ chunk_size = max(500, n // (workers * 2))
294
+
295
+ chunks = _chunk_list(designations, chunk_size)
296
+
297
+ with ThreadPoolExecutor(max_workers=workers) as executor:
298
+ chunk_results = list(executor.map(_process_chunk_convert, chunks))
299
+
300
+ results = []
301
+ for chunk_result in chunk_results:
302
+ results.extend(chunk_result)
303
+
304
+ return results