IndexIOMixin

class scikitplot.annoy.IndexIOMixin

Mixin adding explicit Annoy-native persistence helpers.

The concrete class must provide low-level Annoy methods, typically from the C-extension backend:

• save(path, prefault=...)

• load(path, prefault=...)

• serialize() -> bytes-like

• deserialize(data: bytes-like, prefault=...)

Notes

• Methods in this mixin acquire a per-instance lock if one is available.

• save_index defaults to Annoy.save

• save_bundle / load_bundle require to_json / from_json (compose with MetaMixin).

classmethod from_bytes(data, *, f=None, metric=None, prefault=None)

Construct a new index and load it from serialized bytes.

Parameters:

data

Bytes produced by to_bytes (backend serialize).

f

Vector dimension for construction.

metric

Metric name for construction.

prefault

Forwarded to the backend deserialize if supported.

Returns:

index

Newly constructed index with the data loaded.

Raises:

TypeError

If data is not bytes-like.

ValueError

If f or metric is invalid.

AttributeError

If the backend does not provide deserialize.

Parameters:

• data (bytes | bytearray | memoryview)

• f (int | None)

• metric (str | None)

• prefault (bool | None)

Return type:

Self

Notes

Portable blobs add a small header (version, ABI sizes, endianness, metric, f) to ensure incompatible binaries fail loudly and safely. They are not a cross-architecture wire format; the payload remains Annoy’s native snapshot.

For data if fed to_bytes(format='native') required params ``f`, metric.

classmethod load_bundle(manifest_filename='manifest.json', index_filename='index.ann', *, prefault=None)

Load a directory bundle created by save_bundle.

Parameters:

manifest_filename

Filename for the metadata manifest inside the directory.

index_filename

Filename for the Annoy index inside the directory.

prefault

Forwarded to load_index.

Returns:

index

Newly constructed index.

Raises:

AttributeError

If from_json is not available (compose with MetaMixin).

TypeError

If from_json returns an unexpected type.

OSError

On filesystem failures.

Parameters:

• manifest_filename (str)

• index_filename (str)

• prefault (bool | None)

Return type:

Self

classmethod load_index(f, metric, path, *, prefault=None)

Load (mmap) an Annoy index file into this object.

Parameters:

f

Vector dimension for construction.

metric

Metric name for construction.

pathstr or os.PathLike

Path to a file previously created by save_index or the backend save.

prefault

Forwarded to the backend. If None, the backend default is used.

Raises:

AttributeError

If the backend does not provide load(path, prefault=...).

OSError

If loading fails (backend or filesystem).

Parameters:

• f (int)

• metric (str)

• path (str | PathLike[str])

• prefault (bool | None)

Return type:

Self

save_bundle(manifest_filename='manifest.json', index_filename='index.ann', *, prefault=None)

Save a directory bundle containing metadata + the index file.

The bundle contains: - manifest.json: metadata payload produced by to_json - index.ann: Annoy index produced by save_index

Parameters:

manifest_filename

Filename for the metadata manifest inside the directory.

index_filename

Filename for the Annoy index inside the directory.

prefault

Forwarded to save_index.

Raises:

AttributeError

If to_json is not available (compose with MetaMixin).

OSError

On filesystem failures.

Parameters:

• manifest_filename (str)

• index_filename (str)

• prefault (bool | None)

Return type:

list[str]

save_index(path, *, prefault=None)

Persist the Annoy index to disk.

Parameters:

pathstr or os.PathLike

Destination path for the Annoy index file.

prefault

Forwarded to the backend. If None, the backend default is used.

Raises:

AttributeError

If the backend does not provide save(path, prefault=...).

OSError

For filesystem-level failures.

Parameters:

• path (str | PathLike[str])

• prefault (bool | None)

Return type:

Self

to_bytes(format=None)

Serialize the built index to bytes (backend serialize).

Parameters:

format{“native”, “portable”, “canonical”} or None, optional, default=None

Serialization format. If None used "canonical"

• “native” (legacy): raw Annoy memory snapshot. Fastest, but only compatible when the ABI matches exactly.

• “portable”: prepend a small compatibility header (version, endianness, sizeof checks, metric, f) so deserialization fails loudly on mismatches.

• “canonical”: rebuildable wire format storing item vectors + build parameters. Portable across ABIs (within IEEE-754 float32) and restores by rebuilding trees deterministically.

Returns:

data

Serialized index bytes.

Raises:

AttributeError

If the backend does not provide serialize.

RuntimeError

If serialization fails.

TypeError

If the backend returns non-bytes-like data.

Return type:

bytes

Notes

“Portable” blobs are the native snapshot with additional compatibility guards. They are not a cross-architecture wire format.

“Canonical” blobs trade load time for portability: deserialization rebuilds the index with n_jobs=1 for deterministic reconstruction.