Metadata-Version: 2.4
Name: vfsi-fsspec
Version: 0.1.7
Summary: Shared fsspec engine for VFSI vectorized filesystem backends
Author-email: Ming Chen <v.mingchen@gmail.com>
License-Expression: MIT OR Apache-2.0
Project-URL: Homepage, https://github.com/vmingchen/vnfs
Project-URL: Repository, https://github.com/vmingchen/vnfs
Project-URL: Issues, https://github.com/vmingchen/vnfs/issues
Keywords: vfsi,fsspec,filesystem,vectorized-io
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Requires-Dist: fsspec<2027.0.0,>=2024.12.0
Dynamic: license-file

# vfsi-fsspec

`vfsi-fsspec` is the backend-neutral buffering, batching, caching, callback,
and transaction engine shared by the `nfs4fs` and `vsmbfs` distributions. Most
users should install one of those protocol packages rather than this package
directly.

Upgrade the protocol package (`nfs4fs` or `vsmbfs`) together with
`vfsi-fsspec`. The shared engine requires native `read_all_many` support for
per-call byte budgets and rejects older extensions before connecting; it never
falls back to an unbounded read.

Partial open-ended `cat_file` reads and all open-ended `cat_ranges` reads use
the EOF observed during size validation as their exclusive end. Later growth
is excluded from that read, so it cannot exceed the checked allocation budget;
truncation may produce a short read. This bounds the range, not a snapshot of
its contents.
Whole-file `cat_file` reads (normalized start zero, no end) retain the native
read-to-EOF fast path, which enforces the allocation budget while reading.

Transactional writes require both a native creation-permissions API and a backend
with POSIX permission support. Unsupported backends, including current SMB,
reject transactional writes before allocating a spool or creating staging files;
ordinary I/O remains supported. A method signature alone is not a capability.
