Skip to content

Validators

Validation utilities for PyEyesWeb.

This module provides common validation functions used across multiple PyEyesWeb modules to ensure consistent error handling.

validate_and_normalize_filter_params(filter_params)

Validate and normalize filter parameters.

Parameters:

Name Type Description Default
filter_params tuple / list or None

Filter parameters as (lowcut, highcut, fs) or None

 required

Returns:

Type Description
tuple or None

Validated (lowcut, highcut, fs) tuple or None if input was None
Source code in pyeyesweb/utils/validators.py 
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
def validate_and_normalize_filter_params(filter_params):
    """Validate and normalize filter parameters.

    Parameters
    ----------
    filter_params : tuple/list or None
        Filter parameters as (lowcut, highcut, fs) or None

    Returns
    -------
    tuple or None
        Validated (lowcut, highcut, fs) tuple or None if input was None
    """
    if filter_params is None:
        return None

    # Import here to avoid circular dependency
    from pyeyesweb.utils.signal_processing import validate_filter_params

    filter_params = validate_filter_params_tuple(filter_params)
    lowcut, highcut, fs = validate_filter_params(*filter_params)
    return (lowcut, highcut, fs)

validate_boolean(value, name)

Validate boolean parameter.

Parameters:

Name Type Description Default
value any

Value to validate

 required
name str

Parameter name for error messages

 required

Returns:

Type Description
bool

Validated boolean value

Raises:

Type Description
TypeError

If value is not a boolean

Examples:

>>> validate_boolean(True, 'use_filter')
True
>>> validate_boolean(1, 'output_phase')
TypeError: output_phase must be boolean, got int
Source code in pyeyesweb/utils/validators.py 
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
def validate_boolean(value, name):
    """Validate boolean parameter.

    Parameters
    ----------
    value : any
        Value to validate
    name : str
        Parameter name for error messages

    Returns
    -------
    bool
        Validated boolean value

    Raises
    ------
    TypeError
        If value is not a boolean

    Examples
    --------
    >>> validate_boolean(True, 'use_filter')
    True
    >>> validate_boolean(1, 'output_phase')
    TypeError: output_phase must be boolean, got int
    """
    if not isinstance(value, bool):
        raise TypeError(f"{name} must be boolean, got {type(value).__name__}")
    return value

validate_filter_params_tuple(value, name='filter_params')

Validate filter parameters tuple structure.

Ensures the value is a tuple/list with exactly 3 numeric elements before passing to validate_filter_params for frequency validation.

Parameters:

Name Type Description Default
value any

Value to validate as filter parameters tuple

 required
name str

Parameter name for error messages (default: 'filter_params')

 'filter_params'

Returns:

Type Description
tuple

Validated tuple of (lowcut, highcut, fs)

Raises:

Type Description
TypeError

If value is not a tuple/list or contains non-numeric elements
ValueError

If value doesn't have exactly 3 elements

Examples:

>>> validate_filter_params_tuple((1.0, 10.0, 100.0))
(1.0, 10.0, 100.0)
>>> validate_filter_params_tuple([1, 10, 100])
(1, 10, 100)
>>> validate_filter_params_tuple("invalid")
TypeError: filter_params must be a tuple or list, got str
Source code in pyeyesweb/utils/validators.py 
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
def validate_filter_params_tuple(value, name='filter_params'):
    """Validate filter parameters tuple structure.

    Ensures the value is a tuple/list with exactly 3 numeric elements
    before passing to validate_filter_params for frequency validation.

    Parameters
    ----------
    value : any
        Value to validate as filter parameters tuple
    name : str, optional
        Parameter name for error messages (default: 'filter_params')

    Returns
    -------
    tuple
        Validated tuple of (lowcut, highcut, fs)

    Raises
    ------
    TypeError
        If value is not a tuple/list or contains non-numeric elements
    ValueError
        If value doesn't have exactly 3 elements

    Examples
    --------
    >>> validate_filter_params_tuple((1.0, 10.0, 100.0))
    (1.0, 10.0, 100.0)
    >>> validate_filter_params_tuple([1, 10, 100])
    (1, 10, 100)
    >>> validate_filter_params_tuple("invalid")
    TypeError: filter_params must be a tuple or list, got str
    """
    if not isinstance(value, (tuple, list)):
        raise TypeError(f"{name} must be a tuple or list, got {type(value).__name__}")

    if len(value) != 3:
        raise ValueError(f"{name} must have 3 elements (lowcut, highcut, fs), got {len(value)}")

    if not all(isinstance(x, (int, float)) for x in value):
        raise TypeError(f"{name} must contain only numbers")

    return tuple(value)

validate_integer(value, name, min_val=None, max_val=None)

Validate integer parameter with optional bounds checking.

Parameters:

Name Type Description Default
value any

Value to validate

 required
name str

Parameter name for error messages

 required
min_val int

Minimum allowed value (inclusive)

 None
max_val int

Maximum allowed value (inclusive)

 None

Returns:

Type Description
int

Validated integer value

Raises:

Type Description
TypeError

If value is not an integer
ValueError

If value is outside specified bounds

Examples:

