07 / API REFERENCE

A small surface.
Useful names.

Install the published package, then use the same reader model from the CLI or Python. No database, cloud account, Node.js, Rust or Worker is required.

INSTALL

Python in, RIDA out.

Python 3.10 or newer is required. Encryption support is installed automatically with the package.

pip install rida-format
rida --version

Name	Purpose
`rida.build`	Build a dataset from JSON input.
`rida.scan`	Measure fields and recommend dense or sparse.
`rida.open_reader`	Open a local path or HTTP(S) URL.
`rida.RidaFile`	Local reader: get, get_many, get_record, folders, resolve.
`rida.RemoteRidaFile`	HTTP range reader with timeout, cache and keepalive.
`rida.verify`	Stream the data region and return an integrity report.
`rida.inspect_metadata`	Return index contents as a dictionary.
`rida.MERGE_GAP_LIMIT`	660 bytes: the measured merge threshold.
`rida.VALUE_CODECS`	deflate-per-field and plain.

ONE COMPLETE FLOW

Scan, build, read, verify.

import rida

report = rida.scan("users.json")
print(report.recommended_mode)
rida.build("users.json", "UsersData.rida")

with rida.RidaFile("UsersData.rida") as data:
    print(data.get("ali", "city"))

print(rida.verify("UsersData.rida")["ok"])

Reader options and utility functions

RidaFile accepts index= for a local index. RemoteRidaFile also accepts timeout=, cache_dir=, use_cache=, keepalive= and key=. Both readers provide field and record lookups; use a local reader for a full-file verification.

Name	Purpose
`records_under(prefix)`	List record IDs beneath a numbered folder.
`resolve(...names)`	Resolve folder names to their numbered prefix.
`folders()`	Return the numbered prefixes and their names.
`rida.clear_remote_cache`	Remove cached indexes, optionally for one URL; return the count removed.
`rida.remote_cache_directory`	Return the configured cache folder.
`rida.read_map_folders`	Read numbered folder names without opening the data reader.
`rida.encryption_available`	Check whether optional encryption support is available.
`rida.ID_SEPARATOR`	The separator between numbered levels: /.

rida.open_reader selects a reader for a local path or an HTTP(S) URL. Pass the corresponding reader’s options. value_codec= selects the codec for rida.scan and rida.build.

Show build progress inside your application

A desktop application can show RIDA’s stages in its own interface through a progress callback. The terminal display is not the only way to observe a build.

def progress(stage, completed, total):
    print(f"{stage}: {completed}/{total}")

rida.build("items.json", "ItemsData.rida", progress=progress)

What the current release supports

The library builds static datasets, finds values by record ID and field name, reads several fields, resolves folder names through a map, checks local data integrity and optionally encrypts stored values.

Exact-match search indexes, numeric range search and Unicode full-text search indexes are not included. There is no JavaScript reader in this release. HTTP byte ranges describe how bytes are fetched; they do not provide a search engine.

Work with the source project

From an extracted source project, install locally with python3 -m pip install .. The package and command are both named rida; the distribution name is rida-format. Run the installed package or import it rather than executing an internal source file.

rida/
  pyproject.toml            package metadata
  MANIFEST.in              source archive contents
  RIDA-README.md           usage manual
  RIDA-FORMAT.md           binary format specification
  CHANGELOG.md            release history
  LICENSE                 license terms
  docs/rida-metadata.html  optional metadata helper
  src/rida/               library and command-line code
  tests/                  suite and compatibility fixtures

python3 -m pip install .
python3 -m unittest discover -s tests -v

The core test suite uses a local range server rather than an external network service. Fixtures preserve known data and catalog bytes; tests/make_fixtures.py regenerates them when the format changes. The cryptography dependency is installed automatically with RIDA. Official macOS and Windows Python installers include LZMA support; minimal Linux installations may need their Python LZMA component installed separately.

Use RIDA in your application

The RIDA Proprietary License permits using and modifying RIDA as a component of free or paid applications. It does not permit publishing, redistributing or selling it as a standalone library or software product. The license does not apply to the data files you create.

Applications that include RIDA must display this notice in an About, Licenses or Third-Party Notices section:

Uses RIDA (Range Indexed Data Access).
Copyright (c) 2026 Syed Ali Hamza Chishty.
Used under the RIDA Proprietary License.

Read the LICENSE supplied with the source or installed distribution for the full terms.

A small surface.Useful names.