Changelog

# Serilux Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.5.0] - 2026-03-02

### Added
- **Type-Hint Auto-Discovery**: Fields with type hints are now automatically registered for serialization, significantly reducing boilerplate.
- **Dataclass Native Support**: Standard Python `dataclasses` are now supported as `Serializable` objects without manual field registration.
- **Constructor Parameter Mapping**: Improved deserialization to support objects with required `__init__` arguments by mapping them from serialized data.
- **ObjectFactory**: New internal component for intelligent object instantiation during deserialization.
- **Testing Utility**: Added `SerializableRegistry.clear_registry()` to facilitate clean test environments.

### Changed
- **Registration Flexibility**: Relaxed `__init__` validation in `@register_serializable` to allow classes with required parameters (mapped from data).
- **Initialization Robustness**: `serialize()` and `deserialize()` now ensure internal state is initialized even if `__init__` was bypassed (common in dataclasses).

## [0.4.0] - 2026-03-02

### Added
- **Test coverage gate**: Enforced 80% minimum test coverage in CI
- **Edge case tests**: Added 19 new tests for edge cases and security validation
- **Lambda security tests**: Added 6 new security tests for lambda deserialization
- **Nesting depth protection**: Added `max_depth` parameter to `serialize()` to prevent stack overflow (default: 100)
- **AST validation**: Added AST parsing and validation before lambda expression evaluation
- **Function whitelist**: Implemented safe function whitelist for lambda expressions
- **Custom exception hierarchy**: Added 10 specific exception types for better error handling
  - `SeriluxError` (base exception)
  - `SerializationError`, `DeserializationError`
  - `ClassNotFoundError`, `ValidationError`
  - `CircularReferenceError`, `DepthLimitError`
  - `CallableError`, `InvalidFieldError`, `UnknownFieldError`
- **Type stub file**: Added `serilux/__init__.pyi` for better IDE support and type checking
- **Pre-commit hooks**: Added comprehensive pre-commit configuration for code quality
- **CLAUDE.md**: Added project guide for Claude Code AI assistant
- **Architecture documentation**: Added comprehensive architecture documentation in `docs/architecture.md`

### Fixed
- **Object Identity Preservation**: Fixed a bug where shared object references were broken during deserialization when an object was present in both containers and single fields.
- **Deserialization Phase 2**: Simplified and corrected Phase 2 loop to use `deserialize_item` consistently, ensuring all nested objects are correctly resolved from the registry.
- **Field Determinism**: Fixed `add_serializable_fields` to preserve field registration order, ensuring deterministic serialization output.
- **Import Error**: Fixed a missing `SeriluxError` import in `serializable.py` that caused `NameError` during some error conditions.

### Changed
- **CI configuration**: Replaced `black` with `ruff format` for consistency
- **Python version**: Fixed mypy configuration from Python 3.7 to 3.8
- **Lambda deserialization**: Enhanced security with AST validation and function whitelisting
- **Code style**: Fixed `SerializableClass` naming to `serializable_class`
- **Error handling**: Replaced generic `ValueError` with specific custom exceptions throughout codebase

### Security
- **Nesting depth limit**: Added protection against stack overflow from deeply nested structures
- **Lambda injection protection**: Added AST validation to prevent code injection via lambda expressions
- **Function call restrictions**: Lambda expressions can only call whitelisted safe functions
- **Enhanced validation**: Improved input validation and error reporting

### Testing
- Test coverage increased from 71% to 85%
- Added 25 new tests (from 57 to 82 total)
- Added tests for serialization depth limits
- Added tests for lambda security validation
- Added tests for edge cases and error handling
- Added tests for custom exception types

### Documentation
- Updated `CONTRIBUTING.md` with comprehensive development workflow
- Added `docs/architecture.md` with detailed architecture explanation
- Added type hints via type stub file for better IDE support

### Developer Experience
- Added pre-commit hooks for automated code quality checks
- Added mypy type checking to CI (non-blocking)
- Improved error messages with context (object type, field name)
- Better exception hierarchy for precise error handling

## [0.3.1] - 2026-01-03

### Changed
- Updated Python version support to 3.8-3.14
- Integrated CI workflow with uv for automated testing and building

## [0.2.1] - 2025-12-29

### Added

- **GitHub Actions workflow**: Automated build and release workflow with automatic release notes generation
- **Release scripts**: Scripts for generating release notes from CHANGELOG.md or git commits

### Improved

- **Documentation**: Updated documentation and README
- **Code quality**: Added linting configuration (flake8) for better code quality
- **Nested object support**: Enhanced support for deeply nested objects in serialization

### Documentation

- **Release automation**: Added scripts and documentation for automated releases
- **GitHub integration**: Integrated GitHub Actions for automated package building and publishing

## [0.2.0] - 2025-12-28

### Added

- **Callable Serialization**: Full support for serializing and deserializing callable objects (functions, methods, builtins)
- **Lambda Expression Support**: Serialize lambda functions and function bodies as expressions
- **ObjectRegistry**: Generic registry for looking up objects by ID and class name during deserialization
- **Two-Phase Deserialization**: Enhanced deserialization with pre-creation phase for handling circular references
- **Automatic Callable Handling**: Serializable objects automatically serialize callable fields
- **Expression Extraction**: Extract lambda expressions and function bodies from source code
- **Registry-Based Method Deserialization**: Methods can be deserialized using ObjectRegistry
- **Deeply Nested Container Support**: Full support for arbitrarily deep nesting of containers (dict -> list -> dict -> Serializable, etc.)
- **Automatic Registration for Single Object Fields**: Single object fields (not in containers) are now automatically registered in Phase 2
- **Class Name Conflict Detection**: ``@register_serializable`` now detects and prevents class name conflicts, raising ``ValueError`` when different classes with the same name are registered

