llama.event package

A class for interacting with the files associated with a given event. This class contains methods for working with these files individually (with FileHandlers) or as a group. In particular, the update method can be used to abstractly update the files in an event directory with the latest available information. This approach is robust and allows for trivial modifications and additions to the types of data files associated with events.

class llama.event.Event

Bases: llama.event.EventTuple, llama.flags.FlagsMixin, llama.versioning.GitDirMixin

An event object, used to update and access data associated with a specific trigger (which recieves its own directory or eventdir). FileHandler or another Event (or anything with ‘eventid’ and ‘rundir’ properties) as an input argument, in which case it will correspond to the same event as the object provided as an argument. One can also provide a module or dictionary containing FileHandlers, which will be used to create a FileGraph for the Event (i.e. it will specify which files should be made for this event). Defaults to the files module for now, though eventually this should be refactored out.

Parameters

  • eventid_or_event (str or EventTuple or llama.filehandler.FileHandlerTuple) – This can be a string with the unique ID of this event (which can simply be a filename-friendly descriptive string for tests or manual analyses), in which case the next arguments, rundir and pipeline, will be used; OR, alternatively, it can be an EventTuple (e.g. another Event instance), FileHandlerTuple (e.g. any FileHandler instance), or any object with valid eventid and rundir attributes. In this case, those attributes from the provided object will be re-used, and the rundir argument will be ignored. This makes it easy to get a new Event instance describing the same underlying event but with a different Pipeline specified, or alternatively to get the Event corresponding to a given FileHandler (though in this case you should take care to manually specify the ``Pipeline`` you want to use!).

  • rundir (str, optional) – The rundir, i.e. the directory where all events for a given run are stored, if it differs from the default and is not specified by eventid_or_event.

  • pipeline (llama.pipeline.Pipeline, optional) – The pipeline, i.e. the set of FileHandlers that we want to generate, if it differs from the default pipeline. If none is provided, use DEFAULT_PIPELINE.

Returns

event – A new Event instance with the given properties.

Return type

Event

Raises

ValueError – If the eventid_or_event argument does not conform to the above expectations or if the rundir directory for the run does not exist, a ValueError with a descriptive message will be thrown.

property auxiliary_paths

Names of possible auxiliary paths in the directory that are used to track the state of the Event as a whole.

change_time()

The time at which the permissions of this event directory were last changed (according to the underlying storage system). Note that you probably are more interested in modification_time.

clone(commit='HEAD', rundir=None, clobber=False)

Make a clone of this event in a temporary directory for quick manipulations on a specific version of a file.

Parameters

  • commit (str, optional) – The commit hash to check out when cloning this event. If not specified, the most recent commit will be used. Unsaved changes will be discarded.

  • rundir (str, optional) – The run directory in which to store the cloned event. If not specified, a temporary directory will be created and used. The contents of this directory will NOT be deleted automatically.

  • clobber (bool, optional) – Whether this cloned event should overwrite existing state.

Returns

  • clone_event (llama.event.Event) – A clone of this event. The full history is saved, but the specified commit is checked out. Any uncommitted changes in the working directory will not be copied over to the clone_event. If clone_event already seems to be a valid event with the correct commit hash, no further action will be taken (thus repeated cloning has little performance penalty).

  • Raises

  • llama.versioning.GitRepoUninitialized – If this is called on an Event that has not had its git history initialized.

  • IOError – If this event already exists in the specified rundir and is checked out to a different hash, unless clobber is True, in which case that working directory will be deleted and replaced with the desired commit.

compare_contents(other)

Compare the file contents of this event to another event using filecmp.cmpfiles (though results are given as FileHandler instances rather than file paths). Use this to see whether two event directories contain the same contents under a given pipeline.

Parameters

other (Event, str) – The other Event instance to compare this one to, or else a directory containing files that can be compared to this Event (though in that case the filenames must still follow the expected format).

Returns

  • match (FileGraph) – A FileGraph for this Event whose files have the same contents as those corresponding to the other event.

  • mismatch (FileGraph) – A FileGraph for this Event whose files have differing contents as those corresponding to the other event.

  • errors (FileGraph) – A FileGraph for this Event whose corresponding files do not exist or otherwise could not be accessed for comparison (either for the files corresponding to this Event or the other one).

Raises

ValueError – If the Pipeline instances of this Event and the other one are not equal, it does not make sense to compare them, and a ValueError will be raised.

property cruft_files

Return a list of files in the event directory that are not associated with any file handler nor with event state directories.

property eventdir

The full path to the directory containing files related to this event.

exists()

Check whether this event already exists.

property files

Get a FileGraph full of FileHandler instances for the files in this event with this particular pipeline.

classmethod fromdir(eventdir='.', **kwargs)

Initialize an event just by providing a filepath to its event directory. If no directory is specified, default to the current directory and try to treat that like an event. Note that the returned event will eliminate symbolic links when determining paths for rundir and eventid. Useful for quickly making events during interactive work.

Parameters

  • eventdir (str, optional) – The event directory from which to initialize a new event.

  • **kwargs – Remaining keyword arguments to pass to Event().

gpstime()

Return the GPS time of this event. Returns -1 if none can be parsed.

init()

Initialize the directory for this event, making sure it is in a proper state for processing data. Make sure the eventdir exists by creating it if necessary. Also initializes version control and set flags to the defaults specified in FlagsMixin.DEFAULT_FLAGS (which Event inherits).

Returns

Returns this Event instance to allow command chaining.

Return type

self

Raises

ValueError – If the eventdir path exists but is not a directory or a link to a directory, we don’t want to overwrite it to make an the directory.

modification_time()

The time at which this event directory was modified (according to the underlying storage system).

printstatus(cruft=False, highlight=None, unicode=True, plot=None)

Get a user-readable message indicating the current status of this event. Include a list of files not in the selected pipeline with cruft=True. Bold lines in the summary table containing strings in highlight as substrings. Use nice unicode characters and terminal colors with unicode=True, or use plain ascii with unicode=False. Include a status graph plot with plot=True, or exclude it with plot=False; if plot=None, include the plot only if the underlying Graph::Easy Perl library is available on the host.

save_tarball(outfile)

Save this event and all its contents as a gzipped tarball. You should probably use a .tar.gz extension for the outfile name.

update(**downselect)

Generate any files that fit the FileGraph downselection criteria specified in downselect. By default, generate all files that have not been generated and regenerate all files that have been obsoleted because their data dependencies have changed. Returns True if files were updated, False if no files in need of update were found.

v0_time()

Return the timestamp of the first file version commit, catching the error if the event does not have versioning initialized/has no versions and returning False.

class llama.event.EventTuple(eventid, rundir, pipeline)

Bases: tuple

property eventid

Alias for field number 0

property pipeline

Alias for field number 2

property rundir

Alias for field number 1

llama.event.NOW()

Returns new datetime object representing current time local to tz.

tz

Timezone object.

If no tz is specified, uses local timezone.