History Backend JSON – xonsh.history.json

Implements JSON version of xonsh history backend.

class xonsh.history.json.JsonCommandField(field, hist, default=None)[source]

A field in the ‘cmds’ portion of history.

Represents a field in the ‘cmds’ portion of history.

Will query the buffer for the relevant data, if possible. Otherwise it will lazily acquire data from the file.


field : str

The name of the field to query.

hist : History object

The history object to query.

default : optional

The default value to return if key is not present.


Tests if the command field is at the front of the queue.

class xonsh.history.json.JsonHistory(filename=None, sessionid=None, buffersize=100, gc=True, **meta)[source]

Xonsh history backend implemented with JSON files.

JsonHistory implements two extra actions: diff, and replay.

Represents a xonsh session’s history as an in-memory buffer that is periodically flushed to disk.


filename : str, optional

Location of history file, defaults to $XONSH_DATA_DIR/xonsh-{sessionid}.json.

sessionid : int, uuid, str, optional

Current session identifier, will generate a new sessionid if not set.

buffersize : int, optional

Maximum buffersize in memory.

meta : optional

Top-level metadata to store along with the history. The kwargs ‘cmds’ and ‘sessionid’ are not allowed and will be overwritten.

gc : bool, optional

Run garbage collector flag.


Returns all history as found in XONSH_DATA_DIR.

yield format: {‘inp’: cmd, ‘rtn’: 0, ...}


Appends command to history. Will periodically flush the history to file.


cmd : dict

This dict contains information about the command that is to be added to the history list. It should contain the keys inp, rtn and ts. These key names mirror the same names defined as instance variables in the HistoryEntry class.


hf : JsonHistoryFlusher or None

The thread that was spawned to flush history


Flushes the current command buffer to disk.


at_exit : bool, optional

Whether the JsonHistoryFlusher should act as a thread in the background, or execute immediately and block.


hf : JsonHistoryFlusher or None

The thread that was spawned to flush history


Display history items of current session.

class xonsh.history.json.JsonHistoryFlusher(filename, buffer, queue, cond, at_exit=False, *args, **kwargs)[source]

Flush shell history to disk periodically.

Thread for flushing history.


Write the cached history to external storage.


Tests if the flusher is at the front of the queue.

class xonsh.history.json.JsonHistoryGC(wait_for_shell=True, size=None, *args, **kwargs)[source]

Shell history garbage collection.

Thread responsible for garbage collecting old history.

May wait for shell (and for xonshrc to have been loaded) to start work.


Find and return the history files. Optionally locked files may be excluded.

This is sorted by the last closed time. Returns a list of (timestamp, number of cmds, file name) tuples.