>>> validate_integer(100, 'sensitivity', min_val=1, max_val=10000)
100
>>> validate_integer(0, 'max_length', min_val=1)
ValueError: max_length must be >= 1, got 0
Source code in pyeyesweb/utils/validators.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
def validate_integer(value, name, min_val=None, max_val=None):
    """Validate integer parameter with optional bounds checking.

    Parameters
    ----------
    value : any
        Value to validate
    name : str
        Parameter name for error messages
    min_val : int, optional
        Minimum allowed value (inclusive)
    max_val : int, optional
        Maximum allowed value (inclusive)

    Returns
    -------
    int
        Validated integer value

    Raises
    ------
    TypeError
        If value is not an integer
    ValueError
        If value is outside specified bounds

    Examples
    --------
    >>> validate_integer(100, 'sensitivity', min_val=1, max_val=10000)
    100
    >>> validate_integer(0, 'max_length', min_val=1)
    ValueError: max_length must be >= 1, got 0
    """
    if not isinstance(value, int):
        raise TypeError(f"{name} must be an integer, got {type(value).__name__}")

    if min_val is not None and value < min_val:
        raise ValueError(f"{name} must be >= {min_val}, got {value}")

    if max_val is not None and value > max_val:
        raise ValueError(f"{name} must be <= {max_val}, got {value}")

    return value

validate_numeric(value, name, min_val=None, max_val=None)

Validate numeric parameter with optional bounds checking.

Parameters:

Name Type Description Default
value any

Value to validate

 required
name str

Parameter name for error messages

 required
min_val float

Minimum allowed value (inclusive)

 None
max_val float

Maximum allowed value (inclusive)

 None

Returns:

Type Description
float

Validated numeric value as float

Raises:

Type Description
TypeError

If value is not numeric (int or float)
ValueError

If value is outside specified bounds

Examples:

>>> validate_numeric(50.0, 'rate_hz', min_val=0.1, max_val=100000)
50.0
>>> validate_numeric(-1, 'phase', min_val=0, max_val=1)
ValueError: phase must be >= 0, got -1
Source code in pyeyesweb/utils/validators.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
def validate_numeric(value, name, min_val=None, max_val=None):
    """Validate numeric parameter with optional bounds checking.

    Parameters
    ----------
    value : any
        Value to validate
    name : str
        Parameter name for error messages
    min_val : float, optional
        Minimum allowed value (inclusive)
    max_val : float, optional
        Maximum allowed value (inclusive)

    Returns
    -------
    float
        Validated numeric value as float

    Raises
    ------
    TypeError
        If value is not numeric (int or float)
    ValueError
        If value is outside specified bounds

    Examples
    --------
    >>> validate_numeric(50.0, 'rate_hz', min_val=0.1, max_val=100000)
    50.0
    >>> validate_numeric(-1, 'phase', min_val=0, max_val=1)
    ValueError: phase must be >= 0, got -1
    """
    if not isinstance(value, (int, float)):
        raise TypeError(f"{name} must be a number, got {type(value).__name__}")

    value = float(value)

    if min_val is not None and value < min_val:
        raise ValueError(f"{name} must be >= {min_val}, got {value}")

    if max_val is not None and value > max_val:
        raise ValueError(f"{name} must be <= {max_val}, got {value}")

    return value

validate_range(value, name, min_val, max_val)

Validate that a value is within a specific range.

Useful for parameters that must be within a specific range like phase_threshold (0-1), percentages (0-100), etc.

Parameters:

Name Type Description Default
value float or int

Value to validate

 required
name str

Parameter name for error messages

 required
min_val float

Minimum allowed value (inclusive)

 required
max_val float

Maximum allowed value (inclusive)

 required

Returns:

Type Description
float

Validated value

Raises:

Type Description
ValueError

If value is outside the specified range

Examples:

>>> validate_range(0.7, 'phase_threshold', 0, 1)
0.7
>>> validate_range(1.5, 'probability', 0, 1)
ValueError: probability must be between 0 and 1, got 1.5
Source code in pyeyesweb/utils/validators.py 
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
def validate_range(value, name, min_val, max_val):
    """Validate that a value is within a specific range.

    Useful for parameters that must be within a specific range like
    phase_threshold (0-1), percentages (0-100), etc.

    Parameters
    ----------
    value : float or int
        Value to validate
    name : str
        Parameter name for error messages
    min_val : float
        Minimum allowed value (inclusive)
    max_val : float
        Maximum allowed value (inclusive)

    Returns
    -------
    float
        Validated value

    Raises
    ------
    ValueError
        If value is outside the specified range

    Examples
    --------
    >>> validate_range(0.7, 'phase_threshold', 0, 1)
    0.7
    >>> validate_range(1.5, 'probability', 0, 1)
    ValueError: probability must be between 0 and 1, got 1.5
    """
    if not min_val <= value <= max_val:
        raise ValueError(f"{name} must be between {min_val} and {max_val}, got {value}")
    return value

validate_window_size(value, name='window_size')

Validate window size parameter.

Standard validation for window sizes used across multiple modules.

Parameters:

Name Type Description Default
value int

Window size value

 required
name str

Parameter name for error messages

 'window_size'

Returns:

Type Description
int

Validated window size
Source code in pyeyesweb/utils/validators.py 
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
def validate_window_size(value, name='window_size'):
    """Validate window size parameter.

    Standard validation for window sizes used across multiple modules.

    Parameters
    ----------
    value : int
        Window size value
    name : str
        Parameter name for error messages

    Returns
    -------
    int
        Validated window size
    """
    return validate_integer(value, name, min_val=1, max_val=10000)