dash-pydantic-utils 0.14.0__py3-none-any.whl

dash_pydantic_utils/__init__.py

@@ -0,0 +1,42 @@
+from .common import (
+    deep_diff,
+    deep_merge,
+    get_all_subclasses,
+    get_model_cls,
+    get_non_null_annotation,
+    is_subclass,
+)
+from .path import (
+    SEP,
+    from_form_data,
+    get_fullpath,
+    get_model_value,
+    get_subitem,
+    get_subitem_cls,
+    handle_discriminated,
+    model_construct_recursive,
+    set_at_path,
+)
+from .quantity import Quantity, QuantityDtype
+from .types import Type
+
+__all__ = [
+    "deep_diff",
+    "deep_merge",
+    "from_form_data",
+    "get_all_subclasses",
+    "get_fullpath",
+    "get_model_cls",
+    "get_model_value",
+    "get_non_null_annotation",
+    "get_subitem",
+    "get_subitem_cls",
+    "handle_discriminated",
+    "is_subclass",
+    "model_construct_recursive",
+    "Quantity",
+    "QuantityDtype",
+    "SEP",
+    "set_at_path",
+    "Type",
+]

dash_pydantic_utils/common.py

@@ -0,0 +1,66 @@
+from copy import deepcopy
+from types import UnionType
+from typing import Any, Union, get_args, get_origin
+
+from pydantic import BaseModel
+
+
+def deep_merge(dict1: dict, dict2: dict) -> dict:
+    """Deep merge two dictionaries, the second input is given priority."""
+    dict_final = deepcopy(dict1)
+    for key, val in dict2.items():
+        if isinstance(val, dict):
+            dict_final[key] = deep_merge(dict_final.get(key, {}), val)
+        else:
+            dict_final[key] = val
+    return dict_final
+
+
+def deep_diff(dict1: dict, dict2: dict) -> dict[str, dict | tuple[Any, Any]]:
+    """Compute the deep difference between two dictionaries."""
+    diff = {}
+    for key in dict1.keys() | dict2.keys():
+        if isinstance(dict1.get(key), dict) and isinstance(dict2.get(key), dict):
+            sub_diff = deep_diff(dict1[key], dict2[key])
+            if sub_diff:
+                diff[key] = sub_diff
+        elif dict1.get(key) != dict2.get(key):
+            diff[key] = (dict1.get(key), dict2.get(key))
+    return diff
+
+
+def get_non_null_annotation(annotation: type[Any]) -> type[Any]:
+    """Get a non-null annotation.
+
+    e.g., get_non_null_annotation(Optional[str]) = str
+    """
+    if get_origin(annotation) in [Union, UnionType]:
+        args = tuple(x for x in get_args(annotation) if x is not type(None))
+        if len(args) == 1:
+            return args[0]
+        return Union[args]  # noqa: UP007
+    return annotation
+
+
+def get_all_subclasses(cls: type):
+    """Get all subclasses of a class."""
+    all_subclasses = []
+
+    for subclass in cls.__subclasses__():
+        all_subclasses.append(subclass)
+        all_subclasses.extend(get_all_subclasses(subclass))
+
+    return all_subclasses
+
+
+def get_model_cls(str_repr: str) -> type[BaseModel]:
+    """Get the model class from a string representation."""
+    return next(cls for cls in get_all_subclasses(BaseModel) if str(cls) == str_repr)
+
+
+def is_subclass(cls: type, base_cls: type) -> bool:
+    """Check if a class is a subclass of another class, handling issubclass errors."""
+    try:
+        return issubclass(cls, base_cls)
+    except TypeError:
+        return False

dash_pydantic_utils/path.py

