toil.test.src.workerTest¶

Classes¶

`Config`	Class to represent configuration operations for a toil workflow run.
`CheckpointJobDescription`	A description of a job that is a checkpoint.
`JobDescription`	Stores all the information that the Toil Leader ever needs to know about a Job.
`FileJobStore`	A job store that uses a directory on a locally attached file system. To be compatible with
`ToilTest`	A common base class for Toil tests.
`WorkerTests`	Test miscellaneous units of the worker.

Functions¶

nextChainable(predecessor, job_store, config)

Returns the next chainable job's JobDescription after the given predecessor

Module Contents¶

class toil.test.src.workerTest.Config[source]¶

Class to represent configuration operations for a toil workflow run.

logFile: str | None¶

logRotating: bool¶

cleanWorkDir: str¶

max_jobs: int¶

max_local_jobs: int¶

manualMemArgs: bool¶

run_local_jobs_on_workers: bool¶

coalesceStatusCalls: bool¶

mesos_endpoint: str | None¶

mesos_framework_id: str | None¶

mesos_role: str | None¶

mesos_name: str¶

kubernetes_host_path: str | None¶

kubernetes_owner: str | None¶

kubernetes_service_account: str | None¶

kubernetes_pod_timeout: float¶

kubernetes_privileged: bool¶

tes_endpoint: str¶

tes_user: str¶

tes_password: str¶

tes_bearer_token: str¶

aws_batch_region: str | None¶

aws_batch_queue: str | None¶

aws_batch_job_role_arn: str | None¶

scale: float¶

batchSystem: str¶

batch_logs_dir: str | None¶: The backing scheduler will be instructed, if possible, to save logs to this directory, where the leader can read them.

statePollingWait: int¶

state_polling_timeout: int¶

disableAutoDeployment: bool¶

workflowID: str | None¶: This attribute uniquely identifies the job store and therefore the workflow. It is necessary in order to distinguish between two consecutive workflows for which self.jobStore is the same, e.g. when a job store name is reused after a previous run has finished successfully and its job store has been clean up.

workflowAttemptNumber: int¶

jobStore: str¶

logLevel: str¶

colored_logs: bool¶

workDir: str | None¶

coordination_dir: str | None¶

noStdOutErr: bool¶

stats: bool¶

clean: str | None¶

clusterStats: str¶

restart: bool¶

caching: bool | None¶

symlinkImports: bool¶

moveOutputs: bool¶

provisioner: str | None¶

nodeTypes: List[Tuple[Set[str], float | None]]¶

minNodes: List[int]¶

maxNodes: List[int]¶

targetTime: float¶

betaInertia: float¶

scaleInterval: int¶

preemptibleCompensation: float¶

nodeStorage: int¶

nodeStorageOverrides: List[str]¶

metrics: bool¶

assume_zero_overhead: bool¶

maxPreemptibleServiceJobs: int¶

maxServiceJobs: int¶

deadlockWait: float | int¶

deadlockCheckInterval: float | int¶

defaultMemory: int¶

defaultCores: float | int¶

defaultDisk: int¶

defaultPreemptible: bool¶

defaultAccelerators: List[toil.job.AcceleratorRequirement]¶

maxCores: int¶

maxMemory: int¶

maxDisk: int¶

retryCount: int¶

enableUnlimitedPreemptibleRetries: bool¶

doubleMem: bool¶

maxJobDuration: int¶

rescueJobsFrequency: int¶

job_store_timeout: float¶

maxLogFileSize: int¶

writeLogs: str¶

writeLogsGzip: str¶

writeLogsFromAllJobs: bool¶

write_messages: str | None¶

realTimeLogging: bool¶

environment: Dict[str, str]¶

disableChaining: bool¶

disableJobStoreChecksumVerification: bool¶

sseKey: str | None¶

servicePollingInterval: int¶

useAsync: bool¶

forceDockerAppliance: bool¶

statusWait: int¶

disableProgress: bool¶

readGlobalFileMutableByDefault: bool¶

debugWorker: bool¶

disableWorkerOutputCapture: bool¶

badWorker: float¶

badWorkerFailInterval: float¶

kill_polling_interval: int¶

cwl: bool¶

set_from_default_config()[source]¶

Return type:: None

prepare_start()[source]¶

After options are set, prepare for initial start of workflow.

Return type:: None

prepare_restart()[source]¶

Before restart options are set, prepare for a restart of a workflow. Set up any execution-specific parameters and clear out any stale ones.

Return type:: None

setOptions(options)[source]¶

Creates a config object from the options object.

Parameters:: options (argparse.Namespace)
Return type:: None

check_configuration_consistency()[source]¶

Old checks that cannot be fit into an action class for argparse

Return type:: None

__eq__(other)[source]¶

Return self==value.

