Restalchemy

1. **`UTCDateTimeZ` Type for Explicit UTC Timezone Validation**
- Introduced the `UTCDateTimeZ` class, extending `UTCDateTime`, to enforce UTC timezone validation on datetime values.
- Ensures datetime objects include UTC timezone information via:
- `validate()` method for timezone checks.
- Overridden `from_simple_type` to return UTC-aware datetime objects.

2. **Model-View Conversion Mixins**
- Added mixins to simplify bidirectional conversion between model objects and simplified view representations.

3. **Thread-Local Context Management & Storage**
- **Refactored Context Handling**:
- Introduced customizable context classes via `ContextMiddleware` (supports dependency injection).
- Added `ContextWithStorage` for thread-isolated context storage using `threading.local()`.
- New `get_context()` utility to retrieve the current thread’s context.
- **Storage Class**:
- Added `Storage` for managing key-value pairs with read-only enforcement and thread safety.
- Supports `put()`, `get()`, and `delete()` operations.
- **Exceptions**:
- Added `ContextAlreadyInStorage`, `ContextIsNotExistsInStorage`, `StorageRuntimeException`, and `ReadOnlyStorage` for robust error handling.

1. **Refactored Error Handling**
- Centralized error response logic into `_construct_error_response` for consistency.
- Improved logging and exception handling flow in request processing.

2. **Enhanced Session & Context Management**
- Streamlined session lifecycle management in the `Context` class.
- Added detailed docstrings and error logging for better maintainability.

3. **Dependency Updates**
- Capped maximum versions of test requirements for stability.

---
**Contributors**: Eugene Frolov, Anton Kremenetsky, George Melikov

New Features

- **Introduce Decimal type**: The `decimal` module is now included to handle high precision arithmetic in financial and scientific calculations.

- **OpenAPI Schema Enhancements**:
- Added helpful functions for generating OpenAPI schema.
- Demonstrated how to manually override and set the OpenAPI specification for action operations, bypassing automatic generation.

Bug Fixes

- **Fix IS and IS NOT Filters in PostgreSQL Dialect**: A bug has been fixed affecting the functionality of `IS` and `IS NOT` filters in the PostgreSQL dialect.

Bug Fixes

Fixed Cached Queries
- **Problem:** After adding PostgreSQL support, cached queries produced `AttributeError: 'int' object has no attribute 'engine'` due to a parameter mismatch where `session=2` was incorrectly passed instead of `limit=2`.
- **Fix:** Corrected method signatures in `SessionQueryCache` to properly pass `session` and `limit` parameters. Updated query generation logic in `_get_hash` and `_get_hash_by_query` methods.
- **Tests:** Added functional tests for cached queries in MySQL:
- `test_get_one_all_with_cache`: Verifies cached objects are identical.
- `test_get_one_all_without_cache`: Ensures non-cached objects are distinct.

CLI Argument Handling for Database Tools
- Updated `register_common_db_opts` to use `register_cli_opts`, ensuring compatibility with CLI utilities like `ra-apply-migration`.
_This fixes issues where database arguments were not recognized by migration tools._

Some other changes

Reusable RESTService for Testing
- Modified `RESTService` constructor to accept a custom `app_root` parameter, allowing reuse in external test suites.
Example usage:
python
RESTService(app_root=custom_routes.Root) Custom route class for tests


---

