Skip to content

Capabilities

Capability

Bases: Enum

Operations a backend may support.

Most values gate one or more Store methods; some are quality flags that inform callers about backend behaviour without gating a specific method (see ATOMIC_MOVE, SEEKABLE_READ, LAZY_READ). Use Store.supports() to query at runtime.

Values:

Core I/O

  • READ -- Stream or bulk-read file content. Gates Store.read() and Store.read_bytes().
  • WRITE -- Create or overwrite files. Gates Store.write().
  • DELETE -- Remove files and folders. Gates Store.delete() and Store.delete_folder().

Navigation

  • LIST -- Enumerate files and subfolders. Gates Store.list_files() and Store.list_folders().
  • GLOB -- Native pattern matching against file paths. Gates Store.glob(). Not all backends support this — use ext.glob.glob_files() as a portable fallback.

File operations

  • MOVE -- Rename or relocate a file within the same backend. Gates Store.move().
  • COPY -- Duplicate a file within the same backend. Gates Store.copy().

Atomic variants

  • ATOMIC_WRITE -- Write via temp-file-and-rename so readers never see partial content. Gates Store.write_atomic() and Store.open_atomic().
  • ATOMIC_MOVE -- Quality flag: move() is guaranteed atomic under concurrent access (e.g. Local via os.rename, Memory under lock, SQL in a transaction). Does not gate a method — call store.supports(Capability.ATOMIC_MOVE) before relying on atomic rename semantics. Backends that implement move as copy-then-delete (e.g. S3, Azure non-HNS) do not declare this capability.

Metadata

  • METADATA -- Retrieve file or folder metadata. Gates Store.get_file_info() and Store.get_folder_info().
  • USER_METADATA -- Store user-supplied key/value pairs alongside a file. Strict gate on the metadata= kwarg in Store.write(), Store.write_text(), and Store.write_atomic(): passing a non-empty mapping to a backend that does not declare this capability raises CapabilityNotSupported before any I/O. metadata=None and metadata={} are always allowed.

Quality flags

  • SEEKABLE_READ -- Store.read() always returns a seekable stream (stream.seekable() is True). Backends that declare this capability return seekable streams from both read() and read_seekable() with zero overhead. Backends without this capability still support read_seekable() via an optimized override or spool fallback.
  • LAZY_READ -- read() fetches data lazily on demand from the native source rather than loading the entire file into memory before returning. Backends that pre-load the full file contents (e.g. in-memory backends, SQL blob stores) do not declare this flag. Callers can use store.supports(Capability.LAZY_READ) to know whether partial reads avoid loading the entire file.
  • WRITE_RESULT_NATIVE -- Quality flag: the backend populates the rich fields of the returned WriteResult (etag, last_modified, version_id, and where applicable digest) directly from its write response. Does not gate any method — Store.write*() works on every backend. Backends without this flag return a WriteResult with only path and size populated (source == "basic"); metadata is governed independently by the USER_METADATA capability and is not subject to this flag. Use store.supports(Capability.WRITE_RESULT_NATIVE) to decide whether to call store.get_file_info() after a write if you need the full metadata set.

Quality flags vs. method gates

Two kinds of capabilities exist. Method gates (e.g. READ, WRITE, DELETE) guard specific Store or Backend methods — calling a gated method on a backend that does not declare the capability raises CapabilityNotSupported. Quality flags (e.g. SEEKABLE_READ, WRITE_RESULT_NATIVE) are informational only — they describe behaviour the backend provides but do not guard any method call. Check the class docstring for the full categorisation.

CapabilitySet 

CapabilitySet(capabilities: set[Capability])

Immutable set of capabilities declared by a backend.

Parameters:

  • capabilities (set[Capability]) –

    The set of supported capabilities.

supports 

supports(cap: Capability) -> bool

Check whether a capability is supported.

require 

require(cap: Capability, *, backend: str = '') -> None

Raise if a capability is not supported.

Raises:

See also