Parameters:: other (object)
Return type:: bool

__hash__()[source]¶

Return hash(self).

Return type:: int

class toil.test.src.workerTest.CheckpointJobDescription(*args, **kwargs)[source]¶

Bases: JobDescription

A description of a job that is a checkpoint.

set_checkpoint()[source]¶

Save a body checkpoint into self.checkpoint

Return type:: str

restore_checkpoint()[source]¶

Restore the body checkpoint from self.checkpoint

Return type:: None

restartCheckpoint(jobStore)[source]¶

Restart a checkpoint after the total failure of jobs in its subtree.

Writes the changes to the jobStore immediately. All the checkpoint’s successors will be deleted, but its try count will not be decreased.

Returns a list with the IDs of any successors deleted.

Parameters:: jobStore (toil.jobStores.abstractJobStore.AbstractJobStore)
Return type:: List[str]

class toil.test.src.workerTest.JobDescription(requirements, jobName, unitName='', displayName='', local=None)[source]¶

Bases: Requirer

Stores all the information that the Toil Leader ever needs to know about a Job.

This includes:

Resource requirements.
Which jobs are children or follow-ons or predecessors of this job.
A reference to the Job object in the job store.

Can be obtained from an actual (i.e. executable) Job object, and can be used to obtain the Job object from the JobStore.

Never contains other Jobs or JobDescriptions: all reference is by ID.

Subclassed into variants for checkpoint jobs and service jobs that have their specific parameters.

Parameters:

requirements (Mapping[str, Union[int, str, bool]])
jobName (str)
unitName (Optional[str])
displayName (Optional[str])
local (Optional[bool])

get_names()[source]¶

Get the names and ID of this job as a named tuple.

Return type:: toil.bus.Names

get_chain()[source]¶

Get all the jobs that executed in this job’s chain, in order.

For each job, produces a named tuple with its various names and its original job store ID. The jobs in the chain are in execution order.

If the job hasn’t run yet or it didn’t chain, produces a one-item list.

Return type:: List[toil.bus.Names]

serviceHostIDsInBatches()[source]¶

Find all batches of service host job IDs that can be started at the same time.

(in the order they need to start in)

Return type:: Iterator[List[str]]

successorsAndServiceHosts()[source]¶

Get an iterator over all child, follow-on, and service job IDs.

Return type:: Iterator[str]

allSuccessors()[source]¶

Get an iterator over all child, follow-on, and chained, inherited successor job IDs.

Follow-ons will come before children.

Return type:: Iterator[str]

successors_by_phase()[source]¶

Get an iterator over all child/follow-on/chained inherited successor job IDs, along with their phase numbere on the stack.

Phases ececute higher numbers to lower numbers.

Return type:: Iterator[Tuple[int, str]]

property services¶
Get a collection of the IDs of service host jobs for this job, in arbitrary order.: Will be empty if the job has no unfinished services.

has_body()[source]¶

Returns True if we have a job body associated, and False otherwise.

Return type:: bool

attach_body(file_store_id, user_script)[source]¶

Attach a job body to this JobDescription.

Takes the file store ID that the body is stored at, and the required user script module.

The file store ID can also be “firstJob” for the root job, stored as a shared file instead.

Parameters:

file_store_id (str)
user_script (toil.resource.ModuleDescriptor)

Return type:

None

detach_body()[source]¶

Drop the body reference from a JobDescription.

Return type:: None

get_body()[source]¶

Get the information needed to load the job body.

Returns:: a file store ID (or magic shared file name “firstJob”) and a user script module.
Return type:: Tuple[str, toil.resource.ModuleDescriptor]

Fails if no body is attached; check has_body() first.

nextSuccessors()[source]¶

Return the collection of job IDs for the successors of this job that are ready to run.

If those jobs have multiple predecessor relationships, they may still be blocked on other jobs.

Returns None when at the final phase (all successors done), and an empty collection if there are more phases but they can’t be entered yet (e.g. because we are waiting for the job itself to run).

Return type:: Optional[Set[str]]

filterSuccessors(predicate)[source]¶

Keep only successor jobs for which the given predicate function approves.

The predicate function is called with the job’s ID.

Treats all other successors as complete and forgets them.

Parameters:: predicate (Callable[[str], bool])
Return type:: None

filterServiceHosts(predicate)[source]¶

Keep only services for which the given predicate approves.

The predicate function is called with the service host job’s ID.

Treats all other services as complete and forgets them.

Parameters:: predicate (Callable[[str], bool])
Return type:: None

clear_nonexistent_dependents(job_store)[source]¶

Remove all references to child, follow-on, and associated service jobs that do not exist.

That is to say, all those that have been completed and removed.

Parameters:: job_store (toil.jobStores.abstractJobStore.AbstractJobStore)
Return type:: None

clear_dependents()[source]¶

