feat: add options support to Store for format-specific write options

[james-willis]

Summary

• Adds an options: dict[str, str] | None field to the Store dataclass, allowing users to pass format-specific Spark DataFrameWriter options (e.g. header, delimiter, ignoreNullFields) when storing query results to cloud storage.
• Options are defensively copied, empty dicts are normalized to None, and the field is omitted from the WebSocket request when not set (backward compatible).
• Updates Store.for_download() to accept an optional options parameter.
• Includes 15 pytest tests covering options handling, serialization, and JSON round-tripping.
• Adds "Store options" section to README with usage examples.

PEP 249 (DB-API 2.0) compliance

This change does not alter the PEP 249 interface. The store keyword parameter on cursor.execute() was introduced upstream in #55/#56 as a vendor extension, which PEP 249 explicitly permits:

"During the lifetime of DB API 2.0, module authors have often extended their implementations beyond what is required by this DB API specification."

The standard execute(operation [, parameters]) signature is preserved — store is keyword-only and optional, so callers using the PEP 249 API are unaffected. This PR only adds an attribute (options) to the vendor-specific Store dataclass; no cursor, connection, or driver signatures change.

Usage

from wherobots.db import Store, StorageFormat

# CSV without headers and a custom delimiter
store = Store.for_download(
    format=StorageFormat.CSV,
    options={"header": "false", "delimiter": "|"},
)

# GeoJSON preserving null fields
store = Store.for_download(
    format=StorageFormat.GEOJSON,
    options={"ignoreNullFields": "false"},
)

Related

• sql-session #190 — server-side support for options field on Store (merged/ready)
• wherobots-jdbc-driver BUG-260 lower dependencies versions to fit into airflow constraints #19 — JDBC driver support for store options (merged/ready)
• Supersedes feat: add Store and StorageFormat with options support for result storage #57 which was opened before main had the Store infrastructure from fix: retry transient HTTP errors (502/503/504/429) during session polling #55/feat: add execution progress handler #56

[salty-hambot]

Clean addition — the options field is well-designed with defensive copying, empty-dict normalization, and backward-compatible wire format. PEP 249 compliance is unaffected: store was already a vendor extension kwarg on execute(), and this PR only adds a field to the vendor-specific Store dataclass. No cursor, connection, or driver signatures change.

Two suggestions worth considering as the Store surface area grows: extracting serialization into Store.to_dict() (eliminates duplication in both connection.py and tests), and eventually locking down mutability.

Pre-existing note (not caused by this PR): cursor.fetchone() / fetchall() will TypeError when store is configured, because __get_results() returns None and the callers index into it unconditionally. Worth a follow-up ticket.