unxt-api 1.8.0__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,165 @@
1
+ # -----------------------------------------------
2
+ # Project-Specific
3
+
4
+ # Version files
5
+ _version.py
6
+
7
+
8
+ # -----------------------------------------------
9
+ # General
10
+
11
+ # Byte-compiled / optimized / DLL files
12
+ __pycache__/
13
+ *.py[cod]
14
+ *$py.class
15
+
16
+ # C extensions
17
+ *.so
18
+
19
+ # Distribution / packaging
20
+ .Python
21
+ build/
22
+ develop-eggs/
23
+ dist/
24
+ downloads/
25
+ eggs/
26
+ .eggs/
27
+ lib/
28
+ lib64/
29
+ parts/
30
+ sdist/
31
+ var/
32
+ wheels/
33
+ share/python-wheels/
34
+ *.egg-info/
35
+ .installed.cfg
36
+ *.egg
37
+ MANIFEST
38
+
39
+ # PyInstaller
40
+ # Usually these files are written by a python script from a template
41
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
42
+ *.manifest
43
+ *.spec
44
+
45
+ # Installer logs
46
+ pip-log.txt
47
+ pip-delete-this-directory.txt
48
+
49
+ # Unit test / coverage reports
50
+ htmlcov/
51
+ .tox/
52
+ .nox/
53
+ .coverage
54
+ .coverage.*
55
+ .cache
56
+ nosetests.xml
57
+ coverage.xml
58
+ *.cover
59
+ *.py,cover
60
+ .hypothesis/
61
+ .pytest_cache/
62
+ cover/
63
+
64
+ # Translations
65
+ *.mo
66
+ *.pot
67
+
68
+ # Django stuff:
69
+ *.log
70
+ local_settings.py
71
+ db.sqlite3
72
+ db.sqlite3-journal
73
+
74
+ # Flask stuff:
75
+ instance/
76
+ .webassets-cache
77
+
78
+ # Scrapy stuff:
79
+ .scrapy
80
+
81
+ # Sphinx documentation
82
+ docs/_build/
83
+
84
+ # PyBuilder
85
+ .pybuilder/
86
+ target/
87
+
88
+ # Jupyter Notebook
89
+ .ipynb_checkpoints
90
+
91
+ # IPython
92
+ profile_default/
93
+ ipython_config.py
94
+
95
+ # pyenv
96
+ # For a library or package, you might want to ignore these files since the code is
97
+ # intended to run in multiple environments; otherwise, check them in:
98
+ # .python-version
99
+
100
+ # pipenv
101
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
102
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
103
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
104
+ # install all needed dependencies.
105
+ #Pipfile.lock
106
+
107
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow
108
+ __pypackages__/
109
+
110
+ # Celery stuff
111
+ celerybeat-schedule
112
+ celerybeat.pid
113
+
114
+ # SageMath parsed files
115
+ *.sage.py
116
+
117
+ # Environments
118
+ .env
119
+ .venv
120
+ env/
121
+ venv/
122
+ ENV/
123
+ env.bak/
124
+ venv.bak/
125
+
126
+ # Spyder project settings
127
+ .spyderproject
128
+ .spyproject
129
+
130
+ # Rope project settings
131
+ .ropeproject
132
+
133
+ # mkdocs documentation
134
+ /site
135
+
136
+ # mypy
137
+ .mypy_cache/
138
+ .dmypy.json
139
+ dmypy.json
140
+
141
+ # Pyre type checker
142
+ .pyre/
143
+
144
+ # pytype static type analyzer
145
+ .pytype/
146
+
147
+ # Cython debug symbols
148
+ cython_debug/
149
+
150
+ # ruff
151
+ .ruff_cache/
152
+
153
+ # OS specific stuff
154
+ .DS_Store
155
+ .DS_Store?
156
+ ._*
157
+ .Spotlight-V100
158
+ .Trashes
159
+ ehthumbs.db
160
+ Thumbs.db
161
+
162
+ # Common editor files
163
+ *~
164
+ *.swp
165
+ /.codspeed
@@ -0,0 +1,81 @@
1
+ Metadata-Version: 2.4
2
+ Name: unxt-api
3
+ Version: 1.8.0
4
+ Summary: Abstract dispatch API definitions for unxt
5
+ Project-URL: Bug Tracker, https://github.com/GalacticDynamics/unxt/issues
6
+ Project-URL: Homepage, https://github.com/GalacticDynamics/unxt
7
+ Author-email: GalacticDynamics <nstarman@users.noreply.github.com>, Nathaniel Starkman <nstarman@users.noreply.github.com>
8
+ License: BSD-3-Clause
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Intended Audience :: Developers
11
+ Classifier: Intended Audience :: Science/Research
12
+ Classifier: License :: OSI Approved :: BSD License
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Scientific/Engineering
21
+ Classifier: Typing :: Typed
22
+ Requires-Python: >=3.11
23
+ Requires-Dist: astropy>=7.0.0
24
+ Requires-Dist: plum-dispatch>=2.5.7
25
+ Description-Content-Type: text/markdown
26
+
27
+ # unxt-api
28
+
29
+ Abstract dispatch API definitions for unxt.
30
+
31
+ This package defines the abstract dispatch interfaces that unxt and other
32
+ packages can implement. It provides a minimal dependency set for packages that
33
+ want to define or use unxt's dispatch-based API without pulling in the full unxt
34
+ implementation.
35
+
36
+ ## Installation
37
+
38
+ ```bash
39
+ pip install unxt-api
40
+ ```
41
+
42
+ ## Usage
43
+
44
+ This package is typically used as a dependency by unxt and related packages. It
45
+ defines abstract dispatch signatures using plum-dispatch that concrete
46
+ implementations register against.
47
+
48
+ For comprehensive documentation, examples, and extension guides, see:
49
+
50
+ - [unxt-api API Reference](https://unxt.readthedocs.io/en/latest/api/unxt-api.html)
51
+ - [Extending unxt Guide](https://unxt.readthedocs.io/en/latest/guides/extending.html)
52
+ - [Main unxt Documentation](https://unxt.readthedocs.io/)
53
+
54
+ ## Quick Example
55
+
56
+ ```python
57
+ from plum import dispatch
58
+ import unxt as u
59
+
60
+
61
+ class Temperature:
62
+ def __init__(self, value, unit="K"):
63
+ self.value = value
64
+ self.unit_str = unit
65
+
66
+
67
+ @dispatch
68
+ def unit_of(obj: Temperature, /):
69
+ return u.unit(obj.unit_str)
70
+
71
+
72
+ @dispatch
73
+ def dimension_of(obj: Temperature, /):
74
+ return u.dimension("temperature")
75
+
76
+
77
+ # Now Temperature works with unxt!
78
+ temp = Temperature(300, "K")
79
+ u.unit_of(temp) # Unit("K")
80
+ u.dimension_of(temp) # PhysicalType('temperature')
81
+ ```
@@ -0,0 +1,55 @@
1
+ # unxt-api
2
+
3
+ Abstract dispatch API definitions for unxt.
4
+
5
+ This package defines the abstract dispatch interfaces that unxt and other
6
+ packages can implement. It provides a minimal dependency set for packages that
7
+ want to define or use unxt's dispatch-based API without pulling in the full unxt
8
+ implementation.
9
+
10
+ ## Installation
11
+
12
+ ```bash
13
+ pip install unxt-api
14
+ ```
15
+
16
+ ## Usage
17
+
18
+ This package is typically used as a dependency by unxt and related packages. It
19
+ defines abstract dispatch signatures using plum-dispatch that concrete
20
+ implementations register against.
21
+
22
+ For comprehensive documentation, examples, and extension guides, see:
23
+
24
+ - [unxt-api API Reference](https://unxt.readthedocs.io/en/latest/api/unxt-api.html)
25
+ - [Extending unxt Guide](https://unxt.readthedocs.io/en/latest/guides/extending.html)
26
+ - [Main unxt Documentation](https://unxt.readthedocs.io/)
27
+
28
+ ## Quick Example
29
+
30
+ ```python
31
+ from plum import dispatch
32
+ import unxt as u
33
+
34
+
35
+ class Temperature:
36
+ def __init__(self, value, unit="K"):
37
+ self.value = value
38
+ self.unit_str = unit
39
+
40
+
41
+ @dispatch
42
+ def unit_of(obj: Temperature, /):
43
+ return u.unit(obj.unit_str)
44
+
45
+
46
+ @dispatch
47
+ def dimension_of(obj: Temperature, /):
48
+ return u.dimension("temperature")
49
+
50
+
51
+ # Now Temperature works with unxt!
52
+ temp = Temperature(300, "K")
53
+ u.unit_of(temp) # Unit("K")
54
+ u.dimension_of(temp) # PhysicalType('temperature')
55
+ ```
@@ -0,0 +1,285 @@
1
+ # API Reference
2
+
3
+ ## Dimensions
4
+
5
+ ### `dimension(obj)`
6
+
7
+ Construct a dimension from various inputs.
8
+
9
+ **Abstract Signature:**
10
+
11
+ ```python
12
+ from typing import Any
13
+ import plum
14
+
15
+
16
+ @plum.dispatch.abstract
17
+ def dimension(obj: Any, /) -> Any:
18
+ """Construct the dimension."""
19
+ ```
20
+
21
+ **Example Implementations** (in `unxt`):
22
+
23
+ - `dimension(dimension: AbstractDimension)` - Identity operation
24
+ - `dimension(s: str)` - Construct from string (e.g., `"length"`, `"velocity"`)
25
+
26
+ **Examples:**
27
+
28
+ ```python
29
+ import unxt as u
30
+
31
+ # From string
32
+ length_dim = u.dimension("length")
33
+
34
+ # From unit
35
+ meter_dim = u.dimension_of(u.unit("m"))
36
+ ```
37
+
38
+ ### `dimension_of(obj)`
39
+
40
+ Return the dimension of an object.
41
+
42
+ **Abstract Signature:**
43
+
44
+ ```python
45
+ @plum.dispatch.abstract
46
+ def dimension_of(obj: Any, /) -> Any:
47
+ """Return the dimension of the given units."""
48
+ ```
49
+
50
+ **Example Implementations** (in `unxt`):
51
+
52
+ - `dimension_of(unit: AbstractUnit)` - Get dimension from unit
53
+ - `dimension_of(quantity: Quantity)` - Get dimension from quantity
54
+
55
+ **Examples:**
56
+
57
+ ```python
58
+ import unxt as u
59
+
60
+ # From unit
61
+ u.dimension_of(u.unit("km")) # PhysicalType('length')
62
+
63
+ # From quantity
64
+ q = u.Q(5, "kg")
65
+ u.dimension_of(q) # PhysicalType('mass')
66
+ ```
67
+
68
+ ## Units
69
+
70
+ ### `unit(obj)`
71
+
72
+ Construct units from various inputs.
73
+
74
+ **Abstract Signature:**
75
+
76
+ ```python
77
+ @plum.dispatch.abstract
78
+ def unit(obj: Any, /) -> u.AbstractUnit:
79
+ """Construct the units from a units object."""
80
+ ```
81
+
82
+ **Example Implementations** (in `unxt`):
83
+
84
+ - `unit(unit: AbstractUnit)` - Identity operation
85
+ - `unit(s: str)` - Parse unit from string (e.g., `"m"`, `"km/s"`)
86
+
87
+ **Examples:**
88
+
89
+ ```python
90
+ import unxt as u
91
+
92
+ # From string
93
+ meter = u.unit("m")
94
+ velocity = u.unit("km/s")
95
+ ```
96
+
97
+ ### `unit_of(obj)`
98
+
99
+ Return the units of an object.
100
+
101
+ **Abstract Signature:**
102
+
103
+ ```python
104
+ @plum.dispatch.abstract
105
+ def unit_of(obj: Any, /) -> u.AbstractUnit:
106
+ """Return the units of an object."""
107
+ ```
108
+
109
+ **Example Implementations** (in `unxt`):
110
+
111
+ - `unit_of(obj: Any)` - Returns `None` for objects without units
112
+ - `unit_of(unit: AbstractUnit)` - Identity operation
113
+ - `unit_of(quantity: Quantity)` - Extract unit from quantity
114
+
115
+ **Examples:**
116
+
117
+ ```python
118
+ import unxt as u
119
+
120
+ # From quantity
121
+ q = u.Q(5, "m")
122
+ u.unit_of(q) # Unit("m")
123
+
124
+ # From non-quantity
125
+ u.unit_of(5) # None
126
+ ```
127
+
128
+ ## Quantities
129
+
130
+ ### `uconvert(to_unit, quantity)`
131
+
132
+ Convert a quantity to the specified units.
133
+
134
+ **Abstract Signature:**
135
+
136
+ ```python
137
+ @plum.dispatch.abstract
138
+ def uconvert(u: Any, x: Any, /) -> Any:
139
+ """Convert the quantity to the specified units."""
140
+ ```
141
+
142
+ **Example Implementations** (in `unxt`):
143
+
144
+ - `uconvert(to_unit: str | AbstractUnit, quantity: Quantity)` - Convert quantity
145
+ to new units
146
+
147
+ **Examples:**
148
+
149
+ ```python
150
+ import unxt as u
151
+
152
+ # Convert quantity
153
+ q = u.Q(1, "km")
154
+ u.uconvert("m", q) # Quantity(Array(1000., ...), unit='m')
155
+ ```
156
+
157
+ ### `ustrip(quantity)` / `ustrip(to_unit, quantity)`
158
+
159
+ Strip units from a quantity, optionally converting first.
160
+
161
+ **Abstract Signature:**
162
+
163
+ ```python
164
+ @plum.dispatch.abstract
165
+ def ustrip(*args: Any) -> Any:
166
+ """Strip the units from the quantity, first converting if necessary."""
167
+ ```
168
+
169
+ **Example Implementations** (in `unxt`):
170
+
171
+ - `ustrip(quantity: Quantity)` - Get value in current units
172
+ - `ustrip(to_unit: str | AbstractUnit, quantity: Quantity)` - Convert then get
173
+ value.
174
+
175
+ **Examples:**
176
+
177
+ ```python
178
+ import unxt as u
179
+
180
+ # Strip current units
181
+ q = u.Q(5, "km")
182
+ u.ustrip(q) # Array(5., ...)
183
+
184
+ # Convert then strip
185
+ u.ustrip("m", q) # Array(5000., ...)
186
+ ```
187
+
188
+ ### `is_unit_convertible(to_unit, from_obj)`
189
+
190
+ Check if units are convertible.
191
+
192
+ **Abstract Signature:**
193
+
194
+ ```python
195
+ @plum.dispatch.abstract
196
+ def is_unit_convertible(to_unit: Any, from_: Any, /) -> bool:
197
+ """Check if the units are convertible."""
198
+ ```
199
+
200
+ **Example Implementations** (in `unxt`):
201
+
202
+ - `is_unit_convertible(to_unit: AbstractUnit, from_unit: AbstractUnit)` - Check
203
+ unit compatibility
204
+ - `is_unit_convertible(to_unit: AbstractUnit, from_quantity: Quantity)` - Check
205
+ if quantity can convert
206
+
207
+ **Examples:**
208
+
209
+ ```python
210
+ import unxt as u
211
+
212
+ # Check unit compatibility
213
+ u.is_unit_convertible(u.unit("km"), u.unit("m")) # True
214
+ u.is_unit_convertible(u.unit("kg"), u.unit("m")) # False
215
+
216
+ # Check quantity
217
+ q = u.Q(5, "m")
218
+ u.is_unit_convertible(u.unit("km"), q) # True
219
+ u.is_unit_convertible(u.unit("kg"), q) # False
220
+ ```
221
+
222
+ ### `wrap_to(value, min, max)`
223
+
224
+ Wrap a value to the range [min, max).
225
+
226
+ **Abstract Signature:**
227
+
228
+ ```python
229
+ @plum.dispatch.abstract
230
+ def wrap_to(x: Any, min: Any, max: Any, /) -> Any:
231
+ """Wrap to the range [min, max)."""
232
+ ```
233
+
234
+ **Example Implementations** (in `unxt`):
235
+
236
+ - `wrap_to(angle: Quantity, min: Quantity, max: Quantity)` - Wrap angles to
237
+ range
238
+
239
+ **Examples:**
240
+
241
+ ```python
242
+ import unxt as u
243
+
244
+ # Wrap angle to [0, 360) degrees
245
+ angle = u.Q(370, "deg")
246
+ min_angle = u.Q(0, "deg")
247
+ max_angle = u.Q(360, "deg")
248
+
249
+ u.quantity.wrap_to(angle, min_angle, max_angle) # Angle(Array(10, ...), unit='deg')
250
+
251
+ # Can also use keyword arguments
252
+ u.quantity.wrap_to(angle, min=min_angle, max=max_angle)
253
+ ```
254
+
255
+ ## Unit Systems
256
+
257
+ ### `unitsystem_of(obj)`
258
+
259
+ Return the unit system of an object.
260
+
261
+ **Abstract Signature:**
262
+
263
+ ```python
264
+ @plum.dispatch.abstract
265
+ def unitsystem_of(obj: Any, /) -> Any:
266
+ """Return the unit system of an object."""
267
+ ```
268
+
269
+ **Example Implementations** (in `unxt`):
270
+
271
+ - `unitsystem_of(quantity: Quantity)` - Get unit system if quantity has one
272
+ - `unitsystem_of(unitsystem: AbstractUnitSystem)` - Identity operation
273
+
274
+ **Examples:**
275
+
276
+ ```python
277
+ import unxt as u
278
+
279
+ # From unit system
280
+ sys = u.unitsystem("m", "s", "kg", "rad")
281
+ u.unitsystem_of(sys) # Returns sys
282
+
283
+ # From quantity (if it has an associated system)
284
+ # This depends on how the quantity was constructed
285
+ ```