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.
@@ -1,44 +1,43 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.3
2
2
  Name: statica
3
- Version: 1.4.0
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
- Copyright (c) 2025 mkrd
9
-
10
- Permission is hereby granted, free of charge, to any person obtaining a copy
11
- of this software and associated documentation files (the "Software"), to deal
12
- in the Software without restriction, including without limitation the rights
13
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
- copies of the Software, and to permit persons to whom the Software is
15
- furnished to do so, subject to the following conditions:
16
-
17
- The above copyright notice and this permission notice shall be included in all
18
- copies or substantial portions of the Software.
19
-
20
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
- SOFTWARE.
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: <3.14,>=3.11
33
+ Requires-Python: >=3.11, <3.16
35
34
  Description-Content-Type: text/markdown
36
35
 
37
36
  Statica
38
37
  ========================================================================================
39
38
 
40
- ![Tests](https://github.com/mkrd/statica/actions/workflows/test.yml/badge.svg)
41
- ![Coverage](https://github.com/mkrd/statica/blob/main/assets/coverage.svg?raw=true)
39
+ ![Tests](https://git.budgetflow.cc/mkrd/statica/actions/workflows/test.yml/badge.svg)
40
+ ![Coverage](https://git.budgetflow.cc/mkrd/statica/raw/branch/main/assets/coverage.svg)
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.core import Statica, Field
91
+ from statica import Field, Statica
92
+
93
93
 
94
94
  class Payload(Statica):
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
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
- "name": "Test Payload",
106
- "description": "A short description.",
107
- "num": 42,
108
- "float_num": 3.14,
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
- name="Test",
120
- description="This is a test description.",
121
- num=42,
122
- float_num=3.14,
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.core import ConstraintValidationError, TypeValidationError
131
+ from statica import ConstraintValidationError, TypeValidationError
132
132
 
133
133
  try:
134
- payload = Payload(name="Te", description="Valid", num=42)
134
+ payload = Payload(name="Te", description="Valid", num=42)
135
135
  except ConstraintValidationError as e:
136
- print(e) # Output: "name: length must be at least 3"
136
+ print(e) # Output: "name length must be at least 3"
137
137
 
138
138
  try:
139
- payload = Payload(name="Test", description="Valid", num="Invalid")
139
+ payload = Payload(name="Test", description="Valid", num="Invalid")
140
140
  except TypeValidationError as e:
141
- print(e) # Output: "num: expected type 'int | float', got 'str'"
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
- name: str | None
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
- name: str
165
- age: int = Field(default=25)
166
- active: bool = Field(default=True)
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) # Output: "John"
171
- print(user.age) # Output: 25
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) # Output: 25 (default used)
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) # Output: 30
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
- name: str
190
- timeout: float = 30.0 # Direct assignment
191
- retries: int = 3 # Direct assignment
192
- debug: bool = False # Direct assignment
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) # Output: 3
197
- print(config.debug) # Output: False
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
- timeout: float = Field(default=30.0, min_value=1.0, max_value=120.0)
213
- retries: int = Field(default=3, min_value=1)
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
- name: str
223
- tags: list[str] = Field(default=[]) # or tags: list[str] = []
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
- - **String Constraints**: `min_length`, `max_length`, `strip_whitespace`
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
- name: str = Field(min_length=3, max_length=5, strip_whitespace=True)
251
+ name: str = Field(min_length=3, max_length=5, strip_whitespace=True)
252
+
246
253
 
247
254
  class IntTest(Statica):
248
- num: int = Field(min_value=1, max_value=10, cast_to=int)
255
+ num: int = Field(min_value=1, max_value=10, cast_to=int)
256
+
249
257
 
250
258
  class DefaultTest(Statica):
251
- # Using Field() for defaults with constraints
252
- status: str = Field(default="active")
253
- priority: int = Field(default=1, min_value=1, max_value=5)
254
-
255
- # Direct assignment for simple defaults
256
- timeout: float = 30.0
257
- retries: int = 3
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
- pass
274
+ pass
275
+
267
276
 
268
277
  class CustomPayload(Statica):
269
- constraint_error_class = CustomError
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
- payload = CustomPayload(num=0)
284
+ payload = CustomPayload(num=0)
275
285
  except CustomError as e:
276
- print(e) # Output: "num: must be at least 1"
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.core import Statica, ConstraintValidationError, TypeValidationError
292
+ from statica import ConstraintValidationError, Statica, TypeValidationError
293
+
283
294
 
284
295
  class BaseClass(Statica):
285
- constraint_error_class = ConstraintValidationError
286
- type_error_class = TypeValidationError
296
+ constraint_error_class = ConstraintValidationError
297
+ type_error_class = TypeValidationError
298
+
287
299
 
288
300
  class CustomPayload(BaseClass):
289
- num: int = Field(min_value=1, max_value=10)
301
+ num: int = Field(min_value=1, max_value=10)
302
+
290
303
 
291
304
  try:
292
- payload = CustomPayload(num=0)
305
+ payload = CustomPayload(num=0)
293
306
  except ConstraintValidationError as e:
294
- print(e) # Output: "num: must be at least 1"
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
- full_name: str = Field(alias="fullName")
309
- age: int = Field(alias="userAge", default=25)
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) # Output: 25
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
- num: int = Field(cast_to=int)
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
- Contributing
401
+ Development
354
402
  ----------------------------------------------------------------------------------------
355
403
 
356
- We welcome contributions to Statica! To contribute:
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
- 1. Fork the repository.
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