statica 1.2.0__tar.gz → 1.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: statica
-Version: 1.2.0
+Version: 1.3.0
 Summary: A minimalistic data validation library
 Author-email: Marcel Kröker <kroeker.marcel@gmail.com>
 License: MIT License
@@ -31,10 +31,11 @@ Classifier: Operating System :: OS Independent
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: <3.14,>=3.10
+Requires-Python: <3.14,>=3.11
 Description-Content-Type: text/markdown
 
-# Statica
+Statica
+========================================================================================
 
 ![Tests](https://github.com/mkrd/statica/actions/workflows/test.yml/badge.svg)
 ![Coverage](https://github.com/mkrd/statica/blob/main/assets/coverage.svg?raw=true)
@@ -42,17 +43,21 @@ Description-Content-Type: text/markdown
 
 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.
 
-## Why Statica?
 
-Statica was created to address the need for a lightweight, flexible, and dependency-free alternative to libraries like pydantic.
+Why Statica?
+----------------------------------------------------------------------------------------
+
+Statica was created to address the need for a lightweight, flexible, and dependency-free alternative to libraries like Pydantic.
 While pydantic is a powerful tool for data validation and parsing, Statica offers some distinct advantages in specific situations:
 
-1. **Lightweight**: Statica does not rely on any third-party dependencies, making it ideal for projects where minimizing external dependencies is a priority.
+1. **Lightweight**: Statica has zero dependencies, making it ideal for projects where minimizing external dependencies is a priority.
 2. **Performance**: For use cases where performance is critical. Pydantic needs `3x` more memory than Statica for the same models.
-3. **Ease of Use**: With its simple, Pythonic design, Statica is intuitive for developers already familiar with Python's `dataclasses` and type hinting. It avoids much of the magic that pydantic employs.
-4. **Customizable Validation**: Statica allows fine-grained control over type and constraint validation through customizable field descriptors (`Field`) and error classes.
+3. **Ease of Use**: With its simple, Pythonic design, Statica is intuitive for developers already familiar with Python's `dataclasses` and type hinting. It avoids much of the magic and complexity of Pydantic.
+4. **Customizable**: Statica allows fine-grained control over type and constraint validation through customizable fields and error classes.
+
 
-## Features
+Features
+----------------------------------------------------------------------------------------
 
 - **Type Validation**: Automatically validates types for attributes based on type hints.
 - **Constraint Validation**: Define constraints like minimum/maximum length, value ranges, and more.
@@ -62,8 +67,11 @@ While pydantic is a powerful tool for data validation and parsing, Statica offer
 - **Automatic Initialization**: Automatically generate constructors (`__init__`) for your models.
 - **String Manipulation**: Strip whitespace from string fields if needed.
 - **Casting**: Automatically cast values to the desired type.
+- **Field Aliasing**: Support for field aliases for parsing and serialization.
 
-## Installation
+
+Installation
+----------------------------------------------------------------------------------------
 
 You can install Statica via pip:
 
@@ -71,7 +79,9 @@ You can install Statica via pip:
 pip install statica
 ```
 
-## Getting Started
+
+Getting Started
+----------------------------------------------------------------------------------------
 
 ### Basic Usage
 
@@ -177,20 +187,98 @@ except CustomError as e:
     print(e)  # Output: "num: must be at least 1"
 ```
 
-## Advanced Usage
+Or, define a BaseClass which configures the error classes globally:
+
+```python
+from statica.core import Statica, ConstraintValidationError, TypeValidationError
+
+class BaseClass(Statica):
+    constraint_error_class = ConstraintValidationError
+    type_error_class = TypeValidationError
+
+class CustomPayload(BaseClass):
+    num: int = Field(min_value=1, max_value=10)
+
+try:
+    payload = CustomPayload(num=0)
+except ConstraintValidationError as e:
+    print(e)  # Output: "num: must be at least 1"
+```
+
 
-### Short Syntax for Fields
+Aliasing
+----------------------------------------------------------------------------------------
 
-You can use simple type annotations without explicitly defining `Field` descriptors:
+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")
+
+# Parse data with aliases
+data = {"fullName": "John Doe", "userAge": 30}
+user = User.from_map(data)
+print(user.full_name)  # Output: "John Doe"
+print(user.age)        # Output: 30
+
+# Serialize back with aliases
+result = user.to_dict()
+print(result)  # Output: {"fullName": "John Doe", "userAge": 30}
+```
+
+### Separate Parsing and Serialization Aliases
+
+You can define different aliases for parsing and serialization:
 
 ```python
-class ShortSyntax(Statica):
-    name: str
+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}
+```
 
-short = ShortSyntax(name="Test")
-print(short.name)  # Output: "Test"
+### 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
+----------------------------------------------------------------------------------------
+
 ### Custom Initialization
 
 Statica automatically generates an `__init__` method based on type annotations, ensuring that all required fields are provided during initialization.
@@ -207,7 +295,9 @@ instance = CastingExample(num="42")
 print(instance.num)  # Output: 42
 ```
 
-## Contributing
+
+Contributing
+----------------------------------------------------------------------------------------
 
 We welcome contributions to Statica! To contribute:
 
@@ -216,11 +306,14 @@ We welcome contributions to Statica! To contribute:
 3. Write tests for your changes.
 4. Submit a pull request.
 
-## License
+
+License
+----------------------------------------------------------------------------------------
 
 Statica is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
 
-## Acknowledgments
 
-Statica was built to simplify data validation and provide a robust and simple framework for type-safe models in Python, inspired by `pydantic` and `dataclasses`.
+Acknowledgments
+----------------------------------------------------------------------------------------
 
+Statica was built to simplify data validation and provide a robust and simple framework for type-safe models in Python, inspired by `pydantic` and `dataclasses`.

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

@@ -1,4 +1,5 @@
-# Statica
+Statica
+========================================================================================
 
 ![Tests](https://github.com/mkrd/statica/actions/workflows/test.yml/badge.svg)
 ![Coverage](https://github.com/mkrd/statica/blob/main/assets/coverage.svg?raw=true)
@@ -6,17 +7,21 @@
 
 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.
 
-## Why Statica?
 
-Statica was created to address the need for a lightweight, flexible, and dependency-free alternative to libraries like pydantic.
+Why Statica?
+----------------------------------------------------------------------------------------
+
+Statica was created to address the need for a lightweight, flexible, and dependency-free alternative to libraries like Pydantic.
 While pydantic is a powerful tool for data validation and parsing, Statica offers some distinct advantages in specific situations:
 
-1. **Lightweight**: Statica does not rely on any third-party dependencies, making it ideal for projects where minimizing external dependencies is a priority.
+1. **Lightweight**: Statica has zero dependencies, making it ideal for projects where minimizing external dependencies is a priority.
 2. **Performance**: For use cases where performance is critical. Pydantic needs `3x` more memory than Statica for the same models.
-3. **Ease of Use**: With its simple, Pythonic design, Statica is intuitive for developers already familiar with Python's `dataclasses` and type hinting. It avoids much of the magic that pydantic employs.
-4. **Customizable Validation**: Statica allows fine-grained control over type and constraint validation through customizable field descriptors (`Field`) and error classes.
+3. **Ease of Use**: With its simple, Pythonic design, Statica is intuitive for developers already familiar with Python's `dataclasses` and type hinting. It avoids much of the magic and complexity of Pydantic.
+4. **Customizable**: Statica allows fine-grained control over type and constraint validation through customizable fields and error classes.
+
 
-## Features
+Features
+----------------------------------------------------------------------------------------
 
 - **Type Validation**: Automatically validates types for attributes based on type hints.
 - **Constraint Validation**: Define constraints like minimum/maximum length, value ranges, and more.
@@ -26,8 +31,11 @@ While pydantic is a powerful tool for data validation and parsing, Statica offer
 - **Automatic Initialization**: Automatically generate constructors (`__init__`) for your models.
 - **String Manipulation**: Strip whitespace from string fields if needed.
 - **Casting**: Automatically cast values to the desired type.
+- **Field Aliasing**: Support for field aliases for parsing and serialization.
 
-## Installation
+
+Installation
+----------------------------------------------------------------------------------------
 
 You can install Statica via pip:
 
@@ -35,7 +43,9 @@ You can install Statica via pip:
 pip install statica
 ```
 
-## Getting Started
+
+Getting Started
+----------------------------------------------------------------------------------------
 
 ### Basic Usage
 
@@ -141,20 +151,98 @@ except CustomError as e:
     print(e)  # Output: "num: must be at least 1"
 ```
 
-## Advanced Usage
+Or, define a BaseClass which configures the error classes globally:
+
+```python
+from statica.core import Statica, ConstraintValidationError, TypeValidationError
+
+class BaseClass(Statica):
+    constraint_error_class = ConstraintValidationError
+    type_error_class = TypeValidationError
+
+class CustomPayload(BaseClass):
+    num: int = Field(min_value=1, max_value=10)
+
+try:
+    payload = CustomPayload(num=0)
+except ConstraintValidationError as e:
+    print(e)  # Output: "num: must be at least 1"
+```
+
 
-### Short Syntax for Fields
+Aliasing
+----------------------------------------------------------------------------------------
 
-You can use simple type annotations without explicitly defining `Field` descriptors:
+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")
+
+# Parse data with aliases
+data = {"fullName": "John Doe", "userAge": 30}
+user = User.from_map(data)
+print(user.full_name)  # Output: "John Doe"
+print(user.age)        # Output: 30
+
+# Serialize back with aliases
+result = user.to_dict()
+print(result)  # Output: {"fullName": "John Doe", "userAge": 30}
+```
+
+### Separate Parsing and Serialization Aliases
+
+You can define different aliases for parsing and serialization:
 
 ```python
-class ShortSyntax(Statica):
-    name: str
+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}
+```
 
-short = ShortSyntax(name="Test")
-print(short.name)  # Output: "Test"
+### 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
+----------------------------------------------------------------------------------------
+
 ### Custom Initialization
 
 Statica automatically generates an `__init__` method based on type annotations, ensuring that all required fields are provided during initialization.
@@ -171,7 +259,9 @@ instance = CastingExample(num="42")
 print(instance.num)  # Output: 42
 ```
 
-## Contributing
+
+Contributing
+----------------------------------------------------------------------------------------
 
 We welcome contributions to Statica! To contribute:
 
@@ -180,11 +270,14 @@ We welcome contributions to Statica! To contribute:
 3. Write tests for your changes.
 4. Submit a pull request.
 
-## License
+
+License
+----------------------------------------------------------------------------------------
 
 Statica is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
 
-## Acknowledgments
 
-Statica was built to simplify data validation and provide a robust and simple framework for type-safe models in Python, inspired by `pydantic` and `dataclasses`.
+Acknowledgments
+----------------------------------------------------------------------------------------
 
+Statica was built to simplify data validation and provide a robust and simple framework for type-safe models in Python, inspired by `pydantic` and `dataclasses`.

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

@@ -1,6 +1,6 @@
 [project]
 name = "statica"
-version = "1.2.0"
+version = "1.3.0"
 description = "A minimalistic data validation library"
 readme = "README.md"
 authors = [{ name = "Marcel Kröker", email = "kroeker.marcel@gmail.com" }]
@@ -13,7 +13,7 @@ classifiers=[
 	"Programming Language :: Python",
 	"Topic :: Software Development :: Libraries :: Python Modules"
 ]
-requires-python = ">=3.10, <3.14"
+requires-python = ">=3.11, <3.14"
 
 
 ########################################################################################
@@ -51,7 +51,7 @@ package = true
 
 [tool.ruff]
 show-fixes = true
-line-length = 120
+line-length = 100
 
 
 [tool.ruff.lint]

{statica-1.2.0 → statica-1.3.0}/statica/core.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from dataclasses import field as dataclass_field
+from types import UnionType
 from typing import (
 	TYPE_CHECKING,
 	Any,
@@ -11,11 +12,10 @@ from typing import (
 	cast,
 	dataclass_transform,
 	get_type_hints,
-	overload,
 )
 
 from statica.exceptions import ConstraintValidationError, TypeValidationError
-from statica.validators import validate_constraints, validate_type
+from statica.validation import validate_constraints, validate_or_raise
 
 if TYPE_CHECKING:
 	from collections.abc import Callable, Mapping
@@ -27,15 +27,53 @@ T = TypeVar("T")
 #### MARK: Field descriptor
 
 
-@dataclass
+@dataclass(slots=True)
 class FieldDescriptor(Generic[T]):
 	"""
-	Descriptor for validated fields.
+	Descriptor for statica fields. They will be used to validate fields:
+
+	Example:
+	.. code-block:: python
+		class User(Statica):
+			name: str  # Will be initialized as FieldDescriptor during class creation
+			age: int | None = Field(min_value=0, max_value=120)
 	"""
 
-	name: str = dataclass_field(init=False, repr=False)
-	owner: type = dataclass_field(init=False, repr=False)
-	expected_type: type = dataclass_field(init=False, repr=False)
+	# Descriptor attributes
+
+	name: str = dataclass_field(init=False)
+	"""
+	Name of the field in the class.
+	Example: `"age"` for the field `age: int | None`.
+	"""
+
+	owner: type = dataclass_field(init=False)
+	"""
+	Owner class of the field descriptor.
+	Example: `<class '__main__.User'>` for the field `age: int | None`.
+	"""
+
+	expected_type: Any = dataclass_field(init=False)
+	"""
+	Expected type of the field.
+	Example 1: `int | None` (of type UnionType) for the field `age: int | None`.
+	Example 2: `<class 'int'>` for a field `number: int`.
+	"""
+
+	sub_types: tuple[type, ...] = dataclass_field(init=False, default_factory=tuple)
+	"""
+	List of types that expected_type is composed of.
+	If expected_type is not of type UnionType, then it is just a tuple with one element.
+	"""
+
+	statica_sub_class: type[Statica] | None = dataclass_field(init=False, repr=False)
+	"""
+	Statica subclass if the expected_type is a Statica subclass or a union where one
+	of the types is a Statica subclass.
+	For example, if expected_type is `Union[Statica, int]`, then this will be `Statica`.
+	"""
+
+	# User-facing dataclass fields
 
 	min_length: int | None = None
 	max_length: int | None = None
@@ -51,44 +89,79 @@ class FieldDescriptor(Generic[T]):
 	def __set_name__(self, owner: Any, name: str) -> None:
 		self.name = name
 		self.owner = owner
-		self.expected_type = owner.__annotations__.get(name)
+		self.expected_type = get_type_hints(owner)[name]
+		self.sub_types = self.get_sub_types(self.expected_type)
+		self.statica_sub_class = self.get_statica_subclass(self.sub_types)
+
+	def get_sub_types(self, expected_type: Any) -> tuple[type | Any, ...]:
+		"""
+		Get all subtypes of the expected type.
+		For example, if the expected type is Union[str, int], return [str, int].
+		"""
+
+		if type(expected_type) is UnionType:
+			return tuple(t for t in expected_type.__args__)
 
-	@overload
-	def __get__(self, instance: None, owner: Any) -> FieldDescriptor[T]: ...
+		return (expected_type,)
 
-	@overload
-	def __get__(self, instance: object, owner: Any) -> T: ...
+	def get_statica_subclass(self, sub_types: tuple[type, ...]) -> type[Statica] | None:
+		"""
+		Get the first Statica subclass from the sub_types.
+		Returns None if no Statica subclass is found.
+		"""
+
+		try:
+			for sub_type in sub_types:
+				if issubclass(sub_type, Statica):
+					return sub_type
+		except TypeError:
+			pass
+		return None
 
 	def __get__(self, instance: object | None, owner: Any) -> Any:
+		"""
+		Get the value of the field from the instance.
+		For example user.age will invoke this method.
+		"""
+
 		if instance is None:
 			return self  # Accessed on the class, return the descriptor
 		return instance.__dict__.get(self.name)
 
 	def __set__(self, instance: object, value: T) -> None:
+		"""
+		Set the value of the field on the instance.
+		For example user.age = 30 will invoke this method.
+		"""
+
 		instance.__dict__[self.name] = self.validate(value)
 
 	def validate(self, value: Any) -> Any:
 		try:
+			# (1/4) Cast to required type if cast_to is provided
+
 			if self.cast_to is not None:
 				value = self.cast_to(value)
 
-			validate_type(value, self.expected_type)
-
-			if (
-				self.min_length is not None
-				or self.max_length is not None
-				or self.min_value is not None
-				or self.max_value is not None
-				or self.strip_whitespace is not None
-			):
-				value = validate_constraints(
-					value,
-					min_length=self.min_length,
-					max_length=self.max_length,
-					min_value=self.min_value,
-					max_value=self.max_value,
-					strip_whitespace=self.strip_whitespace,
-				)
+			# (2/4) On dict assignments initialize Statica subclass if it exists
+
+			if self.statica_sub_class is not None and isinstance(value, dict):
+				value = self.statica_sub_class.from_map(value)
+
+			# (3/4) Validate type of the value
+
+			validate_or_raise(value, self.expected_type)
+
+			# (4/4) Validate constraints if any are set
+
+			value = validate_constraints(
+				value,
+				min_length=self.min_length,
+				max_length=self.max_length,
+				min_value=self.min_value,
+				max_value=self.max_value,
+				strip_whitespace=self.strip_whitespace,
+			)
 
 		except TypeValidationError as e:
 			msg = f"{self.name}: {e!s}"
@@ -185,11 +258,7 @@ class StaticaMeta(type):
 		# Generate custom __init__ method
 
 		def statica_init(self: Statica, **kwargs: Any) -> None:
-			for field_name, field_type in annotations.items():
-				if field_name not in kwargs and not isinstance(None, field_type):
-					msg = f"Missing required field: {field_name}"
-					raise TypeValidationError(msg)
-
+			for field_name in annotations:
 				setattr(self, field_name, kwargs.get(field_name))
 
 		namespace["__init__"] = statica_init
@@ -218,23 +287,24 @@ class StaticaMeta(type):
 class Statica(metaclass=StaticaMeta):
 	@classmethod
 	def from_map(cls, mapping: Mapping[str, Any]) -> Self:
-		mapping_key_to_field_keys = {}  # Maps alias to field name
+		# Fields might have aliases, so we need to map them correctly.
+		# Here we map the chosen alias to the original field name.
+		# If no alias is provided, we use the field name itself.
+		# Priority: parsing alias > general alias > field name
+		mapping_key_to_field_keys = {}
 
 		for field_descriptor in get_field_descriptors(cls):
 			# Use alias for parsing if it exists
-			alias = field_descriptor.alias_for_parsing or field_descriptor.alias or field_descriptor.name
+			alias = (
+				field_descriptor.alias_for_parsing
+				or field_descriptor.alias
+				or field_descriptor.name
+			)
 			mapping_key_to_field_keys[alias] = field_descriptor.name
 
 		parsed_mapping = {mapping_key_to_field_keys[k]: v for k, v in mapping.items()}
 
-		instance = cls(**parsed_mapping)
-
-		# Go through type hints and set values
-		for attribute_name in get_type_hints(instance.__class__):
-			value = parsed_mapping.get(attribute_name)
-			setattr(instance, attribute_name, value)  # Descriptor __set__ validates
-
-		return instance
+		return cls(**parsed_mapping)  # Init function will validate fields
 
 	def to_dict(self) -> dict[str, Any]:
 		"""
@@ -243,7 +313,11 @@ class Statica(metaclass=StaticaMeta):
 		result = {}
 		for field_descriptor in get_field_descriptors(self.__class__):
 			# Use alias for serialization if it exists
-			alias = field_descriptor.alias_for_serialization or field_descriptor.alias or field_descriptor.name
+			alias = (
+				field_descriptor.alias_for_serialization
+				or field_descriptor.alias
+				or field_descriptor.name
+			)
 			result[alias] = getattr(self, field_descriptor.name)
 
 		return result
@@ -254,6 +328,11 @@ class Statica(metaclass=StaticaMeta):
 
 if __name__ == "__main__":
 
+	class User(Statica):
+		data: dict[str, int]
+
+	u = User.from_map({})
+
 	class Payload(Statica):
 		type_error_class = ValueError