Python · Platform Notes

Platform Notes

3.0.0-rc.1 · 4c3e5023

§ Tooling

usearch.io reads and writes the fbin / ibin / i8bin matrix formats, and usearch.eval carries the recall harness, which takes the index or any blocking receiver:

from usearch.eval import self_recall

stats = self_recall(index.on(pool), usearch.Arena(pool))
print(stats.mean_recall, stats.mean_efficiency)

§ What This Binding Does Not Expose

  • cursor and search_stream on a DeferredOn: they open walks whose every pull blocks, so there is nothing to submit.
  • usearch_dense_metric_from_name: DenseMetric is an enum.IntEnum, so DenseMetric["ANGULAR"] parses a name and no string ever reaches a verb.

§ Design

  • A thin layer over the C ABI. Every name follows c/usearch/: a C verb usearch_dense_<verb> is a <verb> here, a type drops usearch_ and _t, and enums mirror C enums as enum.IntEnum classes, never strings.
  • The receiver chooses, the verb stays. The index runs a verb on the calling thread, on(executor) blocks on an executor, and deferred(executor) submits it, all with the same arguments.
  • Deferred calls use the language’s own idioms. status polls through usearch_outcome_status, wait blocks through usearch_outcome_wait, and await hands wait() to the running event loop’s default executor.
  • No life of its own. The binding starts no threads and keeps no queues; releasing a Deferred rides reference counting, which waits for the call first.
  • Arenas are lent and reused, never shared. Every output whose length scales with the call lands in an arena the caller passes; an exported buffer pins its arena until released, and a view over a rewound one raises UninitializedError.
  • Nothing costs anything until it is used. Submitting a call allocates nothing, and an arena allocates only when a call writes into it.
  • Blocking calls stay as simple as the language allows. index.search(queries, 10, arena) takes no executor, completion or receiver argument and returns its result; nothing about asynchrony reaches a caller who never asks for it.
  • Language idioms over parallel APIs. The buffer protocol, in, struct sequences, context managers and += take the place of helper methods, and describe, health and metadata_read answer the C structs as struct sequences, never as dicts.