committed 01:49AM - 07 Jul 26 UTC
Give every filesystem source a uniform, self-documenting reader-option
channel c…arried in the URI fragment (file://book.xlsx#sheet=quotes)
instead of overloading --source-table. A format hint and named hints
coexist in one fragment (feed.dat#csv&sheet=quotes).
- router.parse_fragment() splits the trailing #fragment into
(path, format_hint, hints): a known-format token stays the format
hint, key=value pairs (parse_qsl: percent-decoded, =-partitioned,
blank values kept, duplicate keys last-wins) become hints. It is
all-or-nothing: a fragment with any segment that is neither a pair
nor a single known format is left literal, so a real # in a path
(/feeds/vendor#1/data.csv) keeps working; percent-encode a # as %23
to force a fragment-looking tail literal.
- split_format_hint() becomes a thin (path, format_hint) wrapper over
parse_fragment, so determine_endpoint and every existing caller keep
their contract unchanged.
- FilesystemReference.page (previously set but read nowhere) is replaced
by hints: dict[str, str], threaded through the local, GCS, S3 and SFTP
sources. blob_hints() mirrors parse_uri's carrier choice so hints track
the file actually loaded across both the --source-table and the
deprecated URI-path forms.
No built-in reader consumes hints yet: this lands the channel and the
page->hints migration with zero read-behavior change. Source-only; the
file:// destination parser is untouched.