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).