Remove all references to successor and service jobs.

Return type:: None

is_subtree_done()[source]¶

Check if the subtree is done.

Returns:: True if the job appears to be done, and all related child, follow-on, and service jobs appear to be finished and removed.
Return type:: bool

replace(other)[source]¶

Take on the ID of another JobDescription, retaining our own state and type.

When updated in the JobStore, we will save over the other JobDescription.

Useful for chaining jobs: the chained-to job can replace the parent job.

Merges cleanup state and successors other than this job from the job being replaced into this one.

Parameters:: other (JobDescription) – Job description to replace.
Return type:: None

assert_is_not_newer_than(other)[source]¶

Make sure this JobDescription is not newer than a prospective new version of the JobDescription.

Parameters:: other (JobDescription)
Return type:: None

is_updated_by(other)[source]¶

Return True if the passed JobDescription is a distinct, newer version of this one.

Parameters:: other (JobDescription)
Return type:: bool

addChild(childID)[source]¶

Make the job with the given ID a child of the described job.

Parameters:: childID (str)
Return type:: None

addFollowOn(followOnID)[source]¶

Make the job with the given ID a follow-on of the described job.

Parameters:: followOnID (str)
Return type:: None

addServiceHostJob(serviceID, parentServiceID=None)[source]¶

Make the ServiceHostJob with the given ID a service of the described job.

If a parent ServiceHostJob ID is given, that parent service will be started first, and must have already been added.

hasChild(childID)[source]¶

Return True if the job with the given ID is a child of the described job.

Parameters:: childID (str)
Return type:: bool

hasFollowOn(followOnID)[source]¶

Test if the job with the given ID is a follow-on of the described job.

Parameters:: followOnID (str)
Return type:: bool

hasServiceHostJob(serviceID)[source]¶

Test if the ServiceHostJob is a service of the described job.

Return type:: bool

renameReferences(renames)[source]¶

Apply the given dict of ID renames to all references to jobs.

Does not modify our own ID or those of finished predecessors. IDs not present in the renames dict are left as-is.

Parameters:: renames (Dict[TemporaryID, str]) – Rename operations to apply.
Return type:: None

addPredecessor()[source]¶

Notify the JobDescription that a predecessor has been added to its Job.

Return type:: None

onRegistration(jobStore)[source]¶

Perform setup work that requires the JobStore.

Called by the Job saving logic when this JobDescription meets the JobStore and has its ID assigned.

Overridden to perform setup work (like hooking up flag files for service jobs) that requires the JobStore.

Parameters:: jobStore (toil.jobStores.abstractJobStore.AbstractJobStore) – The job store we are being placed into
Return type:: None

setupJobAfterFailure(exit_status=None, exit_reason=None)[source]¶

Configure job after a failure.

Reduce the remainingTryCount if greater than zero and set the memory to be at least as big as the default memory (in case of exhaustion of memory, which is common).

Requires a configuration to have been assigned (see toil.job.Requirer.assignConfig()).

Parameters:

exit_status (Optional[int]) – The exit code from the job.
exit_reason (Optional[toil.batchSystems.abstractBatchSystem.BatchJobExitReason]) – The reason the job stopped, if available from the batch system.

Return type:

None

getLogFileHandle(jobStore)[source]¶

Create a context manager that yields a file handle to the log file.

Assumes logJobStoreFileID is set.

property remainingTryCount¶
Get the number of tries remaining.: The try count set on the JobDescription, or the default based on the retry count from the config if none is set.

clearRemainingTryCount()[source]¶

Clear remainingTryCount and set it back to its default value.

Returns:: True if a modification to the JobDescription was made, and False otherwise.
Return type:: bool

__str__()[source]¶

Produce a useful logging string identifying this job.

Return type:: str

__repr__()[source]¶: Return repr(self).

reserve_versions(count)[source]¶

Reserve a job version number for later, for journaling asynchronously.

Parameters:: count (int)
Return type:: None

pre_update_hook()[source]¶

Run before pickling and saving a created or updated version of this job.

Called by the job store.

Return type:: None

class toil.test.src.workerTest.FileJobStore(path, fanOut=1000)[source]¶

Bases: toil.jobStores.abstractJobStore.AbstractJobStore

A job store that uses a directory on a locally attached file system. To be compatible with distributed batch systems, that file system must be shared by all worker nodes.

Parameters:

path (str)
fanOut (int)

validDirs = 'abcdefghijklmnopqrstuvwxyz0123456789'¶

validDirsSet¶

JOB_DIR_PREFIX = 'instance-'¶

JOB_NAME_DIR_PREFIX = 'kind-'¶

BUFFER_SIZE = 10485760¶

default_caching()[source]¶

Jobstore’s preference as to whether it likes caching or doesn’t care about it. Some jobstores benefit from caching, however on some local configurations it can be flaky.

