unxts.api 2.0.0__tar.gz → 2.0.2__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.
- {unxts_api-2.0.0 → unxts_api-2.0.2}/PKG-INFO +4 -3
- {unxts_api-2.0.0 → unxts_api-2.0.2}/docs/index.md +14 -14
- {unxts_api-2.0.0 → unxts_api-2.0.2}/pyproject.toml +7 -1
- {unxts_api-2.0.0 → unxts_api-2.0.2}/src/unxts/api/_src/quantity.py +1 -1
- unxts_api-2.0.2/src/unxts/api/_src/units.py +33 -0
- {unxts_api-2.0.0 → unxts_api-2.0.2}/src/unxts/api/_version.py +2 -2
- {unxts_api-2.0.0 → unxts_api-2.0.2}/tests/test_public_api.py +10 -0
- unxts_api-2.0.0/src/unxts/api/_src/units.py +0 -20
- {unxts_api-2.0.0 → unxts_api-2.0.2}/.gitignore +0 -0
- {unxts_api-2.0.0 → unxts_api-2.0.2}/LICENSE +0 -0
- {unxts_api-2.0.0 → unxts_api-2.0.2}/README.md +0 -0
- {unxts_api-2.0.0 → unxts_api-2.0.2}/docs/api.md +0 -0
- {unxts_api-2.0.0 → unxts_api-2.0.2}/docs/extending.md +0 -0
- {unxts_api-2.0.0 → unxts_api-2.0.2}/src/unxts/api/__init__.py +0 -0
- {unxts_api-2.0.0 → unxts_api-2.0.2}/src/unxts/api/_src/__init__.py +0 -0
- {unxts_api-2.0.0 → unxts_api-2.0.2}/src/unxts/api/_src/dimensions.py +0 -0
- {unxts_api-2.0.0 → unxts_api-2.0.2}/src/unxts/api/_src/unitsystems.py +0 -0
- {unxts_api-2.0.0 → unxts_api-2.0.2}/src/unxts/api/py.typed +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
Metadata-Version: 2.
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
2
|
Name: unxts.api
|
|
3
|
-
Version: 2.0.
|
|
3
|
+
Version: 2.0.2
|
|
4
4
|
Summary: Abstract dispatch API definitions for unxt (canonical: unxts.api)
|
|
5
5
|
Project-URL: Bug Tracker, https://github.com/GalacticDynamics/unxt/issues
|
|
6
6
|
Project-URL: Homepage, https://github.com/GalacticDynamics/unxt
|
|
@@ -20,7 +20,8 @@ Classifier: Programming Language :: Python :: 3.14
|
|
|
20
20
|
Classifier: Topic :: Scientific/Engineering
|
|
21
21
|
Classifier: Typing :: Typed
|
|
22
22
|
Requires-Python: >=3.12
|
|
23
|
-
Requires-Dist: plum-dispatch
|
|
23
|
+
Requires-Dist: plum-dispatch!=2.10.0,>=2.5.7
|
|
24
|
+
Requires-Dist: plum-dispatch>=2.9.0; python_version >= '3.14'
|
|
24
25
|
Description-Content-Type: text/markdown
|
|
25
26
|
|
|
26
27
|
# unxts.api
|
|
@@ -16,11 +16,11 @@ Abstract dispatch API for [unxt](https://github.com/GalacticDynamics/unxt).
|
|
|
16
16
|
|
|
17
17
|
:::
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
`unxts.api` defines the abstract dispatch interfaces that `unxt` and other packages implement. It provides a minimal dependency foundation for packages that want to define or use `unxt`'s multiple-dispatch-based API without pulling in the full `unxt` implementation.
|
|
20
20
|
|
|
21
|
-
The
|
|
21
|
+
The `unxts.api` package serves several important purposes:
|
|
22
22
|
|
|
23
|
-
1. **Minimal Dependencies**: Depends only on
|
|
23
|
+
1. **Minimal Dependencies**: Depends only on `plum`, not on `jax`, `numpy`, or `astropy`
|
|
24
24
|
2. **Extensibility**: Allows third-party packages to register their own implementations
|
|
25
25
|
3. **Type Safety**: Provides a clear contract for what functions exist and what they should do
|
|
26
26
|
4. **Separation of Concerns**: API definitions are separate from implementation details
|
|
@@ -49,16 +49,16 @@ uv add unxts.api
|
|
|
49
49
|
|
|
50
50
|
## Core API
|
|
51
51
|
|
|
52
|
-
The
|
|
52
|
+
The `unxts.api` package defines abstract dispatch functions organized by domain:
|
|
53
53
|
|
|
54
|
-
- **Dimensions** ({func}`~
|
|
55
|
-
- **Units** ({func}`~
|
|
56
|
-
- **Quantities** ({func}`~
|
|
57
|
-
- **Unit Systems** ({func}`~
|
|
54
|
+
- **Dimensions** ({func}`~unxt.dims.dimension`, {func}`~unxt.dims.dimension_of`) - Working with physical dimensions
|
|
55
|
+
- **Units** ({func}`~unxt.units.unit`, {func}`~unxt.units.unit_of`) - Constructing and inspecting units
|
|
56
|
+
- **Quantities** ({func}`~unxt.quantity.uconvert`, {func}`~unxt.quantity.uconvert_value`, {func}`~unxt.quantity.ustrip`, {func}`~unxt.quantity.is_unit_convertible`, {func}`~unxt.quantity.wrap_to`) - Unit conversion and quantity operations
|
|
57
|
+
- **Unit Systems** ({func}`~unxt.unitsystems.unitsystem_of`) - Inspecting unit systems
|
|
58
58
|
|
|
59
59
|
## Using Multiple Dispatch
|
|
60
60
|
|
|
61
|
-
All functions in
|
|
61
|
+
All functions in `unxts.api` use [plum](https://beartype.github.io/plum/) for multiple dispatch. This means:
|
|
62
62
|
|
|
63
63
|
1. **Functions can have multiple implementations** based on argument types
|
|
64
64
|
2. **You can register your own implementations** for custom types
|
|
@@ -139,7 +139,7 @@ This separation allows:
|
|
|
139
139
|
|
|
140
140
|
## Integration with `unxt`
|
|
141
141
|
|
|
142
|
-
The
|
|
142
|
+
The `unxt` package provides the concrete implementations of all `unxts.api` functions. When you use:
|
|
143
143
|
|
|
144
144
|
```python
|
|
145
145
|
import unxt as u
|
|
@@ -148,7 +148,7 @@ q = u.Q(5, "m")
|
|
|
148
148
|
u.uconvert("km", q)
|
|
149
149
|
```
|
|
150
150
|
|
|
151
|
-
The `u.uconvert` function is the implementation registered by
|
|
151
|
+
The `u.uconvert` function is the implementation registered by `unxt` for the abstract `uapi.uconvert` function.
|
|
152
152
|
|
|
153
153
|
## For Package Authors
|
|
154
154
|
|
|
@@ -156,7 +156,7 @@ If you're writing a package that works with physical quantities:
|
|
|
156
156
|
|
|
157
157
|
### Minimal Dependency Approach
|
|
158
158
|
|
|
159
|
-
Depend on
|
|
159
|
+
Depend on `unxts.api` to use the dispatch system without pulling in `jax`:
|
|
160
160
|
|
|
161
161
|
```toml
|
|
162
162
|
# pyproject.toml
|
|
@@ -192,7 +192,7 @@ def dimension_of(obj: YourType, /):
|
|
|
192
192
|
|
|
193
193
|
### Full Integration Approach
|
|
194
194
|
|
|
195
|
-
If you need JAX and want full
|
|
195
|
+
If you need JAX and want full `unxt` functionality:
|
|
196
196
|
|
|
197
197
|
```toml
|
|
198
198
|
# pyproject.toml
|
|
@@ -202,7 +202,7 @@ dependencies = [
|
|
|
202
202
|
]
|
|
203
203
|
```
|
|
204
204
|
|
|
205
|
-
Then use
|
|
205
|
+
Then use `unxt`'s types directly:
|
|
206
206
|
|
|
207
207
|
```python
|
|
208
208
|
import unxt as u
|
|
@@ -17,7 +17,12 @@ classifiers = [
|
|
|
17
17
|
"Topic :: Scientific/Engineering",
|
|
18
18
|
"Typing :: Typed",
|
|
19
19
|
]
|
|
20
|
-
|
|
20
|
+
# !=2.10.0: see the root `pyproject.toml`. The 3.14 floor is spelled out because,
|
|
21
|
+
# unlike the sibling packages, this one does not depend on `unxt` to supply it.
|
|
22
|
+
dependencies = [
|
|
23
|
+
"plum-dispatch>=2.5.7,!=2.10.0",
|
|
24
|
+
"plum-dispatch>=2.9.0; python_version>='3.14'",
|
|
25
|
+
]
|
|
21
26
|
description = "Abstract dispatch API definitions for unxt (canonical: unxts.api)"
|
|
22
27
|
dynamic = ["version"]
|
|
23
28
|
license = "BSD-3-Clause"
|
|
@@ -47,6 +52,7 @@ test = [
|
|
|
47
52
|
"pytest-cov>=6.2.1",
|
|
48
53
|
"pytest-env>=1.1.5",
|
|
49
54
|
"pytest-github-actions-annotate-failures>=0.3.0",
|
|
55
|
+
"pytest-xdist>=3.6.1",
|
|
50
56
|
"sybil[pytest]>=9.2.0",
|
|
51
57
|
"unxt",
|
|
52
58
|
]
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
"""Units API for unxt.
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2023 Galactic Dynamics. All rights reserved.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
__all__ = ("unit", "unit_of")
|
|
7
|
+
|
|
8
|
+
from typing import TYPE_CHECKING, Any
|
|
9
|
+
|
|
10
|
+
import plum
|
|
11
|
+
|
|
12
|
+
if TYPE_CHECKING:
|
|
13
|
+
# `unit` is liberal in what it accepts (Postel's law): a unit object, a
|
|
14
|
+
# string, ... -> a unit. Declared here as a plain callable so static
|
|
15
|
+
# checkers can read the `Any` parameter -- in particular so it works as an
|
|
16
|
+
# `equinox.field(converter=unit)`, making `Quantity(1, "m")` type-check.
|
|
17
|
+
# (`plum.dispatch.abstract` erases the signature to an opaque `Function`
|
|
18
|
+
# that the converter field-specifier cannot introspect.) The `raise` body
|
|
19
|
+
# keeps pylint from inferring a `None` return for callers (this branch is
|
|
20
|
+
# type-checking only; the runtime definition is dispatched by plum).
|
|
21
|
+
def unit(obj: Any, /) -> Any:
|
|
22
|
+
raise NotImplementedError
|
|
23
|
+
|
|
24
|
+
else:
|
|
25
|
+
|
|
26
|
+
@plum.dispatch.abstract
|
|
27
|
+
def unit(obj: Any, /) -> Any:
|
|
28
|
+
"""Construct the units from a units object."""
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
@plum.dispatch.abstract
|
|
32
|
+
def unit_of(obj: Any, /) -> Any:
|
|
33
|
+
"""Return the units of an object."""
|
|
@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
|
|
|
18
18
|
commit_id: str | None
|
|
19
19
|
__commit_id__: str | None
|
|
20
20
|
|
|
21
|
-
__version__ = version = '2.0.
|
|
22
|
-
__version_tuple__ = version_tuple = (2, 0,
|
|
21
|
+
__version__ = version = '2.0.2'
|
|
22
|
+
__version_tuple__ = version_tuple = (2, 0, 2)
|
|
23
23
|
|
|
24
24
|
__commit_id__ = commit_id = None
|
|
@@ -17,3 +17,13 @@ def test_dispatch_functions_are_callable():
|
|
|
17
17
|
|
|
18
18
|
def test_version_is_a_string():
|
|
19
19
|
assert isinstance(unxts.api.__version__, str)
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def test_wrap_to_keyword_form_redirects_to_positional():
|
|
23
|
+
"""``wrap_to(x, min=..., max=...)`` forwards to the positional method."""
|
|
24
|
+
|
|
25
|
+
@unxts.api.wrap_to.dispatch
|
|
26
|
+
def _(x: int, min: int, max: int, /) -> tuple:
|
|
27
|
+
return (x, min, max)
|
|
28
|
+
|
|
29
|
+
assert unxts.api.wrap_to(1, min=2, max=3) == (1, 2, 3)
|
|
@@ -1,20 +0,0 @@
|
|
|
1
|
-
"""Units API for unxt.
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2023 Galactic Dynamics. All rights reserved.
|
|
4
|
-
"""
|
|
5
|
-
|
|
6
|
-
__all__ = ("unit", "unit_of")
|
|
7
|
-
|
|
8
|
-
from typing import Any
|
|
9
|
-
|
|
10
|
-
import plum
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
@plum.dispatch.abstract
|
|
14
|
-
def unit(obj: Any, /) -> Any:
|
|
15
|
-
"""Construct the units from a units object."""
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
@plum.dispatch.abstract
|
|
19
|
-
def unit_of(obj: Any, /) -> Any:
|
|
20
|
-
"""Return the units of an object."""
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|