statica 1.4.0__tar.gz → 1.7.0__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.
- {statica-1.4.0/statica.egg-info → statica-1.7.0}/PKG-INFO +151 -96
- {statica-1.4.0 → statica-1.7.0}/README.md +127 -71
- statica-1.7.0/pyproject.toml +73 -0
- statica-1.7.0/pyproject.toml.orig +81 -0
- {statica-1.4.0 → statica-1.7.0}/statica/__init__.py +2 -0
- statica-1.7.0/statica/config.py +21 -0
- {statica-1.4.0 → statica-1.7.0}/statica/core.py +112 -143
- statica-1.7.0/statica/py.typed +0 -0
- {statica-1.4.0 → statica-1.7.0}/statica/validation.py +119 -36
- statica-1.4.0/PKG-INFO +0 -373
- statica-1.4.0/pyproject.toml +0 -94
- statica-1.4.0/setup.cfg +0 -4
- statica-1.4.0/statica/config.py +0 -33
- statica-1.4.0/statica.egg-info/SOURCES.txt +0 -20
- statica-1.4.0/statica.egg-info/dependency_links.txt +0 -1
- statica-1.4.0/statica.egg-info/top_level.txt +0 -1
- statica-1.4.0/tests/test_aliasing.py +0 -143
- statica-1.4.0/tests/test_config.py +0 -221
- statica-1.4.0/tests/test_default_field.py +0 -514
- statica-1.4.0/tests/test_descriptor.py +0 -38
- statica-1.4.0/tests/test_python_behavior.py +0 -39
- statica-1.4.0/tests/test_statica.py +0 -211
- statica-1.4.0/tests/test_validate_or_raise.py +0 -673
- statica-1.4.0/tests/test_validation.py +0 -100
- {statica-1.4.0 → statica-1.7.0}/LICENSE +0 -0
- {statica-1.4.0 → statica-1.7.0}/statica/exceptions.py +0 -0
|
@@ -1,44 +1,43 @@
|
|
|
1
|
-
Metadata-Version: 2.
|
|
1
|
+
Metadata-Version: 2.3
|
|
2
2
|
Name: statica
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.7.0
|
|
4
4
|
Summary: A minimalistic data validation library
|
|
5
|
+
Author: Marcel Kröker
|
|
5
6
|
Author-email: Marcel Kröker <kroeker.marcel@gmail.com>
|
|
6
7
|
License: MIT License
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
8
|
+
|
|
9
|
+
Copyright (c) 2025 mkrd
|
|
10
|
+
|
|
11
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
12
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
13
|
+
in the Software without restriction, including without limitation the rights
|
|
14
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
15
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
16
|
+
furnished to do so, subject to the following conditions:
|
|
17
|
+
|
|
18
|
+
The above copyright notice and this permission notice shall be included in all
|
|
19
|
+
copies or substantial portions of the Software.
|
|
20
|
+
|
|
21
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
22
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
23
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
24
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
25
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
26
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
27
|
+
SOFTWARE.
|
|
28
28
|
Classifier: Programming Language :: Python :: 3
|
|
29
|
-
Classifier: License :: OSI Approved :: MIT License
|
|
30
29
|
Classifier: Operating System :: OS Independent
|
|
31
30
|
Classifier: Intended Audience :: Developers
|
|
32
31
|
Classifier: Programming Language :: Python
|
|
33
32
|
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
34
|
-
Requires-Python:
|
|
33
|
+
Requires-Python: >=3.11, <3.16
|
|
35
34
|
Description-Content-Type: text/markdown
|
|
36
35
|
|
|
37
36
|
Statica
|
|
38
37
|
========================================================================================
|
|
39
38
|
|
|
40
|
-

|
|
40
|
+

