PYTHONPATH=$DAQROOT/pythonLibs/nscldaq python3
import LogBook.LogBook as LogBook
try:
...
except LogBook.error:
...
LogBook.create(filename, expid, spokesperson, purpose)
book = LogBook.LogBook(filename)
# People interface
person = book.add_person(lastname, firstname[, salutation])
people = book.find_people([whereclause])
people = book.list_people()
person = book.get_person(id)
# Shift interface
shift = book.get_shift(id)
shift = book.create_shift(name[, people])
shift = book.find_shift(name)
shift = book.current_shift()
# Run interface
run = book.current_run()
runs = book.list_runs()
run = book.find_run(number)
run = book.begin_run(number, title[, comment])
# Note interface:
note = get_note(id)
notes = list_all_notes();
notes = list_all_notes_for_run_number(number)
notes = list_all_notes_for_run_id(id)
notes = list_all_notes_for_run(run)
notes = list_nonrun_notes()
run = get_note_run(note)
note = create_note(author, text [,images=filenames, offsets=offsets][, run])
# Key Value store interface
if (kv_exists(key)):
# It exists
...
value = kv_get(key)
kv_set(key, value)
kv_create(newkey, value)
This is the top level reference page for the python bindings to the
logbook API. In addition to a static method to create new logbooks,
and an exception type (LogBook.error),
the API allows construction of a LogBook.Logbook
object on an existing logbook filename.
Once constructed, that object
provides several API subsections, each of these will be given its
own section.
Each of the API subsections may produce objects of other types that can be manipulated to gain further detailed information about the logbook or provide additional information to the logbook. These will have their own reference pages (they are called out in the text as well as appearing in SEE ALSO)
This section allows you to create and retrieve people from the logbook.
A persin is encapsulated in a LogBook.Person
object. This object is described in the reference page:
LogBook.Person.
Here are the methods that make up the People API section:
LogBook.Person add_person(string lastname, string firstname, (optional) string salutation);
Creates a new logbook person and returns an object that
encapsulates it. The parameters can be ordered or specified
via keywords whose keys are the parameter names above.
The lastname and
firstname parameters are mandatory and
specify the person's last name and first name respectively.
The salutation parameter is optional.
If supplied a non-empty salutation will be provided for the
person (e.g. 'Mr.') If not, on retrieval,
this person will have an empty salutation.
tuple of LogBook.Person find_people(optional string whereclause);
Finds people that match the optional whereclause.
The result is a tuple containing LogBook.Person
objects that encapsulate people that satisfy the
whereclause.
whereclause is optional. If omitted,
this method is functionally equivalent to
list_people below.
If provided, whereclause must be a
valid SQLite3 WHERE clause (without the WHERE)
clause that will be used to filter out the matching people.
For more informationa bout the strings that can be used
for whereclause, refer to the
Sqlite3 reference page for expressions (
https://sqlite.org/syntax/expr.html
). And the logbook schema for the person
table at
Logbook Schema
tuple of LogBook.Person list_people();
Returns a tuple that contains all people in the logbook.
This is functionally equivalent to not supplying a
whereclause to
find_people.
LogBook.Person get_person()(number id);
Returns the person with the primary key id.
This parameter must be treatable as an integer.
The Shift part of the API manipulates collections of people that
can be on-duty while data taking is in progress. Shifts, returned by
this part of the API are encapsulated in LogBook.Shift
objects. These are described in the
LogBook.Shift reference page.
These methods make up the Shift API section:
LogBook.Shift get_shift(number id);
Returns a LogBook.Shift object that
encapsulates the person with the primary key
id. This parameter must be convertible
to an integer.
LogBook.Shift create_shift(string name, (optional) iterable of LogBook.Person people);
Creates a shift and optionally stocks it with people.
The name parameter is mandatory and
is the new name to give to the shift. Shift names must be
unique. The optional people
parameter can be specified either positionally or by keyword
(people). If provided it must be an
iterable Python object whose members are all
LogBook.Person people who will initially
be members of the shift. Note that the
LogBook.Shift object that's returned
also provides methods that allow you to manipulate membership.
A caution here that shift membership should not change once data taking starts. This is because run state translations get associated with a shift. Therefore changing the membership of a shift will change the logbook database's understanding of who was on-duty at the time of the shift change.
LogBook.Shift find_shift(string name);
Returns a LogBook.Shift object that
encapsulates the shift that is named name
LogBook.Shift current_shift();
The logbook has the concept of a current shift. This has meaning during data taking. When run transitions are logged, the current shift is associated with that transition. This logs who was on duty and responsible for that transition. If no current shift has been established; None is returned.
Runs are segments of data taking. They are encapsulated with
LogBook.Run objects. For more on those, see
LogBook.Run.
This part of the API provides the ability to create new runs, by beginning
data taking, and retreive existing runs. One of the most important
bits of metadata associated with a run is its run number. Among recorded
runs, this is a unique integer.
One other key concept in the run API is that, natrually, data taking can only be active in one run at a time. The logbook API enforces this by refusing to allow a run be created while another run is active. The active run, if there is one is called the current run.
Here are the methods that make up the run api:
LogBook.Run current_run();
Returns the current run if there is one or None if no data taking is in progress (according to the logbook).
tuple of LogBook.Run list_runs();
Returs a tuple of LogBook.Run
that contains all of the runs in the logbook. Note that the
current run, if there is one, is included in the tuple.
LogBook.Run find_run(Number number);
Returns the LogBook.Run
that has the run number number.
If there is no match, None is returned.
LogBook.Run begin_run (Number number, String title, optional String comment);
Creates a new run logging a BEGIN
transition for it. The number
and title specify the run number
and title respectively and are mandatory. The
optional parameter comment
provides a comment that's associated with the begin
state transition. All parameters can be either positional
or be keyworded with the name of the parameter as the keyword
(e.g. number=1).
Notes are documentation about the experiment that can be entered at any time. Notes can be associated with runs or free standing. A note has, minimally an author and a time at which it was created. Notes can be rich text using the Markdown formatting language. See https://https://www.markdownguide.org/ for information about Markdown.
Markdown supports the inclusion of images via image links. The logbook database, however is all inclusive. Therefore, the images that are referred to in notes are pulled into the database where they can be recovered when the note is later rendered.
Notes are incapsulated in LogBook.Note objects.
These objects are described in
LogBook.Note.
Here are the methods in the note API
LogBook.Note get_note(Number id);
Returns a LogBook.Note that
encapsulates the note that has the primary key
id
Tuple of LogBook.Note list_all_notes();
Returns a tuple that contains all of the notes known to the logbook.
Tuple of LogBook.Note list_all_notes_for_run_number(Number number);
Returns a tuple of LogBook.Note
objects that represent all of the notes that have been
associated with the run numbered number.
Tuple of LogBook.Note list_all_notes_for_run_id(Number id);
Returns a tuple of LogBook.Note
objects that represent all of the notes that have
been associated with the run whose primary key is
id
Tuple of LogBook.Note list_all_notes_for_run(LogBook.Run run);
Returns a tuple of LogBook.Note
objects that represent all of the notes that have
been associated with the LogBook.Run
object run.
Tuple of LogBook.Note list_nonrun_notes();
Returns a tuple of LogBook.Note
that represent the notes that are not associated with
any run.
LogBook.Run get_note_run(LogBook.Note note);
If the note is associated with a run,
this method returns a LogBook.Run
encapsulating that run. If not, None
is returned.
LogBook.Note create_note(LogBook.Person author, String text, optional Iterable of Strings images, optional Iterable of Numbers offsets, (optional) LogBook.Run run);
Creates a new note in the logbook and returns a
LogBook.Note that encapsulates it.
Two mandatory parameters; author
and text provide the
LogBook.Person that is the note author
and note text respectively. If the markdown in
text contains image references,
the images and offsets
must provide the filenames of those images and byte offsets
into the text at which the link to each
image occurs. If the note is associated with a run,
run is the
LogBook.Run that represents the associated
run.
The parameters can be positional as shown or keywords where the parameter names above are the keywords you can use e.g.
The key value store provides the ability to store keyword value pairs that can be retrieved by keyword. Here are the methods that make up this section of the API.
Boolean kv_exists(String key);
Returns True if there is an entry in
the key value store with the key key.
If not, returns False.
String kv_get(String key);
Returns the value of the key key
from the key value store. If there is no matching
key, raises
LogBook.error
None kv_set(String key, String value);
If key exists, its value is
overridden and set to value. If
key does not exist, it is created with
a value of value.
None kv_create(String newkey, String value);
If newkey does not exist it is created
with value as its value. If it does
exist, LogBook.error is raised.