**Full Commit Summary:**
- [`55eab8b`](https://github.com/infraguys/restalchemy/commit/55eab8b475e91db975a31649b0e19725cdfe2e45): Fix query cache parameter order, add cache tests.
- [`8d24f31`](https://github.com/infraguys/restalchemy/commit/8d24f31f440ff926779ccc5ce84d0dfbaba9409a): Make `RESTService` configurable for external testing.
- [`94f63f9`](https://github.com/infraguys/restalchemy/commit/94f63f9b69f015120695636ee22dcc41249f6d2c): Fix CLI option registration for database tools.

Features

**1. Core Framework Enhancements**
- **MultipartPacker Implementation**:
Introduced a specialized `MultipartPacker` to streamline handling of `multipart/form-data` requests, commonly used for file uploads.
- Extracts file data into a structured dictionary, with files mapped by their part names.
- Includes a `_multipart` flag to explicitly indicate multipart content processing.
- Designed for future extensibility (e.g., potential support for model JSON alongside files).

**2. Model Layer Improvements**
- **Base Model Classes**: Added reusable base models to encapsulate common fields and behaviors:
- **`ModelWithTimestamp`**: Automatically manages `created_at` and `updated_at` UTC timestamps on creation/update.
- **`ModelWithProject`**: Enforces immutable `project_id` for tenant-scoped resources.
- **`ModelWithNameDesc`**: Standardizes `name` and `description` fields (max 255 chars, empty string defaults).
- Promotes modularity, reduces redundancy, and simplifies future model development.

---

Improvements

**1. Routing System Refactor**
- **Base Controller for Route Filtering**:
- Created `RoutesListController` base class to centralize route discovery logic.
- Scans nested routes via `_get_target_route()` using `__TARGET_PATH__`.
- Filters collection routes using `is_collection_route()` checks.
- **Adopted in Controllers**:
- `RootController` and test `V1Controller` now inherit from `RoutesListController`, eliminating duplicate filtering code.
- **Testing Updates**:
- Expanded `TestVersionsResourceTestCase` to verify detection of multiple collection routes (e.g., `["notimplementedmethods", "vms"]`).

---

Implementation Notes
- **Routing**: Configure `__TARGET_PATH__` in controllers to define the root path for automatic route scanning.
- **Models**: Inherit from base models to leverage standardized fields and behaviors while minimizing boilerplate.
- **File Handling**: Use `MultipartPacker` to simplify file upload processing in API endpoints.

This release enhances maintainability, reduces code duplication, and provides foundational components for consistent API routing, model management, and file handling.

This release introduces minor improvements to database configuration management, adds support for multiple databases, and includes **breaking changes** for migration utilities.

Below are the key updates:

---

- **Migration Utilities CLI Parameter Rename**:
The parameter specifying the database connection string has been renamed from `--db-connection` to `--db-connection_url` to align with centralized naming conventions.
**Impact**: All scripts, commands, or workflows using `--db-connection` must update to `--db-connection_url`. This affects CLI commands for applying/rolling back migrations (e.g., `apply_migration.py`, `rollback_migration.py`).

---

- **Centralized Database Configuration**:
- New `config_opts.py` module standardizes common and database-specific options (PostgreSQL/MySQL), eliminating code duplication.
- Database constants (ports, URLs) are now defined in `constants.py`.
- **Multi-Database Support**:
- PostgreSQL and MySQL are now fully supported via dedicated engines (`PgSQLEngine`, `MySQLEngine`).
- Use `register_postgresql_db_opts()` or `register_mysql_db_opts()` to configure database-specific settings.
- **Connection Pooling Enhancements**:
- PostgreSQL: Configurable min/max pool sizes and timeouts.
- MySQL: Adjustable connection pool size.

---

- **Reduced Code Duplication**: Shared logic for migration scripts (CLI options) is now centralized.
- **Maintainability**: Safer updates via unified constants and configuration functions.
- **Flexibility**: Simplified process for adding new database backends or adjusting connection parameters.

---

**Upgrade Instructions**:
- Replace all instances of `--db-connection` with `--db-connection_url` in CLI commands.
- Update configuration references from `CONF.db.connection` to `CONF.db.connection_url`.
- Review `constants.py` and `config_opts.py` for new database configuration defaults.

This release lays the groundwork for future database integrations while improving consistency and scalability.

New Features

🚀 Email Data Type with Validation
Added a new `Email` type with robust validation using the `email-validator` library:
- **Validation features**:
- Length constraints: **5-254 characters** (supports minimal RFC-compliant emails like `ab.c`)
- Format validation (e.g., `userexample.com`)
- Optional domain verification via MX records (`check_deliverability=True`)
- **OpenAPI integration**:
- Automatically adds `format: email` to schemas for Swagger/OpenAPI docs.
- Extendable via `String` type kwargs (e.g., `String(openapi_format="password")` for secret fields).

**Example**:
python
from restalchemy.dm import models, properties, types

Basic validation
types.Email().validate("ab.c") ✅ Valid

Domain verification
types.Email(check_deliverability=True).validate("ab.c") ❌ Fails (no MX records)

class User(models.ModelWithUUID):
email = properties.property(
types.Email(max_length=128),
required=True
)

User(email="validexample.com") Success
User(email="invalid") Raises ValidationError


---

Improvements

🔧 Enhanced Request Body Handling
- **Byte support**:
- Requests now use `webob` to convert bodies to bytes, enabling raw data handling (e.g., file uploads).
- **UTF-8 encoding**:
- Replaced legacy `six.b` (Python 3's `latin-1` encoding) with explicit UTF-8 charset.

---

Maintenance

🗑️ Python 2.7 Deprecation
- **Removed `six` module**:
- All Python 2.7 compatibility code has been dropped.
- **Code cleanup**:
- Refactored to use native Python 3 syntax.

---

Dependency Changes
- Added: `email-validator>=2.2.0` to `requirements.txt`.

---

This release delivers stronger data validation, modernized request handling, and a cleaner Python 3 codebase. 🎉