@@ -0,0 +1,289 @@
+import logging
+import re
+from copy import deepcopy
+from typing import Annotated, Any, Literal, get_args, get_origin
+
+from pydantic import BaseModel, ValidationError, create_model
+from pydantic.fields import FieldInfo
+from pydantic_core import PydanticUndefined
+
+from dash_pydantic_utils.common import get_non_null_annotation, is_subclass
+from dash_pydantic_utils.types import Type
+
+SEP = ":"
+
+
+def get_model_value(item: BaseModel, field: str, parent: str, allow_default: bool = True):  # noqa: PLR0911
+    """Get the value of a model (parent, field) pair.
+
+    Parameters
+    ----------
+    item: BaseModel
+        The object to get the value from
+    field: str
+        The field name
+    parent: str
+        The parent of the field (for nested fields), in dot notation
+    allow_default: bool
+        Allow to return the default value, when the object has been created with model_construct.
+    """
+    try:
+        subitem = get_subitem(item, parent)
+        if isinstance(subitem, BaseModel):
+            return subitem[field]
+        if isinstance(subitem, dict) and isinstance(field, int):
+            return list(subitem.values())[field]
+        if isinstance(subitem, list) and isinstance(field, int):
+            return subitem[field]
+        return subitem[field]
+    except:
+        if allow_default:
+            subitem_cls = get_subitem_cls(item.__class__, parent, item=item)
+            if not is_subclass(subitem_cls, BaseModel):
+                return None
+            field_info = subitem_cls.model_fields[field]
+            if field_info.default is not PydanticUndefined:
+                return field_info.default
+            if field_info.default_factory:
+                return field_info.default_factory()
+            return None
+        raise
+
+
+def get_subitem(item: BaseModel | list | dict, parent: str) -> BaseModel:
+    """Get the subitem of a model at a given parent.
+
+    e.g., get_subitem(person, "au_metadata") = AUMetadata(param1=True, param2=False)
+    """
+    if parent == "":
+        return item
+
+    path = parent.split(SEP)
+
+    first_part = path[0]
+    if isinstance(first_part, str) and first_part.isdigit():
+        first_part = int(first_part)
+
+    if isinstance(item, BaseModel):
+        next_item = getattr(item, first_part)
+    elif isinstance(item, dict) and isinstance(first_part, int):
+        next_item = list(item.values())[first_part]
+    elif isinstance(item, list) and isinstance(first_part, int):
+        next_item = item[first_part]
+    elif is_idx_template(first_part):
+        next_item = None
+    else:
+        next_item = item.get(first_part)
+
+    if len(path) == 1 or next_item is None:
+        return next_item
+
+    return get_subitem(next_item, SEP.join(path[1:]))
+
+
+def is_idx_template(val: str):
+    """Check if a string is an index template."""
+    return bool(re.findall(r"^\{\{[\w|\{\}]+\}\}$", val))
+
+
+def get_subitem_cls(model: type[BaseModel], parent: str, item: BaseModel | None = None) -> type[BaseModel]:
+    """Get the subitem class of a model at a given parent.
+
+    e.g., get_subitem_cls(Person, "au_metadata") = AUMetadata
+    """
+    if parent == "":
+        return model
+
+    path = parent.split(SEP)
+
+    first_part = path[0]
+    second_part = None
+
+    if len(path) == 1:
+        ann = get_non_null_annotation(model.model_fields[first_part].annotation)
+        return ann
+
+    second_part = path[1]
+    if isinstance(second_part, str) and second_part.isdigit():
+        second_part = int(second_part)
+
+    field_info = model.model_fields[first_part] if is_subclass(model, BaseModel) else (item.model_fields[first_part])
+    first_annotation = get_non_null_annotation(field_info.annotation)
+    try:
+        subitem = get_subitem(item, first_part) if item is not None else None
+    except:  # noqa: E722
+        subitem = None
+    if Type.classify(first_annotation, field_info.discriminator) == Type.DISCRIMINATED_MODEL:
+        if not item:
+            raise TypeError("Discriminated models with nesting need passing item data to be displayed")
+        discriminator_value = None if subitem is None else getattr(subitem, field_info.discriminator, None)
+        subitem_cls, _ = handle_discriminated(
+            item.__class__, parent, first_annotation, field_info.discriminator, discriminator_value
+        )
+        return get_subitem_cls(subitem_cls, SEP.join(path[1:]), item=subitem)
+    if (
+        get_origin(first_annotation) is list
+        and (isinstance(second_part, int) or is_idx_template(second_part))
+        and get_args(first_annotation)
+    ):
+        try:
+            subitem = subitem[second_part] if subitem is not None else None
+        except:  # noqa: E722
+            subitem = None
+        return get_subitem_cls(
+            get_non_null_annotation(get_args(first_annotation)[0]),
+            SEP.join(path[2:]),
+            item=subitem,
+        )
+    if get_origin(first_annotation) is dict and (isinstance(second_part, int | str)) and get_args(first_annotation):
+        return get_subitem_cls(
+            get_non_null_annotation(get_args(first_annotation)[1]),
+            SEP.join(path[2:]),
+            item=subitem,
+        )
+    return get_subitem_cls(first_annotation, SEP.join(path[1:]), item=subitem)
+
+
+def handle_discriminated(model: type[BaseModel], parent: str, annotation: type, disc_field: str, disc_val: Any):
+    """Handle a discriminated model."""
+    all_vals = set()
+    out = None
+    if get_origin(annotation) is Annotated:
+        if disc_field is None:
+            disc_field = next(
+                (f.discriminator for f in get_args(annotation)[1:] if isinstance(f, FieldInfo)),
+                None,
+            )
+        annotation = get_args(annotation)[0]
+    for possible in get_args(annotation):
+        if not get_origin(possible.model_fields[disc_field].annotation) == Literal:
+            raise ValueError("Discriminator must be a Literal")
+
+        vals = get_args(possible.model_fields[disc_field].annotation)
+        all_vals = all_vals.union(vals)
+        if disc_val is not None and disc_val in vals:
+            out = possible
+
+    all_vals = tuple(all_vals)
+
+    if disc_val is None:
+        return create_model(
+            f"{model.__name__}{parent.replace(SEP, ' ').title().replace(' ', '')}Discriminator",
+            **{disc_field: (Literal[tuple(all_vals)], ...)},
+        ), all_vals
+
+    if out is None:
+        raise ValueError(f"Invalid discriminator value: {disc_val}")
+
+    return out, all_vals
+
+
+def get_fullpath(*parts, sep: str = SEP):
+    """Creates the full path of a field from its name and parent."""
+    return sep.join([str(p) for p in parts]).strip(sep)
+
+
+def model_construct_recursive(data: dict, data_model: type[BaseModel]):
+    """Construct a model recursively."""
+    updated = deepcopy(data)
+    for key, val in data.items():
+        if key not in data_model.model_fields:
+            continue
+        if val is None:
+            updated[key] = None
+            continue
+
+        field_info = data_model.model_fields[key]
+        ann = get_non_null_annotation(field_info.annotation)
+        type_ = Type.classify(ann, field_info.discriminator)
+        if type_ == Type.MODEL:
+            updated[key] = model_construct_recursive(val, ann)
+        elif type_ == Type.DISCRIMINATED_MODEL:
+            updated[key] = _construct_handle_discriminated(val, field_info.discriminator, ann)
+        elif type_ == Type.MODEL_LIST and isinstance(val, list):
+            updated[key] = [model_construct_recursive(vv, get_args(ann)[0]) for vv in val]
+        elif type_ == Type.DISCRIMINATED_MODEL_LIST and isinstance(val, list):
+            new_val = []
+            sub_ann = get_args(ann)[0]
+            # Note: since we have a DISCRIMINATED_MODEL_LIST, sub_ann will be an Annotated union with discriminator
+            sub_ann2 = get_args(sub_ann)[0]
+            discriminator = next((f.discriminator for f in get_args(sub_ann)[1:] if isinstance(f, FieldInfo)), None)
+            for vv in val:
+                new_val.append(_construct_handle_discriminated(vv, discriminator, sub_ann2))
+            updated[key] = new_val
+        elif type_ == Type.DISCRIMINATED_MODEL_DICT and isinstance(val, dict):
+            new_val = {}
+            sub_ann = get_args(ann)[1]
+            # Note: since we have a DISCRIMINATED_MODEL_LIST, sub_ann will be an Annotated union with discriminator
+            sub_ann2 = get_args(sub_ann)[0]
+            discriminator = next((f.discriminator for f in get_args(sub_ann)[1:] if isinstance(f, FieldInfo)), None)
+            for kk, vv in val.items():
+                new_val[kk] = _construct_handle_discriminated(vv, discriminator, sub_ann2)
+            updated[key] = new_val
+
+    return data_model.model_construct(**updated)
+
+
+def _construct_handle_discriminated(val: dict, discriminator: str | None, ann: type):
+    if discriminator is None or discriminator not in val:
+        return val
+
+    disc_val = val[discriminator]
+    out = None
+    for possible in get_args(ann):
+        if not get_origin(possible.model_fields[discriminator].annotation) == Literal:
+            raise ValueError("Discriminator must be a Literal")
+
+        if disc_val in get_args(possible.model_fields[discriminator].annotation):
+            out = possible
+            break
+
+    if out is not None:
+        return model_construct_recursive(val, out)
+    return val
+
+
+def from_form_data(data: dict, data_model: type[BaseModel]):
+    """Construct a model from form data, allowing to use default values when validation of a field fails."""
+    try:
+        return data_model.model_validate(data)
+    except ValidationError as exc:
+        data_with_defaults = deepcopy(data)
+        defaulted_fields = []
+        for error in exc.errors():
+            path_parts = [str(x) for x in error["loc"]]
+            for i in range(len(path_parts), 0, -1):
+                parts_extract = path_parts[:i]
+                path = SEP.join(parts_extract)
+                try:
+                    failing_model = get_subitem_cls(data_model, SEP.join(parts_extract[:-1]))
+                except AttributeError:
+                    continue
+                if not is_subclass(failing_model, BaseModel):
+                    continue
+                field = failing_model.model_fields[parts_extract[-1]]
+                if field.default != PydanticUndefined:
+                    set_at_path(data_with_defaults, path, field.default)
+                    defaulted_fields.append(path)
+                    break
+                if field.default_factory is not None:
+                    set_at_path(data_with_defaults, path, field.default_factory())
+                    defaulted_fields.append(path)
+                    break
+
+        if defaulted_fields:
+            logging.info(
+                "Could not validate the following fields: %s for %s, using default values instead.",
+                defaulted_fields,
+                data_model.__name__,
+            )
+        return data_model.model_validate(data_with_defaults)
+
+
+def set_at_path(data: dict, path: str, value: Any):
+    """Set a value at a path in a dictionary."""
+    parts = path.split(SEP)
+    pointer = data
+    for part in parts[:-1]:
+        pointer = pointer.get(part, pointer[int(part)])
+    pointer[parts[-1]] = value

