CAT-SOOP API: catsoop.cslog

Logging mechanisms in catsoopdb

From a high-level perspective, CAT-SOOP's logs are sequences of Python objects.

A log is identified by a db_name (typically a username), a path (a list of strings starting with a course name), and a logname (a string).

On disk, each log is a file containing one or more entries, where each entry consists of:

  • 8 bytes representing the length of the entry
  • a binary blob (pickled Python object, potentially encrypted and/or compressed)
  • the 8-byte length repeated

This module provides functions for interacting with and modifying those logs. In particular, it provides ways to retrieve the Python objects in a log, or to add new Python objects to a log.

View Source

Members

  • catsoop.cslog.clear_old_logs (function, lines 374-389)

    Clear logs older than the given value. Primarily used for session handling

 

  • catsoop.cslog.delete_log (function, lines 251-273)

    Deletes an entire log.

    Parameters:

    • db_name: the name of the database to overwrite
    • path: the path to the page associated with the log
    • logname: the name of the log

    Optional Parameters:

    • lock (default True): whether the database should be locked during this update

 

  • catsoop.cslog.get_log_filename (function, lines 166-191)

    Helper function, returns the filename where a given log is stored on disk.

    Parameters:

    • db_name: the name of the database to look in
    • path: the path to the page associated with the log
    • logname: the name of the log

 

  • catsoop.cslog.most_recent (function, lines 315-350)

    Ignoring most of the log, grab the last entry.

    This code works by reading backward through the log until the separator is found, treating the piece of the file after the last separator as a log entry, and using unprep to return the associated Python object.

    Parameters:

    • db_name: the name of the database to read
    • path: the path to the page associated with the log
    • logname: the name of the log

    Optional Parameters:

    • default (default None): the value to be returned if the log contains no entries or does not exist
    • lock (default True): whether the database should be locked during this read

    Returns: a single Python object representing the most recent entry in the log.

 

  • catsoop.cslog.overwrite_log (function, lines 228-248)

    Overwrites the entire log with a new log with a single (given) entry.

    Parameters:

    • db_name: the name of the database to overwrite
    • path: the path to the page associated with the log
    • logname: the name of the log
    • new: the Python object that should be contained in the new log

    Optional Parameters:

    • lock (default True): whether the database should be locked during this update

 

  • catsoop.cslog.read_log (function, lines 295-312)

    Reads all entries of a log.

    Parameters:

    • db_name: the name of the database to read
    • path: the path to the page associated with the log
    • logname: the name of the log

    Optional Parameters:

    • lock (default True): whether the database should be locked during this read

    Returns: a list containing the Python objects in the log

 

 

 

  • catsoop.cslog.update_log (function, lines 204-225)

    Adds a new entry to the end of the specified log.

    Parameters:

    • db_name: the name of the database to update
    • path: the path to the page associated with the log
    • logname: the name of the log
    • new: the Python object that should be added to the end of the log

    Optional Parameters:

    • lock (default True): whether the database should be locked during this update