### Enhanced

- **Serializable.deserialize**: Now supports `registry` parameter for callable deserialization
- **Serializable.serialize**: Recursively handles nested containers at any depth, automatically serializing Serializable objects
- **Serializable._serialize_value**: Now recursively processes nested dicts and lists
- **Phase 1 Deserialization**: Recursively finds and registers all Serializable objects in nested structures
- **Phase 2 Deserialization**: Automatically registers single object fields immediately after creation
- **deserialize_item**: Checks registry first before creating new objects, ensuring pre-registered objects are reused
- **SerializableRegistry.register_class**: Now detects class name conflicts and raises ``ValueError`` when attempting to register a different class with the same name
- **Error Messages**: Improved error messages for missing classes, deserialization failures, and class name conflicts

### Changed

- **Version**: Bumped to 0.2.0 to reflect major feature additions
- **Module Structure**: Complete serialization framework migrated from Routilux

### Documentation

- Updated API reference for callable serialization
- Added examples for callable and lambda expression serialization

### Testing

- Added comprehensive tests for callable serialization
- Tests for lambda expression serialization
- Tests for ObjectRegistry functionality

## [0.1.0] - 2025-07-01

### Added

- **Initial Release**: First release of Serilux serialization framework
- **Serializable Base Class**: Core `Serializable` class for object serialization
- **Automatic Type Registration**: `@register_serializable` decorator for automatic class registration
- **SerializableRegistry**: Class registry for managing serializable types
- **Nested Object Support**: Automatic serialization/deserialization of nested Serializable objects
- **List and Dictionary Support**: Automatic handling of lists and dictionaries containing Serializable objects
- **Strict Mode**: Optional strict mode for deserialization validation
- **Validation Functions**: `check_serializable_constructability` and `validate_serializable_tree` for pre-serialization validation
- **Field Management**: `add_serializable_fields` and `remove_serializable_fields` methods
- **Comprehensive Documentation**: Full Sphinx documentation with examples
- **Test Suite**: Comprehensive test coverage
- **Examples**: Practical usage examples

### Documentation

- Initial documentation structure
- API reference documentation
- User guide with examples
- Quick start guide

### Testing

- Unit tests for core functionality
- Integration tests for nested objects
- Validation tests
- Registry tests

---

**Note**: This is the initial release extracted from the Routilux project's serializable module.

Added

  • Callable Serialization: Full support for serializing and deserializing callable objects (functions, methods, builtins)

  • Lambda Expression Support: Serialize lambda functions and function bodies as expressions

  • ObjectRegistry: Generic registry for looking up objects by ID and class name during deserialization

  • Two-Phase Deserialization: Enhanced deserialization with pre-creation phase for handling circular references

  • Automatic Callable Handling: Serializable objects automatically serialize callable fields

  • Expression Extraction: Extract lambda expressions and function bodies from source code

  • Registry-Based Method Deserialization: Methods can be deserialized using ObjectRegistry

  • Deeply Nested Container Support: Full support for arbitrarily deep nesting of containers (dict -> list -> dict -> Serializable, etc.)

  • Automatic Registration for Single Object Fields: Single object fields (not in containers) are now automatically registered in Phase 2

  • Class Name Conflict Detection: @register_serializable now detects and prevents class name conflicts, raising ValueError when different classes with the same name are registered

Enhanced

  • Serializable.deserialize: Now supports registry parameter for callable deserialization

  • Serializable.serialize: Recursively handles nested containers at any depth, automatically serializing Serializable objects

  • Serializable._serialize_value: Now recursively processes nested dicts and lists

  • Phase 1 Deserialization: Recursively finds and registers all Serializable objects in nested structures

  • Phase 2 Deserialization: Automatically registers single object fields immediately after creation

  • deserialize_item: Checks registry first before creating new objects, ensuring pre-registered objects are reused

  • SerializableRegistry.register_class: Now detects class name conflicts and raises ValueError when attempting to register a different class with the same name

  • Error Messages: Improved error messages for missing classes, deserialization failures, and class name conflicts

Changed

  • Version: Bumped to 0.2.0 to reflect major feature additions

  • Module Structure: Complete serialization framework migrated from Routilux

Documentation

  • Updated API reference for callable serialization

  • Added examples for callable and lambda expression serialization

  • Comprehensive user guide for callable serialization

Testing

  • Added comprehensive tests for callable serialization

  • Tests for lambda expression serialization

  • Tests for ObjectRegistry functionality

Version 0.1.0

Added

  • Initial Release: First release of Serilux serialization framework

  • Serializable Base Class: Core Serializable class for object serialization

  • Automatic Type Registration: @register_serializable decorator for automatic class registration

  • SerializableRegistry: Class registry for managing serializable types

  • Nested Object Support: Automatic serialization/deserialization of nested Serializable objects

  • List and Dictionary Support: Automatic handling of lists and dictionaries containing Serializable objects

  • Strict Mode: Optional strict mode for deserialization validation

  • Validation Functions: check_serializable_constructability and validate_serializable_tree for pre-serialization validation

  • Field Management: add_serializable_fields and remove_serializable_fields methods

  • Comprehensive Documentation: Full Sphinx documentation with examples

  • Test Suite: Comprehensive test coverage

  • Examples: Practical usage examples