dash_pydantic_utils/quantity/__init__.py

@@ -0,0 +1,12 @@
+from pydantic import BaseModel
+
+try:
+    from .pandas import Quantity, QuantityDtype
+except ModuleNotFoundError:
+    from .quantity import Quantity
+
+    QuantityDtype = None
+
+BaseModel.__getitem__ = lambda self, key: self.__dict__.get(key)
+
+__all__ = ["Quantity", "QuantityDtype"]

dash_pydantic_utils/quantity/pandas.py

@@ -0,0 +1,272 @@
+# ruff: noqa
+# TODO: ^
+from __future__ import annotations
+
+import re
+from typing import ClassVar
+
+import numpy as np
+import numpy.typing as npt
+import pandas as pd
+from pandas.core import ops
+from pandas.core.algorithms import take
+from pandas.core.arrays.numeric import NumericArray, NumericDtype
+from pandas.core.dtypes.base import register_extension_dtype
+from pandas.core.dtypes.common import is_bool, is_float_dtype, pandas_dtype
+from pandas.core.dtypes.missing import isna, notna
+from pandas.core.indexers import check_array_indexer
+from pandas.util._decorators import cache_readonly
+
+from .quantity import ISUnits
+from .quantity import Quantity as Quantity_
+
+
+class Quantity(Quantity_):
+    value: float | np.ndarray
+    model_config = {"arbitrary_types_allowed": True}
+
+    def __str__(self) -> str:
+        if isinstance(self.value, np.ndarray):
+            return f"{self.value}, {self.unit}"
+        return super().__str__()
+
+    @property
+    def dtype(self):
+        return QuantityDtype(unit=self.unit)
+
+
+@register_extension_dtype
+class QuantityDtype(NumericDtype):
+    type = np.float64
+    name: ClassVar[str] = "Quantity"
+    _metadata = ("unit",)
+    _default_np_dtype = np.dtype(np.float64)
+    _checker = is_float_dtype
+
+    @property
+    def name(self) -> str:
+        return f"Quantity[{self.unit}]"
+
+    def __init__(self, unit: str, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.unit = unit
+
+    def __repr__(self):
+        return f"QuantityDtype({self.unit})"
+
+    @classmethod
+    def construct_array_type(cls) -> type[QuantityArray]:
+        """
+        Return the array type associated with this dtype.
+
+        Returns
+        -------
+        type
+        """
+        return QuantityArray
+
+    @classmethod
+    def construct_from_string(cls, string: str):
+        try:
+            unit = re.findall(r"^Quantity\[(.*)\]$", string)[0]
+            return cls(unit=unit)
+        except Exception as exc:
+            raise TypeError(f"Cannot construct QuantityDtype from {string}") from exc
+
+    @classmethod
+    def _safe_cast(cls, values: np.ndarray, dtype: np.dtype, copy: bool) -> np.ndarray:
+        """
+        Safely cast the values to the given dtype.
+
+        "safe" in this context means the casting is lossless.
+        """
+        # This is really only here for compatibility with IntegerDtype
+        # Here for compat with IntegerDtype
+        return values.astype(dtype, copy=copy)
+
+    def __from_arrow__(self, array, **kwargs):
+        import pyarrow
+        from pandas.core.arrays.arrow._arrow_utils import pyarrow_array_to_numpy_and_mask
+
+        array_class = self.construct_array_type()
+
+        pyarrow_type = pyarrow.from_numpy_dtype(self.type)
+        if not array.type.equals(pyarrow_type) and not pyarrow.types.is_null(array.type):
+            # test_from_arrow_type_error raise for string, but allow
+            #  through itemsize conversion GH#31896
+            rt_dtype = pandas_dtype(array.type.to_pandas_dtype())
+            if rt_dtype.kind not in "iuf":
+                # Could allow "c" or potentially disallow float<->int conversion,
+                #  but at the moment we specifically test that uint<->int works
+                raise TypeError(f"Expected array of {self} type, got {array.type} instead")
+
+            array = array.cast(pyarrow_type)
+
+        if isinstance(array, pyarrow.ChunkedArray):
+            # TODO this "if" can be removed when requiring pyarrow >= 10.0, which fixed
+            # combine_chunks for empty arrays https://github.com/apache/arrow/pull/13757
+            array = pyarrow.array([], type=array.type) if array.num_chunks == 0 else array.combine_chunks()
+
+        data, mask = pyarrow_array_to_numpy_and_mask(array, dtype=self.numpy_dtype)
+        return array_class(self.unit, data.copy(), ~mask, copy=False)
+
+    def _get_common_dtype(self, dtypes: list):
+        if not all(isinstance(dtype, QuantityDtype) for dtype in dtypes):
+            raise ValueError("No common dtype between Quantity and non-Quantity types")
+        raise ValueError("No common dtype between Quantity with different units")
+
+    def __eq__(self, other):
+        return isinstance(other, QuantityDtype) and self.unit == other.unit
+
+    def __hash__(self):
+        return hash(str(self))
+
+
+class QuantityArray(NumericArray):
+    _dtype_cls = QuantityDtype
+    _internal_fill_value = np.nan
+
+    @cache_readonly
+    def dtype(self) -> NumericDtype:
+        return QuantityDtype(unit=self.unit)
+
+    def __init__(self, unit: str, values: np.ndarray, mask: npt.NDArray[np.bool_], copy: bool = False):
+        self.unit = unit
+        super().__init__(values, mask, copy=copy)
+
+    @classmethod
+    def _from_sequence(cls, scalars, *, dtype=None, copy: bool = False):
+        values, mask = cls._coerce_to_array(scalars, dtype=dtype, copy=copy)
+        return cls(unit=dtype.unit, values=values, mask=mask)
+
+    def _arith_method(self, other, op):
+        pd_op = ops.get_array_op(op)
+        self_q = Quantity(value=self._data, unit=self.dtype.unit)
+        mask = self._mask
+        if isinstance(other, QuantityArray):
+            other_q = Quantity(value=other._data, unit=other.dtype.unit)
+            mask |= other._mask
+        elif isinstance(other, Quantity | float | int):
+            other_q = other
+        result = pd_op(self_q, other_q)
+        if not isinstance(result, Quantity):
+            result = Quantity(value=result, unit="")
+        return self._maybe_mask_result(result, mask)
+
+    def _maybe_mask_result(self, result: Quantity, mask: np.ndarray):
+        if not isinstance(result, Quantity):
+            result = Quantity(value=result, unit=self.unit)
+        return QuantityArray(result.unit, result.value, mask, copy=False)
+
+    def copy(self):
+        data = self._data.copy()
+        mask = self._mask.copy()
+        return self.__class__(unit=self.unit, values=data, mask=mask)
+
+    def to(self, other_unit: str):
+        new_value = Quantity(value=self._data, unit=self.unit).to(other_unit).value
+        return self.__class__(value=new_value, unit=other_unit)
+
+    def __repr__(self):
+        return repr(Quantity(value=self._data, unit=self.unit))
+
+    def __getitem__(self, item):
+        item = check_array_indexer(self, item)
+
+        newmask = self._mask[item]
+        if is_bool(newmask):
+            # This is a scalar indexing
+            if newmask:
+                return self.dtype.na_value
+            return Quantity(value=self._data[item], unit=self.unit)
+
+        return self.__class__(self.unit, self._data[item], newmask)
+
+    def take(
+        self,
+        indexer,
+        *,
+        allow_fill: bool = False,
+        fill_value=None,
+        axis=0,
+    ):
+        # we always fill with 1 internally
+        # to avoid upcasting
+        data_fill_value = self._internal_fill_value if isna(fill_value) else fill_value
+        result = take(
+            self._data,
+            indexer,
+            fill_value=data_fill_value,
+            allow_fill=allow_fill,
+            axis=axis,
+        )
+
+        mask = take(self._mask, indexer, fill_value=True, allow_fill=allow_fill, axis=axis)
+
+        # if we are filling
+        # we only fill where the indexer is null
+        # not existing missing values
+        # TODO(jreback) what if we have a non-na float as a fill value?
+        if allow_fill and notna(fill_value):
+            fill_mask = np.asarray(indexer) == -1
+            result[fill_mask] = fill_value
+            mask = mask ^ fill_mask
+
+        return self.__class__(self.unit, result, mask)
+
+    @classmethod
+    def _concat_same_type(
+        cls,
+        to_concat,
+        axis=0,
+    ):
+        unit = to_concat[0].unit
+        if not all(x.unit == unit for x in to_concat):
+            raise ValueError("Can only concatenate Quantity with the same unit")
+        data = np.concatenate([x._data for x in to_concat], axis=axis)
+        mask = np.concatenate([x._mask for x in to_concat], axis=axis)
+        return cls(unit, data, mask)
+
+
+@pd.api.extensions.register_series_accessor("qt")
+class QuantityAccessor:
+    def __init__(self, pandas_obj: pd.Series):
+        self._obj = pandas_obj
+
+    def to(self, other_unit: str):
+        new_value = Quantity(value=self._obj.to_numpy(), unit=self._obj.dtype.unit).to(other_unit).value
+        return pd.Series(new_value, index=self._obj.index, dtype=QuantityDtype(unit=other_unit))
+
+
+@pd.api.extensions.register_dataframe_accessor("qt")
+class QuantityAccessor:
+    def __init__(self, pandas_obj: pd.DataFrame):
+        self._obj = pandas_obj
+
+    def to(self, other_unit: str):
+        if not all(isinstance(dtype, QuantityDtype) for dtype in self._obj.dtypes.values):
+            raise ValueError("Can only convert a DataFrame of Quantity")
+        if len(set(self._obj.dtypes.values)) != 1:
+            raise ValueError("Can only convert a DataFrame of Quantity with the same unit")
+
+        unit = self._obj.dtypes.values[0].unit
+        new_value = Quantity(value=self._obj.to_numpy(), unit=unit).to(other_unit).value
+        return pd.DataFrame(
+            new_value, index=self._obj.index, columns=self._obj.columns, dtype=QuantityDtype(unit=other_unit)
+        )
+
+    def find(self, unit: str | None = None, category: str | None = None, i_s_units: ISUnits | str | None = None):
+        if not any([unit, category, i_s_units]):
+            return self._obj[[col for col, dtype in self._obj.dtypes.items() if isinstance(dtype, QuantityDtype)]]
+
+        if unit:
+            return self._obj[self._obj.dtypes[self._obj.dtypes == QuantityDtype(unit)].index]
+        if isinstance(i_s_units, str):
+            i_s_units = ISUnits.from_str(i_s_units)
+        cols = []
+        for col, dtype in self._obj.dtypes.items():
+            if isinstance(dtype, QuantityDtype):
+                col_i_s_units, _, col_category = Quantity.get_unit_info(dtype.unit)
+                if (category and col_category == category) or (i_s_units and col_i_s_units == i_s_units):
+                    cols.append(col)
+        return self._obj[cols]

dash_pydantic_utils/quantity/quantity.py

@@ -0,0 +1,462 @@
+import re
+from collections.abc import Mapping
+from copy import deepcopy
+from functools import lru_cache
+from itertools import permutations
+from typing import ClassVar, TypedDict, Union
+
+from pydantic import BaseModel, ConfigDict, field_validator
+
+PREFIX_MULTIPLIERS = {
+    "n": 1e-9,
+    "u": 1e-6,
+    "m": 1e-3,
+    "c": 1e-2,
+    "d": 1e-1,
+    "D": 1e1,
+    "h": 1e2,
+    "k": 1e3,
+    "M": 1e6,
+    "G": 1e9,
+    "T": 1e12,
+}
+
+
+class ISUnits(BaseModel):
+    """International system units + money unit."""
+
+    kg: int = 0
+    m: int = 0
+    s: int = 0
+    A: int = 0
+    K: int = 0
+    mol: int = 0
+    cd: int = 0
+    """Extend IS units to money quantities."""
+    USD: int = 0
+
+    model_config = ConfigDict(extra="forbid")
+
+    def is_empty(self) -> bool:
+        """Check if the model is empty."""
+        return all(getattr(self, field) == 0 for field in self.model_fields)
+
+    def __hash__(self):
+        """The hash function."""
+        return hash(frozenset(self.model_dump().items()))
+
+    def __mul__(self, other: "ISUnits") -> "ISUnits":
+        """Multiply two IS units."""
+        return self.__class__(**{field: getattr(self, field) + getattr(other, field) for field in self.model_fields})
+
+    def __truediv__(self, other: "ISUnits") -> "ISUnits":
+        """Divide two IS units."""
+        return self.__class__(**{field: getattr(self, field) - getattr(other, field) for field in self.model_fields})
+
+    def __pow__(self, other: int) -> "ISUnits":
+        """Raise to power."""
+        return self.__class__(**{field: getattr(self, field) * other for field in self.model_fields})
+
+    def __repr__(self) -> str:
+        """Representation."""
+        return f"ISUnits({self})"
+
+    def __str__(self) -> str:
+        """String representation."""
+        return "*".join([unit + (f"^{pow}" if pow != 1 else "") for unit, pow in self.model_dump().items() if pow])
+
+    @classmethod
+    def from_str(cls, unit_str: str) -> "ISUnits":
+        """Create from string."""
+        return cls(
+            **{
+                unit: int(pow) if pow else 1
+                for unit, pow in re.findall(r"(kg|m|s|K|A|mol|cd|USD)(?:\^(\-*\d+))*(?:\*|$)", unit_str)
+            }
+        )
+
+
+class NameData(TypedDict):
+    """Name data."""
+
+    unit: str
+    category: str
+
+
+class Quantity(BaseModel):
+    """Quantity model."""
+
+    value: float
+    unit: str | None
+
+    """Conversion factors from unit to IS unit."""
+    conversion: ClassVar[dict[ISUnits, Mapping[str, float]]] = {
+        # Unitless
+        ISUnits(): {
+            "": 1,
+            "%": 0.01,
+            "‰": 0.001,
+        },
+        # Money
+        ISUnits(USD=1): {
+            "USD": 1,
+            "EUR": 1.07,
+            "GBP": 1.30,
+            "AUD": 0.67,
+            "JPY": 0.0067,
+            "CAD": 0.73,
+            "CHF": 1.16,
+            "CNY": 0.14,
+            "NZD": 0.61,
+            "ZAR": 0.057,
+            "INR": 0.012,
+        },
+        # Length
+        ISUnits(m=1): {
+            "m": 1,
+            "mi": 1609.344,
+            "NM": 1852,
+            "ft": 0.3048,
+            "in": 0.0254,
+        },
+        # Mass
+        ISUnits(kg=1): {
+            "kg": 1,
+            "g": 0.001,
+            "lb": 0.453592,
+            "oz": 0.0283495,
+        },
+        # Time
+        ISUnits(s=1): {
+            "s": 1,
+            "min": 60,
+            "h": 3600,
+            "d": 86400,
+        },
+        # Force
+        ISUnits(kg=1, m=1, s=-2): {
+            "N": 1,
+        },
+        # Pressure
+        ISUnits(kg=1, m=-1, s=-2): {
+            "Pa": 1,
+            "atm": 101325,
+            "psi": 6894.76,
+        },
+        # Energy
+        ISUnits(kg=1, m=2, s=-2): {
+            "J": 1,
+            "Wh": 3600,
+            "cal": 4.184,
+        },
+        # Frequency
+        ISUnits(s=-1): {
+            "Hz": 1,
+        },
+        # Temperature
+        ISUnits(K=1): {
+            "K": 1,
+            "C": (1, 273.15),
+            "F": (5 / 9, 273.15 - 5 / 9 * 32),
+        },
+        # Power
+        ISUnits(kg=1, m=2, s=-3): {
+            "W": 1,
+            "hp": 745.7,
+        },
+        # Area
+        ISUnits(m=2): {
+            "m^2": 1,
+            "ha": 10000,
+            "acre": 4046.86,
+            "in^2": 0.00064516,
+            "ft^2": 0.092903,
+            "mi^2": 2589988.1,
+        },
+        # Volume
+        ISUnits(m=3): {
+            "m^3": 1,
+            "L": 0.001,
+            "gal": 0.00378541,
+        },
+        # Speed
+        ISUnits(m=1, s=-1): {
+            "m/s": 1,
+            "mph": 0.44704,
+            "kph": 1 / 3.6,
+        },
+        # Acceleration
+        ISUnits(m=1, s=-2): {
+            "m/s^2": 1,
+        },
+    }
+    names: ClassVar[dict[ISUnits, NameData]] = {
+        ISUnits(): {"category": "Unitless", "unit": ""},
+        ISUnits(USD=1): {"category": "Money", "unit": "USD"},
+        ISUnits(m=1): {"category": "Length", "unit": "m"},
+        ISUnits(kg=1): {"category": "Mass", "unit": "kg"},
+        ISUnits(s=1): {"category": "Time", "unit": "s"},
+        ISUnits(K=1): {"category": "Temperature", "unit": "K"},
+        ISUnits(s=-1): {"category": "Frequency", "unit": "Hz"},
+        ISUnits(kg=1, m=1, s=-2): {"category": "Force", "unit": "N"},
+        ISUnits(kg=1, m=-1, s=-2): {"category": "Pressure", "unit": "Pa"},
+        ISUnits(kg=1, m=2, s=-2): {"category": "Energy", "unit": "J"},
+        ISUnits(kg=1, m=2, s=-3): {"category": "Power", "unit": "W"},
+        ISUnits(m=2): {"category": "Area", "unit": "m^2"},
+        ISUnits(m=3): {"category": "Volume", "unit": "m^3"},
+        ISUnits(m=1, s=-1): {"category": "Speed", "unit": "m/s"},
+        ISUnits(m=1, s=-2): {"category": "Acceleration", "unit": "m/s^2"},
+    }
+
+    def __init__(self, value: float, unit: str):
+        super().__init__(value=value, unit=unit)
+
+    @property
+    def unit_multiplier(self) -> tuple[float, float]:
+        """Get multiplier."""
+        return self.get_unit_info(self.unit)[1]
+
+    @property
+    def i_s_units(self) -> ISUnits:
+        """Get IS units."""
+        return self.get_unit_info(self.unit)[0]
+
+    @property
+    def category(self) -> str:
+        """Get category."""
+        return self.get_unit_info(self.unit)[2]
+
+    @classmethod
+    @lru_cache
+    def get_unit_info(cls, unit: str) -> tuple[ISUnits, tuple[float, float], str]:
+        """Get information about a given unit."""
+        i_s_pattern = re.compile("^((kg|m|s|K|USD|A|mol|cd)(?:\^(\-*\d+))*(?:\*|$))+$")
+        # IS units repr
+        if re.match(i_s_pattern, unit):
+            i_s_units = ISUnits.from_str(unit)
+            return i_s_units, (1, 0), cls.names.get(i_s_units, {}).get("category", "Quantity")
+
+        all_units = sum([list(units) for units in cls.conversion.values()], [])
+
+        def trim_prefixes(unit: str) -> str:
+            if unit in all_units:
+                return unit, None
+            for prefix in PREFIX_MULTIPLIERS:
+                if unit.startswith(prefix):
+                    base_unit = unit.removeprefix(prefix)
+                    if base_unit in all_units:
+                        return base_unit, prefix
+            raise ValueError(f"Unsupported unit: {unit}")
+
+        i_s_units = ISUnits()
+        factor, base = 1.0, 0.0
+        for i, unit_ in enumerate(unit.split("/")):
+            base_unit, prefix = trim_prefixes(unit_)
+            i_s_units_, conversion_ = next(
+                (i_s_units, group[base_unit]) for i_s_units, group in cls.conversion.items() if base_unit in group
+            )
+            if isinstance(conversion_, tuple):
+                factor_, base_ = conversion_
+                if i > 0 and base_ != 0:
+                    raise NotImplementedError("Not supported: unit with non-zero base in denominator")
+            else:
+                factor_, base_ = conversion_, 0
+
+            if prefix:
+                prefix_multiplier = PREFIX_MULTIPLIERS[prefix]
+                # Handle cases where prefix multiplier is brought to a power (e.g area, volume)
+                if (
+                    re.match(i_s_pattern, base_unit)
+                    and sum(v != 0 for v in i_s_units_.model_dump().values()) == 1
+                    and abs(pow := next(v for v in i_s_units_.model_dump().values() if v != 0)) > 1
+                ):
+                    prefix_multiplier = prefix_multiplier**pow
+
+                factor_ *= prefix_multiplier
+
+            if i == 0:
+                i_s_units = i_s_units_
+                factor = factor_
+                base = base_
+            else:
+                i_s_units /= i_s_units_
+                factor /= factor_
+
+        return i_s_units, (factor, base), cls.names.get(i_s_units, {}).get("category", "Quantity")
+
+    @property
+    def unit_parts(self) -> dict[ISUnits, str]:
+        """Get unit parts."""
+        return {self.get_unit_info(part)[0]: part for part in self.unit.split("/")}
+
+    @field_validator("unit")
+    def validate_unit(cls, unit: str) -> str:
+        """Validate unit."""
+        _ = cls.get_unit_info(unit)
+        return unit
+
+    def _to_default_unit(self) -> float:
+        """Convert to default unit."""
+        factor, base = self.unit_multiplier
+        return self.value * factor + base
+
+    def _from_default_unit(self, value) -> float:
+        """Convert from default unit."""
+        factor, base = self.unit_multiplier
+        return (value - base) / factor
+
+    def to(self, unit: str) -> "Quantity":
+        """Convert to another unit."""
+        if self.get_unit_info(unit)[0] != self.i_s_units:
+            self_repr = self.category if self.category != "Quantity" else str(self.unit)
+            other_info = self.get_unit_info(unit)
+            other_repr = other_info[2] if other_info[2] != "Quantity" else str(unit)
+            raise ValueError(f"Cannot convert between different types: {self_repr} <-/-> {other_repr}.")
+        default_unit_value = self._to_default_unit()
+        factor, base = self.get_unit_info(unit)[1]
+        return self.__class__(unit=unit, value=(default_unit_value - base) / factor)
+
+    def __add__(self, other: Union["Quantity", float, int]) -> "Quantity":
+        """Add two quantities, they need to be of the same category."""
+        if isinstance(other, float | int):
+            return self.__class__(unit=self.unit, value=self.value + other)
+
+        if other.i_s_units != self.i_s_units:
+            raise ValueError("Cannot add quantities of different types.")
+
+        return self.__class__(
+            unit=self.unit,
+            value=self._from_default_unit(self._to_default_unit() + other._to_default_unit()),
+        )
+
+    def __sub__(self, other: Union["Quantity", float, int]) -> "Quantity":
+        """Add two quantities, they need to be of the same category."""
+        if isinstance(other, float | int):
+            return self.__class__(unit=self.unit, value=self.value + other)
+
+        if self.i_s_units != other.i_s_units:
+            raise ValueError("Cannot subtract quantities of different types.")
+
+        return self.__class__(
+            unit=self.unit,
+            value=self._from_default_unit(self._to_default_unit() - other._to_default_unit()),
+        )
+
+    def _get_output_unit(self, other: Union["Quantity", float, int], out_i_s_units: ISUnits) -> str:
+        all_parts = deepcopy(self.unit_parts)
+        if isinstance(other, Quantity):
+            all_parts |= other.unit_parts
+
+        if out_i_s_units in all_parts:
+            return all_parts[out_i_s_units]
+
+        unit_parts = next(
+            (
+                (all_parts.get(i1) or v1["unit"], all_parts.get(i2) or v2["unit"])
+                for (i1, v1), (i2, v2) in permutations(self.names.items(), 2)
+                if i1 / i2 == out_i_s_units and (i1 in all_parts or i2 in all_parts)
+            ),
+            None,
+        )
+
+        if unit_parts:
+            return "/".join(unit_parts)
+
+        return None
+
+    def __mul__(self, other: Union["Quantity", float, int]) -> "Quantity":
+        """Multiply a quantity with a number."""
+        if isinstance(other, float | int):
+            return self.__class__(unit=self.unit, value=self.value * other)
+
+        i_s_units = self.i_s_units * other.i_s_units
+        out = self.__class__(
+            value=self._to_default_unit() * other._to_default_unit(),
+            unit=self.names.get(i_s_units, {}).get("unit", str(i_s_units)),
+        )
+        output_unit = self._get_output_unit(other, i_s_units)
+        if output_unit is not None:
+            out = out.to(output_unit)
+        return out
+
+    def __rmul__(self, other: float | int) -> "Quantity":
+        """Multiply a quantity with a number."""
+        return self.__mul__(other)
+
+    def __truediv__(self, other: Union["Quantity", float, int]) -> Union["Quantity", float]:
+        """Divide a quantity with a number or another quantity."""
+        if isinstance(other, float | int):
+            return self.__class__(unit=self.unit, value=self.value / other)
+
+        i_s_units = self.i_s_units / other.i_s_units
+        out = self.__class__(
+            value=self._to_default_unit() / other._to_default_unit(),
+            unit=self.names.get(i_s_units, {}).get("unit", str(i_s_units)),
+        )
+        output_unit = self._get_output_unit(other, i_s_units)
+        if output_unit is not None:
+            out = out.to(output_unit)
+        return out
+
+    def __rtruediv__(self, other: float | int):
+        """Divide a number by a quantity."""
+        if not isinstance(other, float | int):
+            raise TypeError("Can only divide numbers by quantities")
+
+        i_s_units = self.i_s_units**-1
+        return self.__class__(
+            value=other / self._to_default_unit(),
+            unit=self.names.get(i_s_units, {}).get("unit", str(i_s_units)),
+        )
+
+    def __pow__(self, other: int) -> "Quantity":
+        """Raise a quantity to a power."""
+        if not isinstance(other, int):
+            raise TypeError("Can only raise a quantity to an integer power")
+
+        i_s_units = self.i_s_units**other
+        return self.__class__(
+            value=self._to_default_unit() ** other,
+            unit=self.names.get(i_s_units, {}).get("unit", str(i_s_units)),
+        )
+
+    def __eq__(self, other: "Quantity") -> bool:
+        """Equality."""
+        if not isinstance(other, Quantity) or self.i_s_units != other.i_s_units:
+            return False
+        return self._to_default_unit() == other._to_default_unit()
+
+    def __neg__(self) -> "Quantity":
+        """Negate."""
+        return self.__class__(unit=self.unit, value=-self.value)
+
+    def __repr__(self) -> str:
+        """Representation."""
+        return f"{self.category}({self})"
+
+    def __str__(self) -> str:
+        """String representation."""
+        base = f"{self.value:.3f}" if abs(self.value) >= 1e-2 or self.value == 0 else f"{self.value:.2e}"  # noqa: PLR2004
+        if "." in base:
+            base = base.rstrip("0").rstrip(".")
+        return f"{base} {self.unit}" if self.unit else base
+
+    @classmethod
+    def register_unit_rates(
+        cls,
+        i_s_units: ISUnits | str,
+        unit_name: str,
+        rate: float = 1.0,
+        category: str | None = None,
+    ) -> None:
+        """Set currency rates."""
+        if isinstance(i_s_units, str):
+            i_s_units = ISUnits.from_str(i_s_units)
+
+        if i_s_units not in cls.conversion:
+            cls.conversion[i_s_units] = {}
+        cls.conversion[i_s_units][unit_name] = rate
+        if i_s_units not in cls.names:
+            cls.names[i_s_units] = {"category": category, "unit": unit_name}
+
+        cls.get_unit_info.cache_clear()

dash_pydantic_utils/types.py

@@ -0,0 +1,91 @@
+from datetime import date, time
+from enum import Enum
+from numbers import Number
+from types import UnionType
+from typing import Annotated, Literal, Union, get_args, get_origin
+
+from pydantic import BaseModel
+from pydantic.fields import FieldInfo
+
+from dash_pydantic_utils.common import get_non_null_annotation, is_subclass
+
+SEP = ":"
+
+
+class Type(Enum):
+    """Types of fields."""
+
+    SCALAR = "scalar"
+    LITERAL = "literal"
+    MODEL = "model"
+    UNKNOWN = "unknown"
+    DISCRIMINATED_MODEL = "discriminated_model"
+    MODEL_LIST = "model_list"
+    SCALAR_LIST = "scalar_list"
+    LITERAL_LIST = "literal_list"
+    UNKOWN_LIST = "unknown_list"
+    DISCRIMINATED_MODEL_LIST = "discriminated_model_list"
+    MODEL_DICT = "model_dict"
+    SCALAR_DICT = "scalar_dict"
+    LITERAL_DICT = "literal_dict"
+    UNKOWN_DICT = "unkown_dict"
+    DISCRIMINATED_MODEL_DICT = "discriminated_model_dict"
+
+    @classmethod
+    def classify(cls, annotation: type, discriminator: str | None = None, depth: int = 0) -> bool:  # noqa: PLR0911, PLR0912
+        """Classify a value as a field type."""
+        annotation = get_non_null_annotation(annotation)
+
+        if get_origin(annotation) is Annotated and get_origin(get_args(annotation)[0]) in [Union, UnionType]:
+            if discriminator is None:
+                discriminator = next(
+                    (f.discriminator for f in get_args(annotation)[1:] if isinstance(f, FieldInfo)), None
+                )
+            annotation = get_args(annotation)[0]
+
+        if is_subclass(annotation, str | Number | bool | date | time):
+            return cls.SCALAR
+
+        if (get_origin(annotation) == Literal) | is_subclass(annotation, Enum):
+            return cls.LITERAL
+
+        if is_subclass(annotation, BaseModel):
+            return cls.MODEL
+
+        if get_origin(annotation) in [Union, UnionType]:
+            if discriminator and all(is_subclass(x, BaseModel) for x in get_args(annotation)):
+                return cls.DISCRIMINATED_MODEL
+            if all(is_subclass(x, str | Number) for x in get_args(annotation)):
+                return cls.SCALAR
+
+        if get_origin(annotation) is list and not depth:
+            ann_args = get_args(annotation)
+            if not ann_args:
+                return cls.UNKOWN_LIST
+            args_type = Type.classify(ann_args[0], depth=1)
+            if args_type == Type.SCALAR:
+                return cls.SCALAR_LIST
+            if args_type == Type.LITERAL:
+                return cls.LITERAL_LIST
+            if args_type == Type.MODEL:
+                return cls.MODEL_LIST
+            if args_type == Type.DISCRIMINATED_MODEL:
+                return cls.DISCRIMINATED_MODEL_LIST
+            return cls.UNKOWN_LIST
+
+        if get_origin(annotation) is dict and not depth:
+            ann_args = get_args(annotation)
+            if not ann_args:
+                return cls.UNKOWN_DICT
+            args_type = Type.classify(ann_args[1], depth=1)
+            if args_type == Type.SCALAR:
+                return cls.SCALAR_DICT
+            if args_type == Type.LITERAL:
+                return cls.LITERAL_DICT
+            if args_type == Type.MODEL:
+                return cls.MODEL_DICT
+            if args_type == Type.DISCRIMINATED_MODEL:
+                return cls.DISCRIMINATED_MODEL_DICT
+            return cls.UNKOWN_DICT
+
+        return cls.UNKNOWN

dash_pydantic_utils-0.14.0.dist-info/METADATA

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: dash-pydantic-utils
+Version: 0.14.0
+Summary: Utils for dash-pydantic-form, allows to use the utils in other places without requiring Dash.
+Project-URL: Source, https://github.com/RenaudLN/dash-pydantic-form
+Author-email: Renaud Lainé <renaudlaine31@gmail.com>
+License: The MIT License (MIT)
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in
+        all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+        THE SOFTWARE.
+License-File: LICENSE
+Requires-Python: <3.13,>=3.10
+Requires-Dist: pydantic==2.*
+Provides-Extra: dev
+Requires-Dist: dash[testing]; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: pandas
+Requires-Dist: numpy; extra == 'pandas'
+Requires-Dist: pandas; extra == 'pandas'

dash_pydantic_utils-0.14.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+dash_pydantic_utils/__init__.py,sha256=7jzlGgYM7HHEm_M8HzETRTSjj0iHBJdtWiq42n_pO3o,810
+dash_pydantic_utils/common.py,sha256=EFZQQhD93neIVr6amMqU5xVcgNGG-3UwDQ5-OdAfVaY,2151
+dash_pydantic_utils/path.py,sha256=KCSQqUZZ5d14Ph2a-76lCOq-ISvOo2KtTrsW7QNz_ZU,11249
+dash_pydantic_utils/types.py,sha256=9MLmW5Ku5J0MLdv_-uDmZ3E-cL9l-KLN8206P1PczbA,3356
+dash_pydantic_utils/quantity/__init__.py,sha256=cynvB1zP7199Dud7otg9DTbsRXX6L1CvVXOLtlO_USY,281
+dash_pydantic_utils/quantity/pandas.py,sha256=VKUAlsatuqLsF0fcZ_KgJ8k4562KPYfAUAxacCus-ac,10041
+dash_pydantic_utils/quantity/quantity.py,sha256=SbaO3F5V5wWOVUv5bHfMe2IfrCaqsUB7DmD9D3hTVKk,15582
+dash_pydantic_utils-0.14.0.dist-info/METADATA,sha256=_xR1LFZs4jG-D1FETNINTAg7_UanwnbG7XMZ5-kKXjA,1818
+dash_pydantic_utils-0.14.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dash_pydantic_utils-0.14.0.dist-info/licenses/LICENSE,sha256=j3Flk3DFJo2aHclipGIyVA6PymNGJYbY76qVqrSSogg,1046
+dash_pydantic_utils-0.14.0.dist-info/RECORD,,

dash_pydantic_utils-0.14.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dash_pydantic_utils-0.14.0.dist-info/licenses/LICENSE

@@ -0,0 +1,19 @@
+The MIT License (MIT)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.