see https://github.com/DataBiosphere/toil/issues/4218

Return type:: bool

__repr__()[source]¶: Return repr(self).

initialize(config)[source]¶

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()[source]¶

Connect this instance to the physical storage it represents and load the Toil configuration into the AbstractJobStore.config attribute.

Raises:: NoSuchJobStoreException – if the physical storage for this job store doesn’t exist

destroy()[source]¶: 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.

assign_job_id(job_description)[source]¶

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)[source]¶

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:: toil.job.JobDescription

batch()[source]¶: 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.

job_exists(job_id)[source]¶

Indicates whether a description of the job with the specified jobStoreID exists in the job store

Return type:: bool

get_public_url(jobStoreFileID)[source]¶

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:: str

get_shared_public_url(sharedFileName)[source]¶

Differs from getPublicUrl() in that this method is for generating URLs for shared files written by writeSharedFileStream().

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:: str

load_job(job_id)[source]¶

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)[source]¶

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)[source]¶

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

jobs()[source]¶

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]

optional_hard_copy(hardlink)[source]¶

write_file(local_path, job_id=None, cleanup=False)[source]¶

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:: str

write_file_stream(job_id=None, cleanup=False, basename=None, encoding=None, errors=None)[source]¶

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 file handle which can be written to and an ID that references the newly created file and can be used to read the file in the future.
Return type:: Iterator[Tuple[IO[bytes], str]]

get_empty_file_store_id(jobStoreID=None, cleanup=False, basename=None)[source]¶

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:

str

update_file(file_id, local_path)[source]¶

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

read_file(file_id, local_path, symlink=False)[source]¶

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.

Return type:

None

delete_file(file_id)[source]¶

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

file_exists(file_id)[source]¶

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)[source]¶

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.

Parameters:: file_id (str) – an ID referencing the file to be checked
Return type:: int

update_file_stream(file_id, encoding=None, errors=None)[source]¶

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

read_file_stream(file_id: str | toil.fileStores.FileID, encoding: Literal[None] = None, errors: str | None = None) → Iterator[IO[bytes]][source]¶

read_file_stream(file_id: str | toil.fileStores.FileID, encoding: str, errors: str | None = None) → Iterator[IO[str]]

read_file_stream(file_id: str | toil.fileStores.FileID, encoding: str | None = None, errors: str | None = None) → Iterator[IO[bytes]] | Iterator[IO[str]]

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:

Iterator[Union[IO[bytes], IO[str]]]

write_shared_file_stream(shared_file_name, encrypted=None, encoding=None, errors=None)[source]¶

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]]

read_shared_file_stream(shared_file_name, encoding=None, errors=None)[source]¶

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]]

list_all_file_names(for_job=None)[source]¶

Get all the file names (not file IDs) of files stored in the job store.

Used for debugging.

Parameters:: for_job (Optional[str]) – If set, restrict the list to files for a particular job.
Return type:: Iterable[str]

write_logs(msg)[source]¶

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)[source]¶

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:

int

class toil.test.src.workerTest.ToilTest(methodName='runTest')[source]¶

Bases: unittest.TestCase

A common base class for Toil tests.

Please have every test case directly or indirectly inherit this one.

When running tests you may optionally set the TOIL_TEST_TEMP environment variable to the path of a directory where you want temporary test files be placed. The directory will be created if it doesn’t exist. The path may be relative in which case it will be assumed to be relative to the project root. If TOIL_TEST_TEMP is not defined, temporary files and directories will be created in the system’s default location for such files and any temporary files or directories left over from tests will be removed automatically removed during tear down. Otherwise, left-over files will not be removed.

setup_method(method)[source]¶

Parameters:: method (Any)
Return type:: None

classmethod setUpClass()[source]¶

Hook method for setting up class fixture before running tests in the class.

Return type:: None

classmethod tearDownClass()[source]¶

Hook method for deconstructing the class fixture after running all tests in the class.

Return type:: None

setUp()[source]¶

Hook method for setting up the test fixture before exercising it.

Return type:: None

tearDown()[source]¶

Hook method for deconstructing the test fixture after testing it.

Return type:: None

classmethod awsRegion()[source]¶

Pick an appropriate AWS region.

Use us-west-2 unless running on EC2, in which case use the region in which the instance is located

Return type:: str

toil.test.src.workerTest.nextChainable(predecessor, job_store, config)[source]¶

Returns the next chainable job’s JobDescription after the given predecessor JobDescription, if one exists, or None if the chain must terminate.

Parameters:

predecessor (toil.job.JobDescription) – The job to chain from
job_store (toil.jobStores.abstractJobStore.AbstractJobStore) – The JobStore to fetch JobDescriptions from.
config (toil.common.Config) – The configuration for the current run.

Return type: