Add IO and registry documentation; update guides

Added new documentation for lzl.io.file, lzl.io.persistence, and lzl.io.ser modules. Updated and expanded guides for lzl.load, lzl.logging, lzl.pool, lzl.proxied, lzo.registry, lzo.types, and lzo.utils. Improved the main index page with flash examples and feature highlights. Updated mkdocs.yml navigation to include new IO subpages.

Author: trisongz

docs/api/lzl/io/file.md

@@ -0,0 +1,124 @@
+# lzl.io.file - Unified File Operations
+
+The `lzl.io.file` module provides a powerful, unified abstraction for file system operations, supporting both local and cloud storage (S3, MinIO, R2) with synchronous and asynchronous APIs. It automatically selects the appropriate backend based on the file path scheme.
+
+## Overview
+
+The `File` class is the main entry point. It acts as a factory that instantiates the correct concrete path object (e.g., `Path` for local files, `FileS3Path` for S3).
+
+::: lzl.io.file
+    options:
+      members:
+        - File
+
+## Supported Schemes
+
+- **Local Files**: `/path/to/file`, `relative/path`
+- **AWS S3**: `s3://bucket/key`
+- **MinIO**: `minio://bucket/key`
+- **Cloudflare R2**: `r2://bucket/key`
+
+## Usage Examples
+
+### Basic File I/O
+
+```python
+from lzl.io import File
+
+# Write text (sync)
+File("data.txt").write_text("Hello World")
+
+# Read text (async)
+content = await File("data.txt").async_read_text()
+
+# Check existence
+if await File("data.txt").async_exists():
+    print("File exists!")
+```
+
+### Cloud Storage (S3)
+
+```python
+from lzl.io import File
+
+# Working with S3 paths
+s3_file = File("s3://my-bucket/data.csv")
+
+# Read bytes
+data = await s3_file.read_bytes()
+
+# Get metadata
+size = s3_file.size
+last_modified = s3_file.stat().st_mtime
+```
+
+### Pydantic Integration
+
+`File` is fully compatible with Pydantic v1 and v2, making it ideal for configuration models.
+
+```python
+from pydantic import BaseModel
+from lzl.io import File
+
+class Config(BaseModel):
+    dataset_path: File
+    output_dir: File
+
+# Validates and converts strings to File objects
+config = Config(
+    dataset_path="s3://data/sets/train.parquet",
+    output_dir="/tmp/output"
+)
+
+print(config.dataset_path.scheme) # 's3'
+```
+
+### Custom Loaders
+
+You can register custom loaders for specific file extensions.
+
+```python
+from lzl.io import File
+import json
+
+def load_json(file: File):
+    return json.loads(file.read_text())
+
+# Register the loader
+File.register_loader(".json", load_json)
+
+# Now you can load directly (implementation dependent on registered hooks)
+# data = File("config.json").load() 
+```
+
+## Advanced Features
+
+### Directory Management
+
+```python
+# Get the parent directory
+parent = File.get_dir("path/to/file.txt")
+
+# Check object size
+size = File.get_object_size("some data")
+print(f"Size: {size.human_readable}")
+```
+
+## Spec and Path Types
+
+Deep dive into the underlying path implementations and specifications.
+
+::: lzl.io.file.spec.main
+::: lzl.io.file.path
+
+## Configuration
+
+Configure storage backends and behavior.
+
+::: lzl.io.file.configs
+
+## Utilities
+
+Helper functions for file operations.
+
+::: lzl.io.file.utils

docs/api/lzl/io/persistence.md

@@ -0,0 +1,116 @@
+# lzl.io.persistence - Data Persistence
+
+The `lzl.io.persistence` module offers robust persistence mechanisms, providing a dictionary-like interface backed by various storage engines (SQLite, Redis, Object Storage). It supports caching, asynchronous access, and data serialization.
+
+## Persistent Dictionary
+
+The `PersistentDict` is the core class. It mimics a standard Python dictionary but persists its contents.
+
+::: lzl.io.persistence.main
+    options:
+      members:
+        - PersistentDict
+
+## Initialization
+
+```python
+from lzl.io.persistence import PersistentDict
+
+# Local SQLite backend (default if no scheme provided)
+cache = PersistentDict("my_app_cache", serializer="json")
+
+# Redis backend
+redis_cache = PersistentDict(
+    "my_redis_cache", 
+    backend="redis", 
+    base_key="app:v1",
+    expiration=3600
+)
+
+# Object Storage backend (S3)
+s3_cache = PersistentDict(
+    "s3_cache",
+    base_key="s3://my-bucket/cache/prefix",
+    serializer="pickle"
+)
+```
+
+## Features
+
+### Async Support
+
+Most methods have an `async` equivalent prefixed with `a` (e.g., `aget`, `aset`, `adelete`).
+
+```python
+await cache.aset("key", "value")
+value = await cache.aget("key")
+```
+
+### Context Managers & Locking
+
+Ensure data consistency with context managers that handle locking.
+
+```python
+# Sync context
+with cache.acquire_context():
+    cache["key"] = "new_value"
+    # Changes are flushed on exit
+
+# Async context
+async with cache.acquire_acontext():
+    await cache.aset("key", "async_value")
+```
+
+### Mutation Tracking
+
+`PersistentDict` tracks changes to mutable objects (like lists or dicts) retrieved from the cache and saves them back if they are modified within a tracking context.
+
+```python
+with cache.track_changes("user:123", "get") as user_data:
+    user_data["login_count"] += 1
+# user_data is automatically saved back to the backend if it changed
+```
+
+### Math & Set Operations
+
+Native support for atomic increments and set operations (especially useful with Redis).
+
+```python
+# Increment
+cache.incr("counter", 1)
+
+# Set operations
+cache.sadd("users", "alice", "bob")
+members = cache.smembers("users")
+```
+
+## Backends
+
+Supported backends implementations.
+
+- **Local**: Stores data in local files.
+- **SQLite**: High-performance, single-file database (Recommended for local persistence).
+- **Redis**: Distributed in-memory store.
+- **Object Storage**: S3, MinIO, R2 for cloud persistence.
+
+::: lzl.io.persistence.backends
+
+## Serialization
+
+Data is serialized before storage. Supported formats:
+- `json`: Human-readable, widely supported.
+- `pickle`: Python-specific, supports complex objects.
+- `msgpack`: Binary, efficient.
+
+You can configure compression (gzip, zstd) alongside serialization.
+
+## Metrics
+
+Attach metrics to track usage or values within the dictionary.
+
+```python
+from lzl.io.persistence.addons import CountMetric
+
+cache.configure_metric("hits", kind="count")
+cache.metrics["hits"].incr()
+```

docs/api/lzl/io/ser.md

@@ -0,0 +1,25 @@
+# lzl.io.ser - Serialization
+
+High-performance serialization utilities supporting JSON, Pickle, MsgPack, and compression.
+
+## Main Interface
+
+::: lzl.io.ser.base
+
+## Formatters
+
+::: lzl.io.ser._json
+::: lzl.io.ser._pickle
+::: lzl.io.ser._msgpack
+
+## Usage
+
+```python
+from lzl.io.ser import serialize, deserialize
+
+data = {"complex": "object"}
+
+# Auto-detect format based on context or configuration
+s = serialize(data, format="json")
+d = deserialize(s, format="json")
+```

docs/api/lzl/load.md

@@ -1,63 +1,70 @@
 # lzl.load - Lazy Loading
 
-The `lzl.load` module provides utilities for lazy loading of modules and dependencies, enabling deferred imports and reducing startup time.
+The `lzl.load` module provides the `LazyLoad` proxy and other utilities for deferred imports. This pattern drastically reduces application startup time by only loading heavy dependencies when they are first accessed.
 
-## Module Reference
+## Key Components
 
-::: lzl.load
-    options:
-      show_root_heading: true
-      show_source: true
+### LazyLoad
 
-## Overview
+The core proxy class. It intercepts attribute access to trigger the import.
 
-Lazy loading defers the import of modules until they are actually needed, which can significantly improve application startup time and reduce memory footprint.
+::: lzl.load.main
+    options:
+        members:
+            - LazyLoad
+            - lazy_load
+            - load
+            - reload
 
-## Usage Examples
+## Usage Guide
 
 ### Basic Lazy Loading
 
+Instead of top-level imports, define a proxy.
+
 ```python
 from lzl.load import LazyLoad
 
-# Create a lazy reference to a module
-numpy = LazyLoad('numpy')
+# 'numpy' is NOT imported yet
+np = LazyLoad("numpy")
 
-# The module is only imported when accessed
-array = numpy.array([1, 2, 3])  # Import happens here
+def process_data(data):
+    # 'numpy' is imported here, on the first attribute access
+    return np.array(data)
 ```
 
-### Lazy Loading with Aliases
+### Handling Optional Dependencies
 
-```python
-from lzl.load import LazyLoad
-
-# Load with an alias
-pd = LazyLoad('pandas', 'pd')
+You can configure `LazyLoad` to automatically install missing packages (though use with caution in production).
 
-# Use as normal
-df = pd.DataFrame({'a': [1, 2, 3]})
+```python
+# If 'pandas' is missing, it will attempt to pip install it
+pd = LazyLoad("pandas", install_missing=True)
 ```
 
-### Conditional Imports
+### Dependency Chains
 
-```python
-from lzl.load import LazyLoad
+If a module depends on another lazy module being loaded first (e.g., for side effects), you can declare dependencies.
 
-# Only import if actually used
-optional_module = LazyLoad('some.optional.module')
-
-if needs_feature:
-    optional_module.do_something()
+```python
+# specific_setup must be loaded before my_module
+setup = LazyLoad("my_app.specific_setup")
+mod = LazyLoad("my_app.my_module", dependencies=setup)
 ```
 
-## Benefits
+### Type Checking
 
-- **Faster Startup**: Modules are only imported when needed
-- **Reduced Memory**: Unused modules don't consume memory
-- **Simplified Dependencies**: Optional dependencies can be handled gracefully
-- **Better Testing**: Mock imports more easily in tests
+For static analysis (mypy/pyright), you can use `TYPE_CHECKING` blocks to keep type hints working while using lazy loading at runtime.
+
+```python
+from typing import TYPE_CHECKING
+from lzl.load import LazyLoad
 
-## Implementation Details
+if TYPE_CHECKING:
+    import pandas as pd
+else:
+    pd = LazyLoad("pandas")
 
-The `LazyLoad` class uses Python's import system to defer module loading. When you access an attribute on a lazy-loaded module, the actual import is triggered transparently.
+def get_df() -> "pd.DataFrame":
+    return pd.DataFrame()
+```