statica 1.3.0__tar.gz → 1.4.0__tar.gz

{statica-1.3.0/statica.egg-info → statica-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: statica
-Version: 1.3.0
+Version: 1.4.0
 Summary: A minimalistic data validation library
 Author-email: Marcel Kröker <kroeker.marcel@gmail.com>
 License: MIT License
@@ -47,7 +47,7 @@ Statica is a Python library for defining and validating structured data with typ
 Why Statica?
 ----------------------------------------------------------------------------------------
 
-Statica was created to address the need for a lightweight, flexible, and dependency-free alternative to libraries like Pydantic.
+Statica was created to address the need for a lightweight, flexible, and dependency-free alternative to Pydantic.
 While pydantic is a powerful tool for data validation and parsing, Statica offers some distinct advantages in specific situations:
 
 1. **Lightweight**: Statica has zero dependencies, making it ideal for projects where minimizing external dependencies is a priority.
@@ -61,6 +61,7 @@ Features
 
 - **Type Validation**: Automatically validates types for attributes based on type hints.
 - **Constraint Validation**: Define constraints like minimum/maximum length, value ranges, and more.
+- **Default Field Values**: Set default values for fields that are used when not explicitly provided.
 - **Customizable Error Handling**: Use custom exception classes for type and constraint errors.
 - **Flexible Field Descriptors**: Add constraints, casting, and other behaviors to your fields.
 - **Optional Fields**: Support for optional fields with default values.
@@ -152,13 +153,92 @@ payload = OptionalPayload()
 print(payload.name)  # Output: None
 ```
 
+### Default Field Values
+
+You can specify default values for fields in two ways:
+
+#### Using Field() with default parameter
+
+```python
+class User(Statica):
+    name: str
+    age: int = Field(default=25)
+    active: bool = Field(default=True)
+
+# Using direct initialization
+user = User(name="John")
+print(user.name)    # Output: "John"
+print(user.age)     # Output: 25
+print(user.active)  # Output: True
+
+# Using from_map
+user = User.from_map({"name": "Jane"})
+print(user.age)     # Output: 25 (default used)
+
+# Explicit values override defaults
+user = User(name="Bob", age=30, active=False)
+print(user.age)     # Output: 30
+```
+
+#### Direct assignment (without Field)
+
+You can also assign default values directly to fields without using `Field()`:
+
+```python
+class Config(Statica):
+    name: str
+    timeout: float = 30.0      # Direct assignment
+    retries: int = 3           # Direct assignment
+    debug: bool = False        # Direct assignment
+
+config = Config(name="server")
+print(config.timeout)  # Output: 30.0
+print(config.retries)   # Output: 3
+print(config.debug)     # Output: False
+
+# Works with from_map too
+config = Config.from_map({"name": "api-server"})
+print(config.timeout)  # Output: 30.0 (default used)
+```
+
+Both approaches work identically and can be mixed within the same class. Use `Field(default=...)` when you need additional constraints or options, and direct assignment for simple defaults.
+
+#### Validation and Safety
+
+Default values are validated against any constraints you've defined:
+
+```python
+class Config(Statica):
+    timeout: float = Field(default=30.0, min_value=1.0, max_value=120.0)
+    retries: int = Field(default=3, min_value=1)
+
+config = Config()  # Uses defaults: timeout=30.0, retries=3
+```
+
+For mutable default values (like lists, dicts, sets), Statica automatically creates copies to prevent shared state issues:
+
+```python
+class UserProfile(Statica):
+    name: str
+    tags: list[str] = Field(default=[])  # or tags: list[str] = []
+
+user1 = UserProfile(name="Alice")
+user2 = UserProfile(name="Bob")
+
+user1.tags.append("admin")
+print(user1.tags)  # Output: ["admin"]
+print(user2.tags)  # Output: [] (not affected)
+```
+
 ### Field Constraints
 
-You can specify constraints on fields:
+You can specify constraints and options on fields:
 
+- **Default Values**: `default` (using `Field()`) or direct assignment
 - **String Constraints**: `min_length`, `max_length`, `strip_whitespace`
 - **Numeric Constraints**: `min_value`, `max_value`
 - **Casting**: `cast_to`
+- **Aliasing**: `alias`
 
 ```python
 class StringTest(Statica):
@@ -166,6 +246,15 @@ class StringTest(Statica):
 
 class IntTest(Statica):
     num: int = Field(min_value=1, max_value=10, cast_to=int)
+
+class DefaultTest(Statica):
+    # Using Field() for defaults with constraints
+    status: str = Field(default="active")
+    priority: int = Field(default=1, min_value=1, max_value=5)
+    
+    # Direct assignment for simple defaults
+    timeout: float = 30.0
+    retries: int = 3
 ```
 
 ### Custom Error Classes
@@ -212,68 +301,27 @@ Aliasing
 Statica supports field aliasing, allowing you to map different field names for parsing and serialization.
 This is particularly useful when working with external APIs that use different naming conventions.
 
-### Basic Aliases
-
 Use the `alias` parameter to define an alternative name for both parsing and serialization:
 
 ```python
 class User(Statica):
     full_name: str = Field(alias="fullName")
-    age: int = Field(alias="userAge")
+    age: int = Field(alias="userAge", default=25)
 
 # Parse data with aliases
-data = {"fullName": "John Doe", "userAge": 30}
+data = {"fullName": "John Doe"}  # userAge not provided, uses default
 user = User.from_map(data)
 print(user.full_name)  # Output: "John Doe"
-print(user.age)        # Output: 30
+print(user.age)        # Output: 25
 
-# Serialize back with aliases
+# Serialize back with aliases (uses the alias for serialization by default)
 result = user.to_dict()
-print(result)  # Output: {"fullName": "John Doe", "userAge": 30}
-```
+print(result)  # Output: {"fullName": "John Doe", "userAge": 25}
 
-### Separate Parsing and Serialization Aliases
+# Serialize without aliases
+result_no_alias = user.to_dict(with_aliases=False)
+print(result_no_alias)  # Output: {"full_name": "John Doe", "age": 25}
 
-You can define different aliases for parsing and serialization:
-
-```python
-class APIModel(Statica):
-    user_name: str = Field(
-        alias_for_parsing="userName",
-        alias_for_serialization="username"
-    )
-    user_id: int = Field(alias_for_parsing="userId")
-
-# Parse from camelCase API response
-api_data = {"userName": "alice", "userId": 123}
-model = APIModel.from_map(api_data)
-
-# Serialize to snake_case for internal use
-internal_data = model.to_dict()
-print(internal_data)  # Output: {"username": "alice", "user_id": 123}
-```
-
-### Alias Priority
-
-When multiple alias types are defined, the priority is:
-1. `alias_for_parsing` for parsing operations
-2. `alias_for_serialization` for serialization operations
-3. `alias` as a fallback for both operations
-
-```python
-class PriorityExample(Statica):
-    field_name: str = Field(
-        alias="generalAlias",
-        alias_for_parsing="parseAlias",
-        alias_for_serialization="serializeAlias"
-    )
-
-# Uses alias_for_parsing
-instance = PriorityExample.from_map({"parseAlias": "value"})
-
-# Uses alias_for_serialization
-result = instance.to_dict()
-print(result)  # Output: {"serializeAlias": "value"}
 ```
 
 Advanced Usage
@@ -296,6 +344,12 @@ print(instance.num)  # Output: 42
 ```
 
 
+Design Decisions
+----------------------------------------------------------------------------------------
+
+- [Inheritance over Decorators](docs/decision-inheritance-over-decorators.md)
+
+
 Contributing
 ----------------------------------------------------------------------------------------
 

{statica-1.3.0 → statica-1.4.0}/README.md

@@ -11,7 +11,7 @@ Statica is a Python library for defining and validating structured data with typ
 Why Statica?
 ----------------------------------------------------------------------------------------
 
-Statica was created to address the need for a lightweight, flexible, and dependency-free alternative to libraries like Pydantic.
+Statica was created to address the need for a lightweight, flexible, and dependency-free alternative to Pydantic.
 While pydantic is a powerful tool for data validation and parsing, Statica offers some distinct advantages in specific situations:
 
 1. **Lightweight**: Statica has zero dependencies, making it ideal for projects where minimizing external dependencies is a priority.
@@ -25,6 +25,7 @@ Features
 
 - **Type Validation**: Automatically validates types for attributes based on type hints.
 - **Constraint Validation**: Define constraints like minimum/maximum length, value ranges, and more.
+- **Default Field Values**: Set default values for fields that are used when not explicitly provided.
 - **Customizable Error Handling**: Use custom exception classes for type and constraint errors.
 - **Flexible Field Descriptors**: Add constraints, casting, and other behaviors to your fields.
 - **Optional Fields**: Support for optional fields with default values.
@@ -116,13 +117,92 @@ payload = OptionalPayload()
 print(payload.name)  # Output: None
 ```
 
+### Default Field Values
+
+You can specify default values for fields in two ways:
+
+#### Using Field() with default parameter
+
+```python
+class User(Statica):
+    name: str
+    age: int = Field(default=25)
+    active: bool = Field(default=True)
+
+# Using direct initialization
+user = User(name="John")
+print(user.name)    # Output: "John"
+print(user.age)     # Output: 25
+print(user.active)  # Output: True
+
+# Using from_map
+user = User.from_map({"name": "Jane"})
+print(user.age)     # Output: 25 (default used)
+
+# Explicit values override defaults
+user = User(name="Bob", age=30, active=False)
+print(user.age)     # Output: 30
+```
+
+#### Direct assignment (without Field)
+
+You can also assign default values directly to fields without using `Field()`:
+
+```python
+class Config(Statica):
+    name: str
+    timeout: float = 30.0      # Direct assignment
+    retries: int = 3           # Direct assignment
+    debug: bool = False        # Direct assignment
+
+config = Config(name="server")
+print(config.timeout)  # Output: 30.0
+print(config.retries)   # Output: 3
+print(config.debug)     # Output: False
+
+# Works with from_map too
+config = Config.from_map({"name": "api-server"})
+print(config.timeout)  # Output: 30.0 (default used)
+```
+
+Both approaches work identically and can be mixed within the same class. Use `Field(default=...)` when you need additional constraints or options, and direct assignment for simple defaults.
+
+#### Validation and Safety
+
+Default values are validated against any constraints you've defined:
+
+```python
+class Config(Statica):
+    timeout: float = Field(default=30.0, min_value=1.0, max_value=120.0)
+    retries: int = Field(default=3, min_value=1)
+
+config = Config()  # Uses defaults: timeout=30.0, retries=3
+```
+
+For mutable default values (like lists, dicts, sets), Statica automatically creates copies to prevent shared state issues:
+
+```python
+class UserProfile(Statica):
+    name: str
+    tags: list[str] = Field(default=[])  # or tags: list[str] = []
+
+user1 = UserProfile(name="Alice")
+user2 = UserProfile(name="Bob")
+
+user1.tags.append("admin")
+print(user1.tags)  # Output: ["admin"]
+print(user2.tags)  # Output: [] (not affected)
+```
+
 ### Field Constraints
 
-You can specify constraints on fields:
+You can specify constraints and options on fields:
 
+- **Default Values**: `default` (using `Field()`) or direct assignment
 - **String Constraints**: `min_length`, `max_length`, `strip_whitespace`
 - **Numeric Constraints**: `min_value`, `max_value`
 - **Casting**: `cast_to`
+- **Aliasing**: `alias`
 
 ```python
 class StringTest(Statica):
@@ -130,6 +210,15 @@ class StringTest(Statica):
 
 class IntTest(Statica):
     num: int = Field(min_value=1, max_value=10, cast_to=int)
+
+class DefaultTest(Statica):
+    # Using Field() for defaults with constraints
+    status: str = Field(default="active")
+    priority: int = Field(default=1, min_value=1, max_value=5)
+    
+    # Direct assignment for simple defaults
+    timeout: float = 30.0
+    retries: int = 3
 ```
 
 ### Custom Error Classes
@@ -176,68 +265,27 @@ Aliasing
 Statica supports field aliasing, allowing you to map different field names for parsing and serialization.
 This is particularly useful when working with external APIs that use different naming conventions.
 
-### Basic Aliases
-
 Use the `alias` parameter to define an alternative name for both parsing and serialization:
 
 ```python
 class User(Statica):
     full_name: str = Field(alias="fullName")
-    age: int = Field(alias="userAge")
+    age: int = Field(alias="userAge", default=25)
 
 # Parse data with aliases
-data = {"fullName": "John Doe", "userAge": 30}
+data = {"fullName": "John Doe"}  # userAge not provided, uses default
 user = User.from_map(data)
 print(user.full_name)  # Output: "John Doe"
-print(user.age)        # Output: 30
+print(user.age)        # Output: 25
 
-# Serialize back with aliases
+# Serialize back with aliases (uses the alias for serialization by default)
 result = user.to_dict()
-print(result)  # Output: {"fullName": "John Doe", "userAge": 30}
-```
+print(result)  # Output: {"fullName": "John Doe", "userAge": 25}
 
-### Separate Parsing and Serialization Aliases
+# Serialize without aliases
+result_no_alias = user.to_dict(with_aliases=False)
+print(result_no_alias)  # Output: {"full_name": "John Doe", "age": 25}
 
-You can define different aliases for parsing and serialization:
-
-```python
-class APIModel(Statica):
-    user_name: str = Field(
-        alias_for_parsing="userName",
-        alias_for_serialization="username"
-    )
-    user_id: int = Field(alias_for_parsing="userId")
-
-# Parse from camelCase API response
-api_data = {"userName": "alice", "userId": 123}
-model = APIModel.from_map(api_data)
-
-# Serialize to snake_case for internal use
-internal_data = model.to_dict()
-print(internal_data)  # Output: {"username": "alice", "user_id": 123}
-```
-
-### Alias Priority
-
-When multiple alias types are defined, the priority is:
-1. `alias_for_parsing` for parsing operations
-2. `alias_for_serialization` for serialization operations
-3. `alias` as a fallback for both operations
-
-```python
-class PriorityExample(Statica):
-    field_name: str = Field(
-        alias="generalAlias",
-        alias_for_parsing="parseAlias",
-        alias_for_serialization="serializeAlias"
-    )
-
-# Uses alias_for_parsing
-instance = PriorityExample.from_map({"parseAlias": "value"})
-
-# Uses alias_for_serialization
-result = instance.to_dict()
-print(result)  # Output: {"serializeAlias": "value"}
 ```
 
 Advanced Usage
@@ -260,6 +308,12 @@ print(instance.num)  # Output: 42
 ```
 
 
+Design Decisions
+----------------------------------------------------------------------------------------
+
+- [Inheritance over Decorators](docs/decision-inheritance-over-decorators.md)
+
+
 Contributing
 ----------------------------------------------------------------------------------------
 

{statica-1.3.0 → statica-1.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "statica"
-version = "1.3.0"
+version = "1.4.0"
 description = "A minimalistic data validation library"
 readme = "README.md"
 authors = [{ name = "Marcel Kröker", email = "kroeker.marcel@gmail.com" }]

statica-1.4.0/statica/config.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class StaticaConfig:
+	type_error_message: str
+	min_length_error_message: str
+	max_length_error_message: str
+	min_value_error_message: str
+	max_value_error_message: str
+
+	@classmethod
+	def create(
+		cls,
+		*,
+		type_error_message: str = "expected type '{expected_type}', got '{found_type}'",
+		min_length_error_message: str = "{field_name} length must be at least {min_length}",
+		max_length_error_message: str = "{field_name} length must be at most {max_length}",
+		min_value_error_message: str = "{field_name} must be at least {min_value}",
+		max_value_error_message: str = "{field_name} must be at most {max_value}",
+	) -> StaticaConfig:
+		return cls(
+			type_error_message=type_error_message,
+			min_length_error_message=min_length_error_message,
+			max_length_error_message=max_length_error_message,
+			min_value_error_message=min_value_error_message,
+			max_value_error_message=max_value_error_message,
+		)
+
+
+default_config = StaticaConfig.create()