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.
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: unxts.api
3
- Version: 2.0.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>=2.5.7
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
- {mod}`unxts.api` defines the abstract dispatch interfaces that {mod}`unxt` and other packages implement. It provides a minimal dependency foundation for packages that want to define or use {mod}`unxt`'s multiple-dispatch-based API without pulling in the full {mod}`unxt` implementation.
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 {mod}`unxts.api` package serves several important purposes:
21
+ The `unxts.api` package serves several important purposes:
22
22
 
23
- 1. **Minimal Dependencies**: Depends only on {mod}`plum`, not on {mod}`jax`, {mod}`numpy`, or {mod}`astropy`
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 {mod}`unxts.api` package defines abstract dispatch functions organized by domain:
52
+ The `unxts.api` package defines abstract dispatch functions organized by domain:
53
53
 
54
- - **Dimensions** ({func}`~unxts.api.dimension`, {func}`~unxts.api.dimension_of`) - Working with physical dimensions
55
- - **Units** ({func}`~unxts.api.unit`, {func}`~unxts.api.unit_of`) - Constructing and inspecting units
56
- - **Quantities** ({func}`~unxts.api.uconvert`, {func}`~unxts.api.uconvert_value`, {func}`~unxts.api.ustrip`, {func}`~unxts.api.is_unit_convertible`, {func}`~unxts.api.wrap_to`) - Unit conversion and quantity operations
57
- - **Unit Systems** ({func}`~unxts.api.unitsystem_of`) - Inspecting unit systems
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 {mod}`unxts.api` use [plum](https://beartype.github.io/plum/) for multiple dispatch. This means:
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 {mod}`unxt` package provides the concrete implementations of all {mod}`unxts.api` functions. When you use:
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 {mod}`unxt` for the abstract `uapi.uconvert` function.
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 {mod}`unxts.api` to use the dispatch system without pulling in {mod}`jax`:
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 {mod}`unxt` functionality:
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 {mod}`unxt`'s types directly:
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
- dependencies = ["plum-dispatch>=2.5.7"]
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
  ]
@@ -106,7 +106,7 @@ def is_unit_convertible(to_unit: Any, from_: Any, /) -> bool:
106
106
  False
107
107
 
108
108
  """
109
- return False
109
+ raise NotImplementedError # pragma: no cover
110
110
 
111
111
 
112
112
  @plum.dispatch.abstract
@@ -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.0'
22
- __version_tuple__ = version_tuple = (2, 0, 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