Job.FileStore API

The FileStore is an abstraction of a Toil run’s shared storage.

class toil.fileStore.FileStore(jobStore, jobGraph, localTempDir, inputBlockFn)[source]

An abstract base class to represent the interface between a worker and the job store. Concrete subclasses will be used to manage temporary files, read and write files from the job store and log messages, passed as argument to the toil.job.Job.run() method.

__init__(jobStore, jobGraph, localTempDir, inputBlockFn)[source]

x.__init__(…) initializes x; see help(type(x)) for signature

open(**kwds)[source]

The context manager used to conduct tasks prior-to, and after a job has been run.

Parameters:job (toil.job.Job) – The job instance of the toil job to run.
getLocalTempDir()[source]

Get a new local temporary directory in which to write files that persist for the duration of the job.

Returns:The absolute path to a new local temporary directory. This directory will exist for the duration of the job only, and is guaranteed to be deleted once the job terminates, removing all files it contains recursively.
Return type:str
getLocalTempFile()[source]

Get a new local temporary file that will persist for the duration of the job.

Returns:The absolute path to a local temporary file. This file will exist for the duration of the job only, and is guaranteed to be deleted once the job terminates.
Return type:str
getLocalTempFileName()[source]

Get a valid name for a new local file. Don’t actually create a file at the path.

Returns:Path to valid file
Return type:str
writeGlobalFile(localFileName, cleanup=False)[source]

Takes a file (as a path) and uploads it to the job store.

Parameters:
  • localFileName (string) – The path to the local file to upload.
  • cleanup (bool) – if True then the copy of the global file will be deleted once the job and all its successors have completed running. If not the global file must be deleted manually.
Returns:

an ID that can be used to retrieve the file.

Return type:

toil.fileStore.FileID

writeGlobalFileStream(cleanup=False)[source]

Similar to writeGlobalFile, but allows the writing of a stream to the job store. The yielded file handle does not need to and should not be closed explicitly.

Parameters:cleanup (bool) – is as in toil.fileStore.FileStore.writeGlobalFile().
Returns:A context manager yielding a tuple of 1) a file handle which can be written to and 2) the ID of the resulting file in the job store.
readGlobalFile(fileStoreID, userPath=None, cache=True, mutable=False, symlink=False)[source]

Makes the file associated with fileStoreID available locally. If mutable is True, then a copy of the file will be created locally so that the original is not modified and does not change the file for other jobs. If mutable is False, then a link can be created to the file, saving disk resources.

If a user path is specified, it is used as the destination. If a user path isn’t specified, the file is stored in the local temp directory with an encoded name.

Parameters:
  • fileStoreID (toil.fileStore.FileID) – job store id for the file
  • userPath (string) – a path to the name of file to which the global file will be copied or hard-linked (see below).
  • cache (bool) – Described in toil.fileStore.CachingFileStore.readGlobalFile()
  • mutable (bool) – Described in toil.fileStore.CachingFileStore.readGlobalFile()
Returns:

An absolute path to a local, temporary copy of the file keyed by fileStoreID.

Return type:

str

readGlobalFileStream(fileStoreID)[source]

Similar to readGlobalFile, but allows a stream to be read from the job store. The yielded file handle does not need to and should not be closed explicitly.

Returns:a context manager yielding a file handle which can be read from.
deleteLocalFile(fileStoreID)[source]

Deletes Local copies of files associated with the provided job store ID.

Parameters:fileStoreID (str) – File Store ID of the file to be deleted.
deleteGlobalFile(fileStoreID)[source]

Deletes local files with the provided job store ID and then permanently deletes them from the job store. To ensure that the job can be restarted if necessary, the delete will not happen until after the job’s run method has completed.

Parameters:fileStoreID – the job store ID of the file to be deleted.
classmethod findAndHandleDeadJobs(nodeInfo, batchSystemShutdown=False)[source]

This function looks at the state of all jobs registered on the node and will handle them (clean up their presence ont he node, and run any registered defer functions)

Parameters:
  • nodeInfo – Information regarding the node required for identifying dead jobs.
  • batchSystemShutdown (bool) – Is the batch system in the process of shutting down?
logToMaster(text, level=20)[source]

Send a logging message to the leader. The message will also be logged by the worker at the same level.

Parameters:
  • text – The string to log.
  • level (int) – The logging level.
classmethod shutdown(dir_)[source]

Shutdown the filestore on this node.

This is intended to be called on batch system shutdown.

Parameters:dir – The jeystone directory containing the required information for fixing the state of failed workers on the node before cleaning up.