|
|
42
41
|
|
|
43
42
|
|
|
44
43
|
Statica is a Python library for defining and validating structured data with type annotations and constraints. It provides an easy-to-use framework for creating type-safe models with comprehensive validation for both types and constraints.
|
|
@@ -62,7 +61,7 @@ Features
|
|
|
62
61
|
- **Type Validation**: Automatically validates types for attributes based on type hints.
|
|
63
62
|
- **Constraint Validation**: Define constraints like minimum/maximum length, value ranges, and more.
|
|
64
63
|
- **Default Field Values**: Set default values for fields that are used when not explicitly provided.
|
|
65
|
-
- **Customizable Error Handling**: Use custom exception classes for type and constraint errors.
|
|
64
|
+
- **Customizable Error Handling**: Use custom exception classes and message templates for type and constraint errors.
|
|
66
65
|
- **Flexible Field Descriptors**: Add constraints, casting, and other behaviors to your fields.
|
|
67
66
|
- **Optional Fields**: Support for optional fields with default values.
|
|
68
67
|
- **Automatic Initialization**: Automatically generate constructors (`__init__`) for your models.
|
|
@@ -89,23 +88,24 @@ Getting Started
|
|
|
89
88
|
Define a model with type annotations and constraints:
|
|
90
89
|
|
|
91
90
|
```python
|
|
92
|
-
from statica
|
|
91
|
+
from statica import Field, Statica
|
|
92
|
+
|
|
93
93
|
|
|
94
94
|
class Payload(Statica):
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
95
|
+
name: str = Field(min_length=3, max_length=50, strip_whitespace=True)
|
|
96
|
+
description: str | None = Field(max_length=200)
|
|
97
|
+
num: int | float
|
|
98
|
+
float_num: float | None
|
|
99
99
|
```
|
|
100
100
|
|
|
101
101
|
Instantiate the model using a dictionary:
|
|
102
102
|
|
|
103
103
|
```python
|
|
104
104
|
data = {
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
105
|
+
"name": "Test Payload",
|
|
106
|
+
"description": "A short description.",
|
|
107
|
+
"num": 42,
|
|
108
|
+
"float_num": 3.14,
|
|
109
109
|
}
|
|
110
110
|
|
|
111
111
|
payload = Payload.from_map(data)
|
|
@@ -116,10 +116,10 @@ Or instantiate directly:
|
|
|
116
116
|
|
|
117
117
|
```python
|
|
118
118
|
payload = Payload(
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
119
|
+
name="Test",
|
|
120
|
+
description="This is a test description.",
|
|
121
|
+
num=42,
|
|
122
|
+
float_num=3.14,
|
|
123
123
|
)
|
|
124
124
|
```
|
|
125
125
|
|
|
@@ -128,17 +128,17 @@ payload = Payload(
|
|
|
128
128
|
Statica automatically validates attributes based on type annotations and constraints:
|
|
129
129
|
|
|
130
130
|
```python
|
|
131
|
-
from statica
|
|
131
|
+
from statica import ConstraintValidationError, TypeValidationError
|
|
132
132
|
|
|
133
133
|
try:
|
|
134
|
-
|
|
134
|
+
payload = Payload(name="Te", description="Valid", num=42)
|
|
135
135
|
except ConstraintValidationError as e:
|
|
136
|
-
|
|
136
|
+
print(e) # Output: "name length must be at least 3"
|
|
137
137
|
|
|
138
138
|
try:
|
|
139
|
-
|
|
139
|
+
payload = Payload(name="Test", description="Valid", num="Invalid")
|
|
140
140
|
except TypeValidationError as e:
|
|
141
|
-
|
|
141
|
+
print(e) # Output: "expected type 'int | float', got 'str'"
|
|
142
142
|
```
|
|
143
143
|
|
|
144
144
|
### Optional Fields
|
|
@@ -147,7 +147,8 @@ Fields annotated with `| None` are optional and default to `None`:
|
|
|
147
147
|
|
|
148
148
|
```python
|
|
149
149
|
class OptionalPayload(Statica):
|
|
150
|
-
|
|
150
|
+
name: str | None
|
|
151
|
+
|
|
151
152
|
|
|
152
153
|
payload = OptionalPayload()
|
|
153
154
|
print(payload.name) # Output: None
|
|
@@ -161,23 +162,24 @@ You can specify default values for fields in two ways:
|
|
|
161
162
|
|
|
162
163
|
```python
|
|
163
164
|
class User(Statica):
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
165
|
+
name: str
|
|
166
|
+
age: int = Field(default=25)
|
|
167
|
+
active: bool = Field(default=True)
|
|
168
|
+
|
|
167
169
|
|
|
168
170
|
# Using direct initialization
|
|
169
171
|
user = User(name="John")
|
|
170
|
-
print(user.name)
|
|
171
|
-
print(user.age)
|
|
172
|
+
print(user.name) # Output: "John"
|
|
173
|
+
print(user.age) # Output: 25
|
|
172
174
|
print(user.active) # Output: True
|
|
173
175
|
|
|
174
176
|
# Using from_map
|
|
175
177
|
user = User.from_map({"name": "Jane"})
|
|
176
|
-
print(user.age)
|
|
178
|
+
print(user.age) # Output: 25 (default used)
|
|
177
179
|
|
|
178
180
|
# Explicit values override defaults
|
|
179
181
|
user = User(name="Bob", age=30, active=False)
|
|
180
|
-
print(user.age)
|
|
182
|
+
print(user.age) # Output: 30
|
|
181
183
|
```
|
|
182
184
|
|
|
183
185
|
#### Direct assignment (without Field)
|
|
@@ -186,15 +188,16 @@ You can also assign default values directly to fields without using `Field()`:
|
|
|
186
188
|
|
|
187
189
|
```python
|
|
188
190
|
class Config(Statica):
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
191
|
+
name: str
|
|
192
|
+
timeout: float = 30.0 # Direct assignment
|
|
193
|
+
retries: int = 3 # Direct assignment
|
|
194
|
+
debug: bool = False # Direct assignment
|
|
195
|
+
|
|
193
196
|
|
|
194
197
|
config = Config(name="server")
|
|
195
198
|
print(config.timeout) # Output: 30.0
|
|
196
|
-
print(config.retries)
|
|
197
|
-
print(config.debug)
|
|
199
|
+
print(config.retries) # Output: 3
|
|
200
|
+
print(config.debug) # Output: False
|
|
198
201
|
|
|
199
202
|
# Works with from_map too
|
|
200
203
|
config = Config.from_map({"name": "api-server"})
|
|
@@ -209,8 +212,9 @@ Default values are validated against any constraints you've defined:
|
|
|
209
212
|
|
|
210
213
|
```python
|
|
211
214
|
class Config(Statica):
|
|
212
|
-
|
|
213
|
-
|
|
215
|
+
timeout: float = Field(default=30.0, min_value=1.0, max_value=120.0)
|
|
216
|
+
retries: int = Field(default=3, min_value=1)
|
|
217
|
+
|
|
214
218
|
|
|
215
219
|
config = Config() # Uses defaults: timeout=30.0, retries=3
|
|
216
220
|
```
|
|
@@ -219,8 +223,9 @@ For mutable default values (like lists, dicts, sets), Statica automatically crea
|
|
|
219
223
|
|
|
220
224
|
```python
|
|
221
225
|
class UserProfile(Statica):
|
|
222
|
-
|
|
223
|
-
|
|
226
|
+
name: str
|
|
227
|
+
tags: list[str] = Field(default=[]) # or tags: list[str] = []
|
|
228
|
+
|
|
224
229
|
|
|
225
230
|
user1 = UserProfile(name="Alice")
|
|
226
231
|
user2 = UserProfile(name="Bob")
|
|
@@ -235,26 +240,29 @@ print(user2.tags) # Output: [] (not affected)
|
|
|
235
240
|
You can specify constraints and options on fields:
|
|
236
241
|
|
|
237
242
|
- **Default Values**: `default` (using `Field()`) or direct assignment
|
|
238
|
-
- **
|
|
243
|
+
- **Length Constraints** (`str`, `list`, `tuple`, `dict`): `min_length`, `max_length`
|
|
244
|
+
- **String Options**: `strip_whitespace`
|
|
239
245
|
- **Numeric Constraints**: `min_value`, `max_value`
|
|
240
246
|
- **Casting**: `cast_to`
|
|
241
247
|
- **Aliasing**: `alias`
|
|
242
248
|
|
|
243
249
|
```python
|
|
244
250
|
class StringTest(Statica):
|
|
245
|
-
|
|
251
|
+
name: str = Field(min_length=3, max_length=5, strip_whitespace=True)
|
|
252
|
+
|
|
246
253
|
|
|
247
254
|
class IntTest(Statica):
|
|
248
|
-
|
|
255
|
+
num: int = Field(min_value=1, max_value=10, cast_to=int)
|
|
256
|
+
|
|
249
257
|
|
|
250
258
|
class DefaultTest(Statica):
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
259
|
+
# Using Field() for defaults with constraints
|
|
260
|
+
status: str = Field(default="active")
|
|
261
|
+
priority: int = Field(default=1, min_value=1, max_value=5)
|
|
262
|
+
|
|
263
|
+
# Direct assignment for simple defaults
|
|
264
|
+
timeout: float = 30.0
|
|
265
|
+
retries: int = 3
|
|
258
266
|
```
|
|
259
267
|
|
|
260
268
|
### Custom Error Classes
|
|
@@ -263,37 +271,76 @@ You can define custom error classes for type and constraint validation:
|
|
|
263
271
|
|
|
264
272
|
```python
|
|
265
273
|
class CustomError(Exception):
|
|
266
|
-
|
|
274
|
+
pass
|
|
275
|
+
|
|
267
276
|
|
|
268
277
|
class CustomPayload(Statica):
|
|
269
|
-
|
|
278
|
+
constraint_error_class = CustomError
|
|
279
|
+
|
|
280
|
+
num: int = Field(min_value=1, max_value=10)
|
|
270
281
|
|
|
271
|
-
num: int = Field(min_value=1, max_value=10)
|
|
272
282
|
|
|
273
283
|
try:
|
|
274
|
-
|
|
284
|
+
payload = CustomPayload(num=0)
|
|
275
285
|
except CustomError as e:
|
|
276
|
-
|
|
286
|
+
print(e) # Output: "num must be at least 1"
|
|
277
287
|
```
|
|
278
288
|
|
|
279
289
|
Or, define a BaseClass which configures the error classes globally:
|
|
280
290
|
|
|
281
291
|
```python
|
|
282
|
-
from statica
|
|
292
|
+
from statica import ConstraintValidationError, Statica, TypeValidationError
|
|
293
|
+
|
|
283
294
|
|
|
284
295
|
class BaseClass(Statica):
|
|
285
|
-
|
|
286
|
-
|
|
296
|
+
constraint_error_class = ConstraintValidationError
|
|
297
|
+
type_error_class = TypeValidationError
|
|
298
|
+
|
|
287
299
|
|
|
288
300
|
class CustomPayload(BaseClass):
|
|
289
|
-
|
|
301
|
+
num: int = Field(min_value=1, max_value=10)
|
|
302
|
+
|
|
290
303
|
|
|
291
304
|
try:
|
|
292
|
-
|
|
305
|
+
payload = CustomPayload(num=0)
|
|
293
306
|
except ConstraintValidationError as e:
|
|
294
|
-
|
|
307
|
+
print(e) # Output: "num must be at least 1"
|
|
295
308
|
```
|
|
296
309
|
|
|
310
|
+
### Custom Error Messages
|
|
311
|
+
|
|
312
|
+
Pass a `StaticaConfig` with the `config` class keyword to change the message templates of a model. Subclasses use the messages of their parent unless they pass their own.
|
|
313
|
+
|
|
314
|
+
```python
|
|
315
|
+
from statica import Field, Statica, StaticaConfig, TypeValidationError
|
|
316
|
+
|
|
317
|
+
messages = StaticaConfig(
|
|
318
|
+
type_error_message="{found_type} is not {expected_type}",
|
|
319
|
+
min_value_error_message="{field_name} is below {min_value}",
|
|
320
|
+
)
|
|
321
|
+
|
|
322
|
+
|
|
323
|
+
class Order(Statica, config=messages):
|
|
324
|
+
quantity: int = Field(min_value=1)
|
|
325
|
+
|
|
326
|
+
|
|
327
|
+
try:
|
|
328
|
+
Order(quantity="three")
|
|
329
|
+
except TypeValidationError as e:
|
|
330
|
+
print(e) # Output: "str is not int"
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
Messages that are not passed keep their default text. Each template can use these placeholders:
|
|
334
|
+
|
|
335
|
+
| Message | Placeholders |
|
|
336
|
+
|:--|:--|
|
|
337
|
+
| `type_error_message` | `{expected_type}`, `{found_type}` |
|
|
338
|
+
| `literal_error_message` | `{allowed_values}`, `{value}` |
|
|
339
|
+
| `min_length_error_message` | `{field_name}`, `{min_length}` |
|
|
340
|
+
| `max_length_error_message` | `{field_name}`, `{max_length}` |
|
|
341
|
+
| `min_value_error_message` | `{field_name}`, `{min_value}` |
|
|
342
|
+
| `max_value_error_message` | `{field_name}`, `{max_value}` |
|
|
343
|
+
|
|
297
344
|
|
|
298
345
|
Aliasing
|
|
299
346
|
----------------------------------------------------------------------------------------
|
|
@@ -305,14 +352,15 @@ Use the `alias` parameter to define an alternative name for both parsing and ser
|
|
|
305
352
|
|
|
306
353
|
```python
|
|
307
354
|
class User(Statica):
|
|
308
|
-
|
|
309
|
-
|
|
355
|
+
full_name: str = Field(alias="fullName")
|
|
356
|
+
age: int = Field(alias="userAge", default=25)
|
|
357
|
+
|
|
310
358
|
|
|
311
359
|
# Parse data with aliases
|
|
312
360
|
data = {"fullName": "John Doe"} # userAge not provided, uses default
|
|
313
361
|
user = User.from_map(data)
|
|
314
362
|
print(user.full_name) # Output: "John Doe"
|
|
315
|
-
print(user.age)
|
|
363
|
+
print(user.age) # Output: 25
|
|
316
364
|
|
|
317
365
|
# Serialize back with aliases (uses the alias for serialization by default)
|
|
318
366
|
result = user.to_dict()
|
|
@@ -321,7 +369,6 @@ print(result) # Output: {"fullName": "John Doe", "userAge": 25}
|
|
|
321
369
|
# Serialize without aliases
|
|
322
370
|
result_no_alias = user.to_dict(with_aliases=False)
|
|
323
371
|
print(result_no_alias) # Output: {"full_name": "John Doe", "age": 25}
|
|
324
|
-
|
|
325
372
|
```
|
|
326
373
|
|
|
327
374
|
Advanced Usage
|
|
@@ -337,7 +384,8 @@ You can automatically cast input values to the desired type:
|
|
|
337
384
|
|
|
338
385
|
```python
|
|
339
386
|
class CastingExample(Statica):
|
|
340
|
-
|
|
387
|
+
num: int = Field(cast_to=int)
|
|
388
|
+
|
|
341
389
|
|
|
342
390
|
instance = CastingExample(num="42")
|
|
343
391
|
print(instance.num) # Output: 42
|
|
@@ -350,15 +398,22 @@ Design Decisions
|
|
|
350
398
|
- [Inheritance over Decorators](docs/decision-inheritance-over-decorators.md)
|
|
351
399
|
|
|
352
400
|
|
|
353
|
-
|
|
401
|
+
Development
|
|
354
402
|
----------------------------------------------------------------------------------------
|
|
355
403
|
|
|
356
|
-
|
|
404
|
+
Statica supports Python 3.11 to 3.15. Development uses [uv](https://docs.astral.sh/uv/) and [just](https://just.systems/):
|
|
405
|
+
|
|
406
|
+
```bash
|
|
407
|
+
uv sync # Install the dev dependencies
|
|
408
|
+
just check # Fix lint and formatting, type-check, run tests with coverage
|
|
409
|
+
uv run python benchmark_creation.py # Time the creation of 1,000,000 instances
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
Use `uv sync` to set up, not `just install`: that recipe also sets the maintainer's git identity.
|
|
413
|
+
|
|
414
|
+
To read the code, start with `statica/core.py` (`Statica`, `StaticaMeta`, `FieldDescriptor`), then `statica/validation.py`.
|
|
357
415
|
|
|
358
|
-
|
|
359
|
-
2. Create a new branch for your feature or bug fix.
|
|
360
|
-
3. Write tests for your changes.
|
|
361
|
-
4. Submit a pull request.
|
|
416
|
+
Contributions are welcome: fork the repository, add tests for your change, and open a pull request.
|
|
362
417
|
|
|
363
418
|
|
|
364
419
|
License
|