Improvements to Relationships, updated documentation

[robinvandernoord]

Summary

Enhance relationship handling with lazy loading policies and explicit relationship control, providing better flexibility and performance optimization for data fetching.

Changes

New Features

Lazy Loading Policies (lazy parameter)

• "forbid" - Raise an error when accessing unjoined relationships (strictest, prevents N+1 queries)
• "warn" - Return empty value with RuntimeWarning (matches previous behavior)
• "ignore" - Return empty value silently
• "tolerate" - Fetch data on-demand with performance warning (new default)
• "allow" - Fetch data on-demand silently

Configure globally via TypeDALConfig.lazy_policy or per-relationship via relationship(..., lazy="forbid").

Explicit Relationships (explicit parameter)
Mark relationships as only loading when explicitly requested:

tags_tolerate = relationship(
    list["Tag"],
    on=...,
    lazy="tolerate",
    explicit=True  # only loaded when explicitly joined
)

Enhanced join() API

• Now accepts Relationship instances directly: Article.join(Article.tags, method="inner")
• Handles mixed string/instance arguments: Article.join("author", Article.tags)
• Better error handling for conflicting condition and on parameters
• Respects explicit=True in bare .join() calls (only joins explicitly requested relationships)

Improved Descriptor Behavior

• Added __set_name__ to automatically track relationship field names
• Implements lazy loading with configurable policies in __get__
• Graceful fallback when lazy loading fails

Configuration

• New TypeDALConfig.lazy_policy setting (default: "tolerate")
• Can be set via pyproject.toml [tool.typedal] section
• Per-relationship override via lazy parameter

Other Improvements

• Better error messages for relationship configuration conflicts
• Type annotation improvements throughout
• Added __eq__ method to TypedTable instances for row-based comparison

Testing

• Added comprehensive tests for all lazy loading policies
• Tests for explicit relationships
• Tests for direct Relationship instance joins
• Verified backward compatibility with existing join patterns

Documentation

This release includes a comprehensive documentation update covering the changes in this release as well as several previous releases:

• 1. Getting Started - Added references to configuration options and py4web setup
• 2. Defining Tables - Updated with clearer navigation to the query building guide
• 3. Building Queries - Enhanced with .where() examples, .orderby() usage, raw SQL expressions, and links to relationships documentation
• 4. Relationships - Expanded with lazy loading policies, explicit relationships, alternative join syntax, and nested relationship examples
• 5. py4web & web2py - (existing)
• 6. Migrations - Streamlined with clearer minimal configuration and simplified instructions
• 7. Advanced Configuration - New comprehensive guide covering all TypeDAL config options, multiple connections, environment variables, and lazy policies
• 8. Mixins - Renamed from page 7, updated with modern examples and class method patterns
• Added cross-references between related documentation pages throughout