selkie.store
— Object store
JSONDisk - unit is the file. Directories are created incidentally.
An Object is either a Dict or a List. It represents the contents of a JSONDisk at a finer grain. An Object may be attached to a file, or an element inside of a file, or a directory. It may also be unattached.
An Object has a _contents
member that contains the current
contents of what is on disk. If _contents
is None, the Object is
unattached.
which
An Object
is a dict-like JSON object that is backed
by a JSONDisk, and a Store
maps pathnames to Objects.
To clarify, let us define some terms:
- Dict-like object
An object that has an
items()
method.- List-like object
An object that has an
__iter__()
method, but is not dict-like.- JSON object
None, a boolean, int, float, or string, or a dict-like or list-like object consisting of JSON objects.
- Backing
A directory, file, or part of a file that provides the persistent content of an Object.
- Key
A member of an Object that contributes an item to
items()
.- Basic key
A key that has a direct backing. The value of the key is set when the Object is instantiated, and setting the value causes the backing to be rewritten.
- Defined key
A key that is not basic. Its value is computed from the values of basic keys, and setting its value sets the values of basic keys.
An Object is instantiated from a directory, file, or part of a file, known as its backing. Object classes are never instantiated by the user, but are always obtained by reading from a store.
Instantiating the object from its backing sets certain keys, which are distinguished as basic keys. Setting the value of a basic key causes
Defined keys are also permitted. Their values are determined by the values of basic keys, and setting them
provides construction from JSON and rendering to
JSON. It is intended for use with a Store
, which is a
specialization of JSONDisk (see selkie.disk
) that provides a
store of persistent objects.
Distinguish directory objects or file objects from meta-objects. The backing of a meta-object is just a part of a file; typically a listing. A file object is immediately loaded in entirety, but the members of a directory object are only loaded on demand. The members of a directory object are files or subdirectories.
We distinguish between instantiation and loading. Loading involves reading something from disk. We rely on schemas to know what the contents of a directory are (or rather, should be). Directory listings are never taken. Loading consists exclusively of the loading of individual files.
A directory object is backed by a directory. Directories are never loaded. The first time a key is accessed, the value of that key (and only that key) is instantiated. The key’s value (which must be a directory object or file object) is only instantiated, not loaded.
A file object is backed by a file. Nothing is loaded when the file object is instantiated. The file is loaded the first time any key is accessed.
A partial-file object is an object that cannot be independently read or written. Its contents exist in entirety when it is instantiated. It has a pointer to the file object that contains it. If the partial-file object is modified, it instructs the containing file to save itself.
Objects wrap plain lists and dicts produced by read_kvi()
.
A subclass defines __schema__
, which determines the basic keys.
A defined key is added for each method whose name begins get_
.
Object provides __getattr__()
, etc., __getitem__()
etc., and GET()
etc.
As a JSON object, an Object is equal to its contents (which is what the JSONDisk reads in).