toil.jobStores.aws.jobStore¶
Module Contents¶
Classes¶
A job store that uses Amazon's S3 for file storage and SimpleDB for storing job info and |
Attributes¶
- toil.jobStores.aws.jobStore.boto3_session¶
- toil.jobStores.aws.jobStore.s3_boto3_resource¶
- toil.jobStores.aws.jobStore.s3_boto3_client¶
- toil.jobStores.aws.jobStore.logger¶
- toil.jobStores.aws.jobStore.CONSISTENCY_TICKS = 5¶
- toil.jobStores.aws.jobStore.CONSISTENCY_TIME = 1¶
- exception toil.jobStores.aws.jobStore.ChecksumError¶
Bases:
Exception
Raised when a download from AWS does not contain the correct data.
- class toil.jobStores.aws.jobStore.AWSJobStore(locator, partSize=50 << 20)¶
Bases:
toil.jobStores.abstractJobStore.AbstractJobStore
A job store that uses Amazon’s S3 for file storage and SimpleDB for storing job info and enforcing strong consistency on the S3 file storage. There will be SDB domains for jobs and files and a versioned S3 bucket for file contents. Job objects are pickled, compressed, partitioned into chunks of 1024 bytes and each chunk is stored as a an attribute of the SDB item representing the job. UUIDs are used to identify jobs and files.
- class FileInfo(fileID, ownerID, encrypted, version=None, content=None, numContentChunks=0, checksum=None)¶
Bases:
toil.jobStores.aws.utils.SDBHelper
Represents a file in this job store.
- property fileID¶
- property ownerID¶
- property version¶
- property previousVersion¶
- property content¶
- property checksum¶
- outer¶
- Type
- classmethod create(ownerID)¶
- classmethod presenceIndicator()¶
The key that is guaranteed to be present in the return value of binaryToAttributes(). Assuming that binaryToAttributes() is used with SDB’s PutAttributes, the return value of this method could be used to detect the presence/absence of an item in SDB.
- classmethod exists(jobStoreFileID)¶
- classmethod load(jobStoreFileID)¶
- classmethod loadOrCreate(jobStoreFileID, ownerID, encrypted)¶
- classmethod loadOrFail(jobStoreFileID, customName=None)¶
- Return type
- Returns
an instance of this class representing the file with the given ID
- Raises
NoSuchFileException – if given file does not exist
- classmethod fromItem(item)¶
Convert an SDB item to an instance of this class.
- toItem()¶
Convert this instance to an attribute dictionary suitable for SDB put_attributes().
- static maxInlinedSize()¶
- save()¶
- upload(localFilePath, calculateChecksum=True)¶
- uploadStream(multipart=True, allowInlining=True, encoding=None, errors=None)¶
Context manager that gives out a binary or text mode upload stream to upload data.
- copyFrom(srcObj)¶
Copies contents of source key into this file.
- Parameters
srcObj (S3.Object) – The key (object) that will be copied from
- copyTo(dstObj)¶
Copies contents of this file to the given key.
- Parameters
dstObj (S3.Object) – The key (object) to copy this file’s content to
- download(localFilePath, verifyChecksum=True)¶
- downloadStream(verifyChecksum=True, encoding=None, errors=None)¶
Context manager that gives out a download stream to download data.
- delete()¶
- getSize()¶
Return the size of the referenced item in bytes.
- __repr__()¶
Return repr(self).
- property sseKeyPath¶
- bucketNameRe¶
- minBucketNameLen = 3¶
- maxBucketNameLen = 63¶
- maxNameLen = 10¶
- nameSeparator = '--'¶
- jobsPerBatchInsert = 25¶
- itemsPerBatchDelete = 25¶
- statsFileOwnerID¶
- readStatsFileOwnerID¶
- versionings¶
- initialize(config)¶
Initialize this job store.
Create the physical storage for this job store, allocate a workflow ID and persist the given Toil configuration to the store.
- Parameters
config – the Toil configuration to initialize this job store with. The given configuration will be updated with the newly allocated workflow ID.
- Raises
JobStoreExistsException – if the physical storage for this job store already exists
- resume()¶
Connect this instance to the physical storage it represents and load the Toil configuration into the
AbstractJobStore.configattribute.- Raises
NoSuchJobStoreException – if the physical storage for this job store doesn’t exist
- batch()¶
If supported by the batch system, calls to create() with this context manager active will be performed in a batch after the context manager is released.
- assign_job_id(job_description)¶
Get a new jobStoreID to be used by the described job, and assigns it to the JobDescription.
Files associated with the assigned ID will be accepted even if the JobDescription has never been created or updated.
- Parameters
job_description (toil.job.JobDescription) – The JobDescription to give an ID to
- create_job(job_description)¶
Writes the given JobDescription to the job store. The job must have an ID assigned already.
Must call jobDescription.pre_update_hook()
- Returns
The JobDescription passed.
- Return type
- job_exists(job_id)¶
Indicates whether a description of the job with the specified jobStoreID exists in the job store
- Return type
- jobs()¶
Best effort attempt to return iterator on JobDescriptions for all jobs in the store. The iterator may not return all jobs and may also contain orphaned jobs that have already finished successfully and should not be rerun. To guarantee you get any and all jobs that can be run instead construct a more expensive ToilState object
- Returns
Returns iterator on jobs in the store. The iterator may or may not contain all jobs and may contain invalid jobs
- Return type
Iterator[toil.job.jobDescription]
- load_job(job_id)¶
Loads the description of the job referenced by the given ID, assigns it the job store’s config, and returns it.
May declare the job to have failed (see
toil.job.JobDescription.setupJobAfterFailure()) if there is evidence of a failed update attempt.- Parameters
job_id – the ID of the job to load
- Raises
NoSuchJobException – if there is no job with the given ID
- update_job(job_description)¶
Persists changes to the state of the given JobDescription in this store atomically.
Must call jobDescription.pre_update_hook()
- Parameters
job (toil.job.JobDescription) – the job to write to this job store
- delete_job(job_id)¶
Removes the JobDescription from the store atomically. You may not then subsequently call load(), write(), update(), etc. with the same jobStoreID or any JobDescription bearing it.
This operation is idempotent, i.e. deleting a job twice or deleting a non-existent job will succeed silently.
- Parameters
job_id (str) – the ID of the job to delete from this job store
- get_empty_file_store_id(jobStoreID=None, cleanup=False, basename=None)¶
Creates an empty file in the job store and returns its ID. Call to fileExists(getEmptyFileStoreID(jobStoreID)) will return True.
- Parameters
job_id (str) – the id of a job, or None. If specified, the may be associated with that job in a job-store-specific way. This may influence the returned ID.
cleanup (bool) – Whether to attempt to delete the file when the job whose jobStoreID was given as jobStoreID is deleted with jobStore.delete(job). If jobStoreID was not given, does nothing.
basename (str) – If supported by the implementation, use the given file basename so that when searching the job store with a query matching that basename, the file will be detected.
- Returns
a jobStoreFileID that references the newly created file and can be used to reference the file in the future.
- Return type
- classmethod get_size(url)¶
Get the size in bytes of the file at the given URL, or None if it cannot be obtained.
- Parameters
src_uri – URL that points to a file or object in the storage mechanism of a supported URL scheme e.g. a blob in an AWS s3 bucket.
- write_file(local_path, job_id=None, cleanup=False)¶
Takes a file (as a path) and places it in this job store. Returns an ID that can be used to retrieve the file at a later time. The file is written in a atomic manner. It will not appear in the jobStore until the write has successfully completed.
- Parameters
local_path (str) – the path to the local file that will be uploaded to the job store. The last path component (basename of the file) will remain associated with the file in the file store, if supported, so that the file can be searched for by name or name glob.
job_id (str) – the id of a job, or None. If specified, the may be associated with that job in a job-store-specific way. This may influence the returned ID.
cleanup (bool) – Whether to attempt to delete the file when the job whose jobStoreID was given as jobStoreID is deleted with jobStore.delete(job). If jobStoreID was not given, does nothing.
- Raises
ConcurrentFileModificationException – if the file was modified concurrently during an invocation of this method
NoSuchJobException – if the job specified via jobStoreID does not exist
FIXME: some implementations may not raise this
- Returns
an ID referencing the newly created file and can be used to read the file in the future.
- Return type
- write_file_stream(job_id=None, cleanup=False, basename=None, encoding=None, errors=None)¶
Similar to writeFile, but 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. The yielded file handle does not need to and should not be closed explicitly. The file is written in a atomic manner. It will not appear in the jobStore until the write has successfully completed.
- Parameters
job_id (str) – the id of a job, or None. If specified, the may be associated with that job in a job-store-specific way. This may influence the returned ID.
cleanup (bool) – Whether to attempt to delete the file when the job whose jobStoreID was given as jobStoreID is deleted with jobStore.delete(job). If jobStoreID was not given, does nothing.
basename (str) – If supported by the implementation, use the given file basename so that when searching the job store with a query matching that basename, the file will be detected.
encoding (str) – the name of the encoding used to encode the file. Encodings are the same as for encode(). Defaults to None which represents binary mode.
errors (str) – an optional string that specifies how encoding errors are to be handled. Errors are the same as for open(). Defaults to ‘strict’ when an encoding is specified.
- Raises
ConcurrentFileModificationException – if the file was modified concurrently during an invocation of this method
NoSuchJobException – if the job specified via jobStoreID does not exist
FIXME: some implementations may not raise this
Returns a context manager yielding a writable file handle to the global file referenced by the given name. File will be created in an atomic manner.
- Parameters
shared_file_name (str) – A file name matching AbstractJobStore.fileNameRegex, unique within this job store
encrypted (bool) – True if the file must be encrypted, None if it may be encrypted or False if it must be stored in the clear.
encoding (str) – the name of the encoding used to encode the file. Encodings are the same as for encode(). Defaults to None which represents binary mode.
errors (str) – an optional string that specifies how encoding errors are to be handled. Errors are the same as for open(). Defaults to ‘strict’ when an encoding is specified.
- Raises
ConcurrentFileModificationException – if the file was modified concurrently during an invocation of this method
- Returns
a context manager yielding a writable file handle
- Return type
Iterator[IO[bytes]]
- update_file(file_id, local_path)¶
Replaces the existing version of a file in the job store.
Throws an exception if the file does not exist.
- Parameters
file_id – the ID of the file in the job store to be updated
local_path – the local path to a file that will overwrite the current version in the job store
- Raises
ConcurrentFileModificationException – if the file was modified concurrently during an invocation of this method
NoSuchFileException – if the specified file does not exist
- update_file_stream(file_id, encoding=None, errors=None)¶
Replaces the existing version of a file in the job store. Similar to writeFile, but returns a context manager yielding a file handle which can be written to. The yielded file handle does not need to and should not be closed explicitly.
- Parameters
file_id (str) – the ID of the file in the job store to be updated
encoding (str) – the name of the encoding used to encode the file. Encodings are the same as for encode(). Defaults to None which represents binary mode.
errors (str) – an optional string that specifies how encoding errors are to be handled. Errors are the same as for open(). Defaults to ‘strict’ when an encoding is specified.
- Raises
ConcurrentFileModificationException – if the file was modified concurrently during an invocation of this method
NoSuchFileException – if the specified file does not exist
- file_exists(file_id)¶
Determine whether a file exists in this job store.
- Parameters
file_id – an ID referencing the file to be checked
- get_file_size(file_id)¶
Get the size of the given file in bytes, or 0 if it does not exist when queried.
Note that job stores which encrypt files might return overestimates of file sizes, since the encrypted file may have been padded to the nearest block, augmented with an initialization vector, etc.
- read_file(file_id, local_path, symlink=False)¶
Copies or hard links the file referenced by jobStoreFileID to the given local file path. The version will be consistent with the last copy of the file written/updated. If the file in the job store is later modified via updateFile or updateFileStream, it is implementation-defined whether those writes will be visible at localFilePath. The file is copied in an atomic manner. It will not appear in the local file system until the copy has completed.
The file at the given local path may not be modified after this method returns!
Note! Implementations of readFile need to respect/provide the executable attribute on FileIDs.
- Parameters
file_id (str) – ID of the file to be copied
local_path (str) – the local path indicating where to place the contents of the given file in the job store
symlink (bool) – whether the reader can tolerate a symlink. If set to true, the job store may create a symlink instead of a full copy of the file or a hard link.
- read_file_stream(file_id, encoding=None, errors=None)¶
Similar to readFile, but returns a context manager yielding a file handle which can be read from. The yielded file handle does not need to and should not be closed explicitly.
- Parameters
file_id (str) – ID of the file to get a readable file handle for
encoding (str) – the name of the encoding used to decode the file. Encodings are the same as for decode(). Defaults to None which represents binary mode.
errors (str) – an optional string that specifies how encoding errors are to be handled. Errors are the same as for open(). Defaults to ‘strict’ when an encoding is specified.
- Returns
a context manager yielding a file handle which can be read from
- Return type
Returns a context manager yielding a readable file handle to the global file referenced by the given name.
- Parameters
shared_file_name (str) – A file name matching AbstractJobStore.fileNameRegex, unique within this job store
encoding (str) – the name of the encoding used to decode the file. Encodings are the same as for decode(). Defaults to None which represents binary mode.
errors (str) – an optional string that specifies how encoding errors are to be handled. Errors are the same as for open(). Defaults to ‘strict’ when an encoding is specified.
- Returns
a context manager yielding a readable file handle
- Return type
Iterator[IO[bytes]]
- delete_file(file_id)¶
Deletes the file with the given ID from this job store. This operation is idempotent, i.e. deleting a file twice or deleting a non-existent file will succeed silently.
- Parameters
file_id (str) – ID of the file to delete
- write_logs(msg)¶
Stores a message as a log in the jobstore.
- Parameters
msg (str) – the string to be written
- Raises
ConcurrentFileModificationException – if the file was modified concurrently during an invocation of this method
- read_logs(callback, read_all=False)¶
Reads logs accumulated by the write_logs() method. For each log this method calls the given callback function with the message as an argument (rather than returning logs directly, this method must be supplied with a callback which will process log messages).
Only unread logs will be read unless the read_all parameter is set.
- Parameters
callback (Callable) – a function to be applied to each of the stats file handles found
read_all (bool) – a boolean indicating whether to read the already processed stats files in addition to the unread stats files
- Raises
ConcurrentFileModificationException – if the file was modified concurrently during an invocation of this method
- Returns
the number of stats files processed
- Return type
- get_public_url(jobStoreFileID)¶
Returns a publicly accessible URL to the given file in the job store. The returned URL may expire as early as 1h after its been returned. Throw an exception if the file does not exist.
- Parameters
file_name (str) – the jobStoreFileID of the file to generate a URL for
- Raises
NoSuchFileException – if the specified file does not exist in this job store
- Return type
Differs from
getPublicUrl()in that this method is for generating URLs for shared files written bywriteSharedFileStream().Returns a publicly accessible URL to the given file in the job store. The returned URL starts with ‘http:’, ‘https:’ or ‘file:’. The returned URL may expire as early as 1h after its been returned. Throw an exception if the file does not exist.
- Parameters
shared_file_name (str) – The name of the shared file to generate a publically accessible url for.
- Raises
NoSuchFileException – raised if the specified file does not exist in the store
- Return type
- destroy()¶
The inverse of
initialize(), this method deletes the physical storage represented by this instance. While not being atomic, this method is at least idempotent, as a means to counteract potential issues with eventual consistency exhibited by the underlying storage mechanisms. This means that if the method fails (raises an exception), it may (and should be) invoked again. If the underlying storage mechanism is eventually consistent, even a successful invocation is not an ironclad guarantee that the physical storage vanished completely and immediately. A successful invocation only guarantees that the deletion will eventually happen. It is therefore recommended to not immediately reuse the same job store location for a new Toil workflow.
- toil.jobStores.aws.jobStore.aRepr¶
- toil.jobStores.aws.jobStore.custom_repr¶
