RemoteFile¶

RemoteFile is a read-only Caterva2 fixed-chunk SChunk byte stream. It is returned by lazy service leaf opening or RemoteStore file lookup. Discovery and file metadata do not fetch payload. Ordinary files such as Markdown, JPEG, and PDF published as compressed byte streams are supported; there is no Python object deserialization or implicit interpretation as an array.

import blosc2

with blosc2.open("https://cat2.cloud/demo/@public/examples/README.md") as file:
    prefix = file.read_bytes(0, min(file.nbytes, 4096))
    file.download("README.md")

read_bytes(start, stop) returns original bytes, with at most 16 MiB per call. The omitted stop means the file end, not an unbounded streaming read. Use download for larger files. A chunk can contain more data than the requested range: transfers are chunk-granular, bounded at 32 MiB compressed and 256 MiB decoded per chunk. Oversized/irregular streams require rechunking on the server. Generic fixed-chunk typed SChunks expose their raw byte representation; they do not imply a text/image/document format.

Downloads stage beside the destination, then publish completed original bytes. Existing destinations are not overwritten unless overwrite=True is explicit. No-overwrite publication uses a hard link to prevent concurrent-creation races; the destination filesystem must support hard links. progress(done, total) and cancel() callbacks run on the calling thread. Cancellation or failure removes only the operation’s staging file and preserves any previous destination.

Cache policy/allowance, traffic, and lifetime are shared with the source owner. cache_bytes includes other leaves in that owner. MEMORY/DISK retain compressed chunks; NONE retains no payload between calls. Transient decoded buffers are separately bounded, not included in retained cache bytes. Sources must remain immutable until explicit refresh; returned children outlive their parent handle. save of a file reference is intentionally unsupported; download is an original-byte export, not a reference archive. Explicit nonlazy URLPath input still requires lazy=True for byte-stream access.

class blosc2.RemoteFile[source]¶

A lazy, read-only Caterva2 byte stream.

read_bytes(start, stop) returns original bytes (at most 16 MiB per call). download(destination) streams original bytes with atomic publication and no overwrite by default. Chunk work is limited to 32 MiB compressed / 256 MiB decoded; oversized or irregular streams require server-side rechunking. Caches and lifetime are shared with the containing RemoteStore owner.

Attributes:

attrs: Read-only user metadata for the selected remote object.
cache_bytes: Retained bytes for the shared owner, including other leaves.
cache_policy: Configured payload-retention policy.
cbytes
chunksize
info
max_cache_bytes: Configured compressed-payload allowance.
media_type: A filename-based MIME hint, not a guarantee about the payload.
metadata_bytes
name
nbytes
nchunks
source: Credential-free descriptor for the selected remote object.
traffic: Source-read accounting for this object or its shared owner.

Methods

`close`()	Release resources owned by this handle.
`download`(destination, *[, overwrite, ...])	Stream original bytes, publishing only on success.
`read_bytes`([start, stop])	Read an explicitly bounded byte interval; omitted stop means end of file.

property attrs¶: Read-only user metadata for the selected remote object.

property cache_bytes¶: Retained bytes for the shared owner, including other leaves.

property cache_policy¶: Configured payload-retention policy.

close()[source]¶: Release resources owned by this handle.

download(destination, *, overwrite=False, progress=None, cancel=None)[source]¶

Stream original bytes, publishing only on success.

progress(done, total) and cancel() run on the caller’s thread. A false overwrite uses an atomic hard-link publish to avoid races, or a checked rename on Emscripten’s single-threaded virtual filesystem.

property max_cache_bytes¶: Configured compressed-payload allowance.

property media_type¶: A filename-based MIME hint, not a guarantee about the payload.

read_bytes(start=0, stop=None)[source]¶: Read an explicitly bounded byte interval; omitted stop means end of file.

property source¶: Credential-free descriptor for the selected remote object.

property traffic¶: Source-read accounting for this object or its shared owner.