mpc-designation 1.0.1__tar.gz

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,116 @@
1
+ CC0 1.0 Universal
2
+
3
+ Statement of Purpose
4
+
5
+ The laws of most jurisdictions throughout the world automatically confer
6
+ exclusive Copyright and Related Rights (defined below) upon the creator and
7
+ subsequent owner(s) (each and all, an "owner") of an original work of
8
+ authorship and/or a database (each, a "Work").
9
+
10
+ Certain owners wish to permanently relinquish those rights to a Work for the
11
+ purpose of contributing to a commons of creative, cultural and scientific
12
+ works ("Commons") that the public can reliably and without fear of later
13
+ claims of infringement build upon, modify, incorporate in other works, reuse
14
+ and redistribute as freely as possible in any form whatsoever and for any
15
+ purposes, including without limitation commercial purposes. These owners may
16
+ contribute to the Commons to promote the ideal of a free culture and the
17
+ further production of creative, cultural and scientific works, or to gain
18
+ reputation or greater distribution for their Work in part through the use and
19
+ efforts of others.
20
+
21
+ For these and/or other purposes and motivations, and without any expectation
22
+ of additional consideration or compensation, the person associating CC0 with a
23
+ Work (the "Affirmer"), to the extent that he or she is an owner of Copyright
24
+ and Related Rights in the Work, voluntarily elects to apply CC0 to the Work
25
+ and publicly distribute the Work under its terms, with knowledge of his or her
26
+ Copyright and Related Rights in the Work and the meaning and intended legal
27
+ effect of CC0 on those rights.
28
+
29
+ 1. Copyright and Related Rights. A Work made available under CC0 may be
30
+ protected by copyright and related or neighboring rights ("Copyright and
31
+ Related Rights"). Copyright and Related Rights include, but are not limited
32
+ to, the following:
33
+
34
+ i. the right to reproduce, adapt, distribute, perform, display, communicate,
35
+ and translate a Work;
36
+
37
+ ii. moral rights retained by the original author(s) and/or performer(s);
38
+
39
+ iii. publicity and privacy rights pertaining to a person's image or likeness
40
+ depicted in a Work;
41
+
42
+ iv. rights protecting against unfair competition in regards to a Work,
43
+ subject to the limitations in paragraph 4(a), below;
44
+
45
+ v. rights protecting the extraction, dissemination, use and reuse of data in
46
+ a Work;
47
+
48
+ vi. database rights (such as those arising under Directive 96/9/EC of the
49
+ European Parliament and of the Council of 11 March 1996 on the legal
50
+ protection of databases, and under any national implementation thereof,
51
+ including any amended or successor version of such directive); and
52
+
53
+ vii. other similar, equivalent or corresponding rights throughout the world
54
+ based on applicable law or treaty, and any national implementations thereof.
55
+
56
+ 2. Waiver. To the greatest extent permitted by, but not in contravention of,
57
+ applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and
58
+ unconditionally waives, abandons, and surrenders all of Affirmer's Copyright
59
+ and Related Rights and associated claims and causes of action, whether now
60
+ known or unknown (including existing as well as future claims and causes of
61
+ action), in the Work (i) in all territories worldwide, (ii) for the maximum
62
+ duration provided by applicable law or treaty (including future time
63
+ extensions), (iii) in any current or future medium and for any number of
64
+ copies, and (iv) for any purpose whatsoever, including without limitation
65
+ commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes
66
+ the Waiver for the benefit of each member of the public at large and to the
67
+ detriment of Affirmer's heirs and successors, fully intending that such Waiver
68
+ shall not be subject to revocation, rescission, cancellation, termination, or
69
+ any other legal or equitable action to disrupt the quiet enjoyment of the Work
70
+ by the public as contemplated by Affirmer's express Statement of Purpose.
71
+
72
+ 3. Public License Fallback. Should any part of the Waiver for any reason be
73
+ judged legally invalid or ineffective under applicable law, then the Waiver
74
+ shall be preserved to the maximum extent permitted taking into account
75
+ Affirmer's express Statement of Purpose. In addition, to the extent the Waiver
76
+ is so judged Affirmer hereby grants to each affected person a royalty-free,
77
+ non transferable, non sublicensable, non exclusive, irrevocable and
78
+ unconditional license to exercise Affirmer's Copyright and Related Rights in
79
+ the Work (i) in all territories worldwide, (ii) for the maximum duration
80
+ provided by applicable law or treaty (including future time extensions), (iii)
81
+ in any current or future medium and for any number of copies, and (iv) for any
82
+ purpose whatsoever, including without limitation commercial, advertising or
83
+ promotional purposes (the "License"). The License shall be deemed effective as
84
+ of the date CC0 was applied by Affirmer to the Work. Should any part of the
85
+ License for any reason be judged legally invalid or ineffective under
86
+ applicable law, such partial invalidity or ineffectiveness shall not
87
+ invalidate the remainder of the License, and in such case Affirmer hereby
88
+ affirms that he or she will not (i) exercise any of his or her remaining
89
+ Copyright and Related Rights in the Work or (ii) assert any associated claims
90
+ and causes of action with respect to the Work, in either case contrary to
91
+ Affirmer's express Statement of Purpose.
92
+
93
+ 4. Limitations and Disclaimers.
94
+
95
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
96
+ surrendered, licensed or otherwise affected by this document.
97
+
98
+ b. Affirmer offers the Work as-is and makes no representations or warranties
99
+ of any kind concerning the Work, express, implied, statutory or otherwise,
100
+ including without limitation warranties of title, merchantability, fitness
101
+ for a particular purpose, non infringement, or the absence of latent or
102
+ other defects, accuracy, or the present or absence of errors, whether or not
103
+ discoverable, all to the greatest extent permissible under applicable law.
104
+
105
+ c. Affirmer disclaims responsibility for clearing rights of other persons
106
+ that may apply to the Work or any use thereof, including without limitation
107
+ any person's Copyright and Related Rights in the Work. Further, Affirmer
108
+ disclaims responsibility for obtaining any necessary consents, permissions
109
+ or other rights required for any use of the Work.
110
+
111
+ d. Affirmer understands and acknowledges that Creative Commons is not a
112
+ party to this document and has no duty or obligation with respect to this
113
+ CC0 or use of the Work.
114
+
115
+ For more information, please see
116
+ <http://creativecommons.org/publicdomain/zero/1.0/>
@@ -0,0 +1,2 @@
1
+ include LICENSE
2
+ include README.md
@@ -0,0 +1,373 @@
1
+ Metadata-Version: 2.4
2
+ Name: mpc-designation
3
+ Version: 1.0.1
4
+ Summary: Convert between packed and unpacked MPC (Minor Planet Center) designations
5
+ Author-email: Rob Seaman <rseaman@arizona.edu>
6
+ Maintainer-email: Rob Seaman <rseaman@arizona.edu>
7
+ License-Expression: CC0-1.0
8
+ Project-URL: Homepage, https://github.com/rlseaman/MPC_designations
9
+ Project-URL: Documentation, https://github.com/rlseaman/MPC_designations#readme
10
+ Project-URL: Repository, https://github.com/rlseaman/MPC_designations.git
11
+ Project-URL: Changelog, https://github.com/rlseaman/MPC_designations/blob/main/CHANGELOG.md
12
+ Project-URL: Issues, https://github.com/rlseaman/MPC_designations/issues
13
+ Keywords: astronomy,minor planet,asteroid,comet,MPC
14
+ Classifier: Development Status :: 5 - Production/Stable
15
+ Classifier: Intended Audience :: Science/Research
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.9
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3.14
23
+ Classifier: Topic :: Scientific/Engineering :: Astronomy
24
+ Requires-Python: >=3.9
25
+ Description-Content-Type: text/markdown
26
+ License-File: LICENSE
27
+ Dynamic: license-file
28
+
29
+ # MPC Designation Converter - Python Implementation
30
+
31
+ Python 3 library and CLI tool for converting between packed and unpacked MPC designations.
32
+
33
+ ## Quick Start
34
+
35
+ ```python
36
+ from mpc_designation import convert_simple
37
+
38
+ result = convert_simple('1995 XA') # Returns 'J95X00A'
39
+ result = convert_simple('J95X00A') # Returns '1995 XA'
40
+ ```
41
+
42
+ ## Installation
43
+
44
+ ### From PyPi
45
+
46
+ ```bash
47
+ pip install mpc-designation
48
+ ```
49
+
50
+ ### From Source
51
+
52
+ ```bash
53
+ cd python
54
+ pip install -e .
55
+ ```
56
+
57
+ Or simply copy `src/mpc_designation/` to your project.
58
+
59
+ ## CLI Usage
60
+
61
+ ```bash
62
+ # Single conversion
63
+ python -m mpc_designation '1995 XA'
64
+ # Output: J95X00A
65
+
66
+ # Multiple designations
67
+ python -m mpc_designation 1 '1995 XA' 'C/1995 O1'
68
+ # Output:
69
+ # 1 -> 00001
70
+ # 1995 XA -> J95X00A
71
+ # C/1995 O1 -> CJ95O010
72
+
73
+ # Verbose mode
74
+ python -m mpc_designation -v '1995 XA'
75
+ # Output:
76
+ # Input: 1995 XA
77
+ # Detected: unpacked format, provisional
78
+ # Action: packing to MPC compact form
79
+ # Output: J95X00A
80
+ ```
81
+
82
+ Or run directly:
83
+
84
+ ```bash
85
+ python src/mpc_designation/mpc_designation.py '1995 XA'
86
+ ```
87
+
88
+ ## Library Usage
89
+
90
+ ### Simple Conversion
91
+
92
+ ```python
93
+ from mpc_designation import convert_simple, MPCDesignationError
94
+
95
+ try:
96
+ packed = convert_simple('1995 XA') # Returns 'J95X00A'
97
+ unpacked = convert_simple('J95X00A') # Returns '1995 XA'
98
+ except MPCDesignationError as e:
99
+ print(f"Error: {e}")
100
+ ```
101
+
102
+ ### With Format Information
103
+
104
+ ```python
105
+ from mpc_designation import convert
106
+
107
+ result = convert('1995 XA')
108
+ print(result['input']) # '1995 XA'
109
+ print(result['output']) # 'J95X00A'
110
+ print(result['format']) # 'unpacked'
111
+ print(result['subtype']) # 'provisional asteroid'
112
+ ```
113
+
114
+ ### Format Detection
115
+
116
+ ```python
117
+ from mpc_designation import detect_format
118
+
119
+ info = detect_format('1995 XA')
120
+ print(info['format']) # 'unpacked'
121
+ print(info['type']) # 'provisional'
122
+ ```
123
+
124
+ ### Batch Processing
125
+
126
+ ```python
127
+ from mpc_designation import convert_simple, MPCDesignationError
128
+
129
+ designations = ['1', '1995 XA', 'C/1995 O1']
130
+ for des in designations:
131
+ try:
132
+ result = convert_simple(des)
133
+ print(f"{des} -> {result}")
134
+ except MPCDesignationError as e:
135
+ print(f"{des}: Error - {e}")
136
+ ```
137
+
138
+ ### Parallel Batch Processing (Large Datasets)
139
+
140
+ For processing millions of designations, use the parallel batch functions:
141
+
142
+ ```python
143
+ from mpc_designation.batch import convert_batch, pack_batch, unpack_batch
144
+
145
+ # Convert millions of designations in parallel
146
+ results = convert_batch(designations, workers=4)
147
+
148
+ # Pack all to compact format
149
+ packed = pack_batch(designations, workers=4)
150
+
151
+ # Unpack all to human-readable format
152
+ unpacked = unpack_batch(packed_designations, workers=4)
153
+
154
+ # Handle errors gracefully (returns None for invalid designations)
155
+ results = pack_batch(designations, workers=4, ignore_errors=True)
156
+ ```
157
+
158
+ Performance on 2M designations (8 workers): ~800K pack/sec, ~1.5M unpack/sec.
159
+
160
+ ## API Reference
161
+
162
+ ### Functions
163
+
164
+ #### `convert_simple(designation: str) -> str`
165
+
166
+ Convert a designation, returning just the result string.
167
+
168
+ - **Parameters:** `designation` - The MPC designation to convert
169
+ - **Returns:** The converted designation
170
+ - **Raises:** `MPCDesignationError` if the input is invalid
171
+
172
+ #### `convert(designation: str) -> dict`
173
+
174
+ Convert a designation, returning detailed information.
175
+
176
+ - **Parameters:** `designation` - The MPC designation to convert
177
+ - **Returns:** Dictionary with keys:
178
+ - `input`: Original input
179
+ - `output`: Converted designation
180
+ - `format`: 'packed' or 'unpacked'
181
+ - `subtype`: Human-readable description
182
+
183
+ #### `detect_format(designation: str) -> dict`
184
+
185
+ Detect the format of a designation without converting.
186
+
187
+ - **Parameters:** `designation` - The MPC designation to analyze
188
+ - **Returns:** Dictionary with format information
189
+
190
+ #### `to_report_format(minimal: str) -> str`
191
+
192
+ Convert minimal packed format to 12-character MPC report format.
193
+
194
+ - **Parameters:** `minimal` - Minimal packed designation (e.g., '0073Pa')
195
+ - **Returns:** 12-character report format (e.g., '0073P a')
196
+
197
+ #### `from_report_format(report: str) -> str`
198
+
199
+ Convert 12-character MPC report format to minimal packed format.
200
+
201
+ - **Parameters:** `report` - 12-character report format
202
+ - **Returns:** Minimal packed designation
203
+
204
+ #### `has_fragment(desig: str) -> bool`
205
+
206
+ Check if a designation has a comet fragment suffix.
207
+
208
+ - **Parameters:** `desig` - Designation to check (packed or unpacked)
209
+ - **Returns:** True if has fragment, False if not
210
+
211
+ #### `get_fragment(desig: str) -> str`
212
+
213
+ Extract the fragment suffix from a comet designation.
214
+
215
+ - **Parameters:** `desig` - Designation (packed or unpacked)
216
+ - **Returns:** Fragment in uppercase (e.g., 'A', 'AA'), or empty string
217
+
218
+ #### `get_parent(desig: str) -> str`
219
+
220
+ Get the parent comet designation without fragment suffix.
221
+
222
+ - **Parameters:** `desig` - Designation (packed or unpacked)
223
+ - **Returns:** Parent designation in same format as input
224
+
225
+ #### `designations_equal(desig1: str, desig2: str) -> bool`
226
+
227
+ Check if two designations refer to the same object.
228
+
229
+ - **Parameters:** `desig1`, `desig2` - Designations to compare
230
+ - **Returns:** True if same object, False if different
231
+
232
+ ### Exceptions
233
+
234
+ #### `MPCDesignationError`
235
+
236
+ Raised when a designation cannot be converted.
237
+
238
+ ```python
239
+ from mpc_designation import MPCDesignationError
240
+
241
+ try:
242
+ convert_simple('invalid')
243
+ except MPCDesignationError as e:
244
+ print(f"Invalid designation: {e}")
245
+ ```
246
+
247
+ ## Comet Fragment Handling
248
+
249
+ The library supports comet fragment designations:
250
+
251
+ ### Numbered Comets with Fragments
252
+
253
+ Numbered comets (like 73P) can have fragments:
254
+
255
+ ```python
256
+ convert_simple('73P-A') # Returns '0073Pa'
257
+ convert_simple('73P-AA') # Returns '0073Paa'
258
+ convert_simple('0073Pa') # Returns '73P-A'
259
+ convert_simple('0073Paa') # Returns '73P-AA'
260
+ ```
261
+
262
+ ### Provisional Comets with Fragments
263
+
264
+ Provisional comets can also have fragments:
265
+
266
+ ```python
267
+ convert_simple('P/1930 J1-A') # Returns 'PJ30J01a'
268
+ convert_simple('P/1930 J1-AA') # Returns 'PJ30J01aa'
269
+ convert_simple('PJ30J01aa') # Returns 'P/1930 J1-AA'
270
+ ```
271
+
272
+ Fragment letters include all A-Z (including I, per MPC data).
273
+
274
+ ## Helper Functions
275
+
276
+ ### Format Conversion (Minimal ↔ 12-Character Report Format)
277
+
278
+ Convert between minimal packed format and the 12-character MPC observation report format:
279
+
280
+ ```python
281
+ from mpc_designation import to_report_format, from_report_format
282
+
283
+ # Minimal to 12-char report format
284
+ report = to_report_format('0073Pa') # '0073P a'
285
+
286
+ # 12-char report format to minimal
287
+ minimal = from_report_format('0073P a') # '0073Pa'
288
+ ```
289
+
290
+ ### Fragment Extraction
291
+
292
+ ```python
293
+ from mpc_designation import has_fragment, get_fragment, get_parent
294
+
295
+ # Check if designation has a fragment
296
+ if has_fragment('73P-A'): # Returns True
297
+ # Extract fragment (uppercase)
298
+ frag = get_fragment('73P-A') # 'A'
299
+ frag = get_fragment('73P-AA') # 'AA'
300
+
301
+ # Get parent comet
302
+ parent = get_parent('73P-A') # '73P'
303
+ parent = get_parent('0073Pa') # '0073P'
304
+ ```
305
+
306
+ ### Designation Comparison
307
+
308
+ Compare designations across different formats:
309
+
310
+ ```python
311
+ from mpc_designation import designations_equal
312
+
313
+ # Same object, different formats
314
+ designations_equal('1995 XA', 'J95X00A') # Returns True
315
+ designations_equal('73P-A', '0073Pa') # Returns True
316
+
317
+ # Different objects
318
+ designations_equal('73P-A', '73P-B') # Returns False
319
+ ```
320
+
321
+ ## Pre-1925 Designations
322
+
323
+ For years before 1925, the library outputs A-prefix format per MPC convention:
324
+
325
+ ```python
326
+ convert_simple('I01A00A') # Returns 'A801 AA' (not '1801 AA')
327
+ convert_simple('J08C00J') # Returns 'A908 CJ' (not '1908 CJ')
328
+ convert_simple('A908 CJ') # Returns 'J08C00J'
329
+ ```
330
+
331
+ The A-prefix format is the MPC-assigned primary designation for pre-1925 objects.
332
+
333
+ ## Century Code Validation
334
+
335
+ The library validates century codes:
336
+
337
+ - **Asteroids**: Only I-L (years 1800-2199)
338
+ - **Comets**: A-L (years 1000-2199, including historical comets)
339
+
340
+ ```python
341
+ convert_simple('1800 AA') # Valid - minimum asteroid year
342
+ convert_simple('C/1014 C1') # Valid - historical comet from 1014 CE
343
+ convert_simple('1700 AA') # Error - year before 1800 for asteroids
344
+ ```
345
+
346
+ ## Testing
347
+
348
+ ```bash
349
+ # Run error handling tests (94 test cases)
350
+ python test/test_errors.py ../test-data/error_test_cases.csv
351
+
352
+ # Run fragment handling tests
353
+ python test/test_fragments.py
354
+
355
+ # Run helper function tests (77 test cases)
356
+ python test/test_helpers.py
357
+
358
+ # Run conversion tests (requires decompressing test data first)
359
+ gunzip -k ../test-data/prov_unpack_to_pack.csv.gz
360
+ python test/test_csv.py ../test-data/prov_unpack_to_pack.csv
361
+
362
+ # Run roundtrip tests (verifies pack(unpack(x)) == x and unpack(pack(x)) == x)
363
+ python test/test_roundtrip.py ../test-data/prov_unpack_to_pack.csv
364
+ ```
365
+
366
+ ## Examples
367
+
368
+ See `examples/example_usage.py` for more detailed usage examples.
369
+
370
+ ## Requirements
371
+
372
+ - Python 3.9+
373
+ - No external dependencies