Coverage for install/scipp/typing.py: 0%

1# SPDX-License-Identifier: BSD-3-Clause 

2# Copyright (c) 2023 Scipp contributors (https://github.com/scipp) 

3# @file 

4# @author Neil Vaytet 

5from __future__ import annotations 

6 

7import typing as _std_typing 

8 

9import numpy.typing as npt 

10 

11from ._scipp import core as sc 

12from .core.cpp_classes import DataArray, Dataset, DType, Variable 

13from .core.data_group import DataGroup 

14 

15 

16def is_scalar(obj: VariableLike) -> bool: 

17 """ 

18 Return True if the input is a scalar. 

19 """ 

20 return obj.ndim == 0 

21 

22 

23def has_vector_type(obj: Variable | DataArray) -> bool: 

24 """ 

25 Return True if the object dtype is vector3. 

26 """ 

27 return obj.dtype == sc.DType.vector3 # type: ignore[no-any-return] 

28 

29 

30def has_string_type(obj: Variable | DataArray) -> bool: 

31 """ 

32 Return True if the object dtype is string. 

33 """ 

34 return obj.dtype == sc.DType.string # type: ignore[no-any-return] 

35 

36 

37def has_datetime_type(obj: Variable | DataArray) -> bool: 

38 """ 

39 Return True if the object dtype is datetime64. 

40 """ 

41 return obj.dtype == sc.DType.datetime64 # type: ignore[no-any-return] 

42 

43 

44def has_numeric_type(obj: Variable | DataArray) -> bool: 

45 """ 

46 Return False if the dtype is either vector or string. 

47 """ 

48 return (not has_vector_type(obj)) and (not has_string_type(obj)) 

49 

50 

51Dims: _std_typing.TypeAlias = str | _std_typing.Sequence[str] | None 

52""" 

53Describes dimensions to operate on. 

54 

55Can be a string (for a single dimension) or a sequence of strings (multiple dimensions). 

56A value of ``None`` indicates "all dimensions." 

57""" 

58 

59VariableLike: _std_typing.TypeAlias = ( 

60 Variable | DataArray | Dataset | DataGroup[_std_typing.Any] 

61) 

62"""Any object that behaves like a :class:`scipp.Variable`. 

63 

64More concretely, an array with labeled dimensions which supports slicing and 

65arithmetic: 

66 

67- :class:`scipp.DataArray` 

68- :class:`scipp.DataGroup` 

69- :class:`scipp.Dataset` 

70- :class:`scipp.Variable` 

71""" 

72 

73MetaDataMap: _std_typing.TypeAlias = _std_typing.MutableMapping[str, Variable] 

74"""dict-like object mapping dimension labels to Variables.""" 

75 

76VariableLikeType = _std_typing.TypeVar( 

77 'VariableLikeType', Variable, DataArray, Dataset, DataGroup[_std_typing.Any] 

78) 

79"""TypeVar for use in annotations. 

80 

81Should be hidden in rendered documentation in favor of VariableLike. 

82""" 

83 

84DTypeLike: _std_typing.TypeAlias = npt.DTypeLike | DType 

85"""Anything that can be interpreted as a dtype. 

86 

87This includes 

88 

89- :class:`scipp.DType` 

90- everything that is supported by 

91 `numpy.DTypeLike <https://numpy.org/devdocs/reference/typing.html#numpy.typing.DTypeLike>`_ 

92 e.g. 

93 

94 - :class:`numpy.dtype` 

95 - :class:`type` objects like :class:`int` and :class:`float` 

96 - names of dtypes as strings like ``'int32'`` and ``'float64'`` 

97""" 

98 

99if _std_typing.TYPE_CHECKING: 

100 from enum import Enum 

101 

102 class ellipsis(Enum): 

103 Ellipsis = "..." 

104 

105else: 

106 ellipsis = type(Ellipsis) 

107 

108ScippIndex: _std_typing.TypeAlias = ( 

109 ellipsis 

110 | int 

111 | tuple[int, ...] 

112 | slice 

113 | list[int] 

114 | npt.NDArray[_std_typing.Any] 

115 | tuple[str, int | slice | list[int] | npt.NDArray[_std_typing.Any] | Variable] 

116 | Variable 

117)