diff --git a/docs/dtype.md b/docs/dtype.md new file mode 100644 index 0000000..f7be5ca --- /dev/null +++ b/docs/dtype.md @@ -0,0 +1,98 @@ +# dtype + +```{todo} +This section is under construction as of 1.6.1 + +Much of the details of dtypes are covered in [syntax](./syntax.md) +and in {mod}`numpydantic.dtype` , but this section will specifically +address how dtypes are handled both generically and by interfaces +as we expand custom dtype handling <3. + +For details of support and implementation until the docs have time for some love, +please see the tests, which are the source of truth for the functionality +of the library for now and forever. +``` + +Recall the general syntax: + +``` +NDArray[Shape, dtype] +``` + +These are the docs for what can do in `dtype`. + +## Scalar Dtypes + +Python builtin types and numpy types should be handled transparently, +with some exception for complex numbers and objects (described below). + +### Numbers + +#### Complex numbers + +```{todo} +Document limitations for complex numbers and strategies for serialization/validation +``` + +### Datetimes + +```{todo} +Datetimes are supported by every interface except :class:`.VideoInterface` , +with the caveat that HDF5 loses timezone information, and thus all timestamps should +be re-encoded to UTC before saving/loading. + +More generic datetime support is TODO. +``` + +### Objects + +```{todo} +Generic objects are supported by all interfaces except +:class:`.VideoInterface` , :class;`.HDF5Interface` , and :class:`.ZarrInterface` . + +this might be expected, but there is also hope, TODO fill in serialization plans. +``` + +### Strings + +```{todo} +Strings are supported by all interfaces except :class:`.VideoInterface` . + +TODO is fill in the subtleties of how this works +``` + +## Generic Dtypes + +```{todo} +For now these are handled as tuples of dtypes, see the source of +{ref}`numpydantic.dtype.Float` . They should either be handled as Unions +or as a more prescribed meta-type. + +For now, use `int` and `float` to refer to the general concepts of +"any int" or "any float" even if this is a bit mismatched from the numpy usage. +``` + +## Extended Python Typing Universe + +### Union Types + +Union types can be used as expected. + +Union types are tested recursively -- if any item within a ``Union`` matches +the expected dtype at a given level of recursion, the dtype test passes. + +```python +class MyModel(BaseModel): + array: NDArray[Any, int | float] +``` + +## Compound Dtypes + +```{todo} +Compound dtypes are currently unsupported, +though the HDF5 interface supports indexing into compound dtypes +as separable dimensions/arrays using the third "field" parameter in +{class}`.hdf5.H5ArrayPath` . +``` + + diff --git a/docs/index.md b/docs/index.md index 9caaaf7..bced657 100644 --- a/docs/index.md +++ b/docs/index.md @@ -473,6 +473,7 @@ dumped = instance.model_dump_json(context={'zarr_dump_array': True}) design syntax +dtype serialization interfaces ```