Glossary

Auditor

An instance of the seagrass.Auditor class. The auditor is the main external interface for using Seagrass; you use it to select which parts of code you wish to audit.

Auditing context

A block of code in which the local auditor is enabled. Typically you create a new auditing context using seagrass.Auditor.audit():

auditor = seagrass.Auditor()

with auditor.start_auditing():
    # Events that occur here will be audited
    ...

# Events outside of the auditing context are not audited

You can also create an auditing context by enabling and disabling the auditor with seagrass.Auditor.toggle_auditing():

auditor.toggle_auditing(True)

# Events that occur here will be audited

auditor.toggle_auditing(False)

# Events here are not audited

Event

Also referred to as an audit event. Events (that is, instances of seagrass.events.Event) are the basic building block for auditing code in Seagrass. You usually create an event with the list of hooks that you want to run on that event using the audit() method of seagrass.Auditor:

# Method 1: use @auditor.audit to decorate a function definition.
# This call will create a new event called "my_foo_event" that gets
# raised whenever we call the function foo
@auditor.audit("my_foo_event", hooks=hooks)
def foo(x, y):
    return x + y

# Method 2: use auditor.audit to wrap an existing function.
# This call will create a new event called "my_bar_event" that gets
# raised whenever we call the function audited_bar
def bar(name):
    return f"Hello, {name}!"

audited_bar = auditor.audit("my_bar_event", bar, hooks=hooks)

There are two main components to any event:

• The name of the event, represented by a string. Event names must be unique for each seagrass.Auditor. If you try to define two events with the same name, you’ll get an error:

  >>> @auditor.audit("my_event", hooks=hooks)
  ... def add(x, y):
  ...     return x + y
  
  >>> @auditor.audit("my_event", hooks=hooks)
  ... def sub(x, y):
  ...     return x - y   
  Traceback (most recent call last):
  ValueError: An event with the name 'my_event' has already been defined
  

• A function. The event is really just a wrapper around this function; instead of calling the function directly, we call the wrapper. If we’re in an auditing context and the event is enabled (events can be toggled with seagrass.Auditor.toggle_event()), then we will call the event’s prehooks, call the function itself, and then call the event’s posthooks.

Hook

A hook is an instance of a class that can be used to “hook” an event. It primarily consists of a prehook and a posthook method, which are called at the start and end of the event. Any class can be a hook so long as it satisfies the seagrass.base.ProtoHook protocol.

Runtime audit event/hook

The terms runtime audit event and runtime audit hook signify an audit event/hook for the Python runtime as defined by PEP 578. Runtime audit events are created by calling sys.audit, while runtime audit hooks are added with sys.addaudithook.

These terms are used to differentiate between Seagrass audit events/hooks. A Seagrass audit event is an instance of seagrass.events.Event, while a Seagrass audit hook is an instance of a class implementing the seagrass.base.ProtoHook protocol. Seagrass events and hooks are only a part of the Seagrass library and not a part of the Python runtime.

While runtime audit events/hooks are similar to Seagrass events/hooks, they share some important differences; see Why use Seagrass instead of Python runtime audit hooks? for more information.