inspect-textdb

Inspecting a dbetto text database

dbetto treats a directory of JSON/YAML files as a database. Directories, files, and the keys inside a file all sit at the same semantic level, so you can walk from the top folder down to a leaf value with one uniform syntax. In memory every mapping becomes an AttrsDict (a dict you can also access with dot notation). This skill is the map of what the API can do and which entry point fits each question, including how to check that a change to the data behaves.

Orient first

Before writing code, look at the data. The right API call depends on the shape on disk, so check it:

• find <dir> -maxdepth 2 -name '*.json' -o -name '*.yaml' -o -name '*.yml' to see the file layout.
• Look for a validity.yaml / validity.json / validity.jsonl in a directory: its presence means the data is time-versioned and you should query it with .on(timestamp) rather than reading a fixed file.
• Peek at one file to learn whether the top level is a mapping ({...}) or a list ([...]), and whether entries carry an inner id worth remapping on (e.g. daq.rawid, name).

Everything is importable from the top package:

from dbetto import TextDB, AttrsDict, Props, load_dict, load_attrs_dict, str_to_datetime

Load a database

from dbetto import TextDB

db = TextDB("/path/to/data")  # scans the tree immediately

• lazy=True skips the initial filesystem scan and caches files as you touch them. Cheap for huge trees, but .map(), .group(), iteration, and .keys() need a populated store, so call db.scan() first if you use them. lazy="auto" is lazy except in an interactive session.
• hidden=True includes dot-files/dot-dirs (ignored by default).
• To read a single file without a whole database: load_dict(path) returns a plain dict/list; load_attrs_dict(path) returns an AttrsDict. Both infer JSON vs YAML from the extension.

Access files and values

Directories resolve to nested TextDB objects; files resolve to AttrsDict (or a list). The extension is optional and path-style keys work: