HTCondor Version 10.0.9 Manual

classad.quote(input) → str :

Converts the Python string into a ClassAd string literal; this handles all the quoting rules for the ClassAd language. For example:

>>> classad.quote('hello'world')
''hello\\'world''

This allows one to safely handle user-provided strings to build expressions. For example:

>>> classad.ExprTree('Foo =?= %s' % classad.quote('hello'world'))
Foo is 'hello\'world'

Parameters: input (str) – Input string to quote.
Returns: The corresponding string literal as a Python string.
Return type: str

classad.unquote(input) → str :

Converts a ClassAd string literal, formatted as a string, back into a Python string. This handles all the quoting rules for the ClassAd language.

Parameters: input (str) – Input string to unquote.
Returns: The corresponding Python string for a string literal.
Return type: str

classad.Attribute(name) → ExprTree :

Given an attribute name, construct an ExprTree object which is a reference to that attribute.

Note

This may be used to build ClassAd expressions easily from python. For example, the ClassAd expression foo == 1 can be constructed by the Python code Attribute('foo') == 1.

Parameters: name (str) – Name of attribute to reference.
Returns: Corresponding expression consisting of an attribute reference.
Return type: ExprTree

classad.Function()

Given function name name, and zero-or-more arguments, construct an ExprTree which is a function call expression. The function is not evaluated.

For example, the ClassAd expression strcat('hello ', 'world') can be constructed by the Python expression Function('strcat', 'hello ', 'world').

Returns: Corresponding expression consisting of a function call.
Return type: ExprTree

classad.Literal(obj) → ExprTree :

Convert a given Python object to a ClassAd literal.

Python strings, floats, integers, and booleans have equivalent literals in the ClassAd language.

Parameters: obj – Python object to convert to an expression.
Returns: Corresponding expression consising of a literal.
Return type: ExprTree

classad.lastError() → str :

Return the string representation of the last error to occur in the ClassAd library.

As the ClassAd language has no concept of an exception, this is the only mechanism to receive detailed error messages from functions.

classad.register(function, name=None) → None :

Given the Python function, register it as a function in the ClassAd language. This allows the invocation of the Python function from within a ClassAd evaluation context.

Parameters

function – A callable object to register with the ClassAd runtime.
name (str) – Provides an alternate name for the function within the ClassAd library. The default, None, indicates to use the built-in function name.

classad.registerLibrary(arg1) → None :

Given a file system path, attempt to load it as a shared library of ClassAd functions. See the upstream documentation for configuration variable CLASSAD_USER_LIBS for more information about loadable libraries for ClassAd functions.

Parameters: path (str) – The library to load.

Parser Control

The behavior of parseAds(), parseNext(), and parseOne() can be controlled by giving them different values of the Parser enumeration.

class classad.Parser

An enumeration that controls the behavior of the ClassAd parser. The values of the enumeration are…

Auto: The parser should automatically determine the ClassAd representation.

Old: The parser should only accept the old ClassAd format.

New: The parser should only accept the new ClassAd format.

Utility Functions

classad.version() → str :: Return the version of the linked ClassAd library.

Exceptions

For backwards-compatibility, the exceptions in this module inherit from the built-in exceptions raised in earlier (pre-v8.9.9) versions.

class classad.ClassAdException: Never raised. The parent class of all exceptions raised by this module.

class classad.ClassAdEnumError: Raised when a value must be in an enumeration, but isn’t.

class classad.ClassAdEvaluationError: Raised when the ClassAd library fails to evaluate an expression.

class classad.ClassAdInternalError: Raised when the ClassAd library encounters an internal error.

class classad.ClassAdOSError: Raised instead of OSError for backwards compatibility.

class classad.ClassAdParseError: Raised when the ClassAd library fails to parse a (putative) ClassAd.

class classad.ClassAdTypeError: Raised instead of TypeError for backwards compatibility.

class classad.ClassAdValueError: Raised instead of ValueError for backwards compatibility.

Deprecated Functions

The functions in this section are deprecated; new code should not use them and existing code should be rewritten to use their replacements.

classad.parse(input) → ClassAd :

Warning

This function is deprecated.

Parse input, in the new ClassAd format, into a ClassAd object.

Parameters: input (str or file) – A string-like object or a file pointer.
Returns: Corresponding ClassAd object.
Return type: ClassAd

classad.parseOld(input) → ClassAd :

Warning

This function is deprecated.

Parse input, in the old ClassAd format, into a ClassAd object.

Parameters: input (str or file) – A string-like object or a file pointer.
Returns: Corresponding ClassAd object.
Return type: ClassAd

`htcondor` API Reference

This page is an exhaustive reference of the API exposed by the htcondor module. It is not meant to be a tutorial for new users but rather a helpful guide for those who already understand the basic usage of the module.

Interacting with Collectors

class htcondor.Collector(pool)

Client object for a remote condor_collector. The Collector can be used to:

Locate a daemon.
Query the condor_collector for one or more specific ClassAds.
Advertise a new ad to the condor_collector.

Parameters: pool (str or list[str]) – A host:port pair specified for the remote collector (or a list of pairs for HA setups). If omitted, the value of configuration parameter COLLECTOR_HOST is used.

locate(daemon_type, name) → object :

Query the condor_collector for a particular daemon.

Parameters

daemon_type (DaemonTypes) – The type of daemon to locate.
name (str) – The name of daemon to locate. If not specified, it searches for the local daemon.

Returns

a minimal ClassAd of the requested daemon, sufficient only to contact the daemon; typically, this limits to the MyAddress attribute.

Return type

locateAll(daemon_type) → object :

Query the condor_collector daemon for all ClassAds of a particular type. Returns a list of matching ClassAds.

Parameters: daemon_type (DaemonTypes) – The type of daemon to locate.
Returns: Matching ClassAds
Return type: list[ClassAd]

query(ad_type=htcondor.htcondor.AdTypes.Any, constraint='', projection=[], statistics='') → object :

Query the contents of a condor_collector daemon. Returns a list of ClassAds that match the constraint parameter.

Parameters

ad_type (AdTypes) – The type of ClassAd to return. If not specified, the type will be ANY_AD.
constraint (str or ExprTree) – A constraint for the collector query; only ads matching this constraint are returned. If not specified, all matching ads of the given type are returned.
projection (list[str]) – A list of attributes to use for the projection. Only these attributes, plus a few server-managed, are returned in each ClassAd.
statistics (list[str]) – Statistics attributes to include, if they exist for the specified daemon.

Returns

A list of matching ads.

Return type

list[ClassAd]

directQuery(daemon_type, name='', projection=[], statistics='') → object :

Query the specified daemon directly for a ClassAd, instead of using the ClassAd from the condor_collector daemon. Requires the client library to first locate the daemon in the collector, then querying the remote daemon.

Parameters

daemon_type (DaemonTypes) – Specifies the type of the remote daemon to query.
name (str) – Specifies the daemon’s name. If not specified, the local daemon is used.
projection (list[str]) – is a list of attributes requested, to obtain only a subset of the attributes from the daemon’s ClassAd.
statistics (str) – Statistics attributes to include, if they exist for the specified daemon.

Returns

The ad of the specified daemon.

Return type

advertise(ad_list, command='UPDATE_AD_GENERIC', use_tcp=True) → None :

Advertise a list of ClassAds into the condor_collector.

Parameters

ad_list (list[ClassAds]) – ClassAds to advertise.
command (str) – An advertise command for the remote condor_collector. It defaults to UPDATE_AD_GENERIC. Other commands, such as UPDATE_STARTD_AD, may require different authorization levels with the remote daemon.
use_tcp (bool) – When set to True, updates are sent via TCP. Defaults to True.

class htcondor.DaemonTypes

An enumeration of different types of daemons available to HTCondor.

The values of the enumeration are:

None

Any: Any type of daemon; useful when specifying queries where all matching daemons should be returned.

Master: Ads representing the condor_master.

Schedd: Ads representing the condor_schedd.

Startd: Ads representing the resources on a worker node.

Collector: Ads representing the condor_collector.

Negotiator: Ads representing the condor_negotiator.

HAD: Ads representing the high-availability daemons (condor_had).

Generic: All other ads that are not categorized as above.

Credd

class htcondor.AdTypes

A list of different types of ads that may be kept in the condor_collector.

The values of the enumeration are:

None

Any: Type representing any matching ad. Useful for queries that match everything in the collector.

Generic: Generic ads, associated with no particular daemon.

Startd: Startd ads, produced by the condor_startd daemon. Represents the available slots managed by the startd.

StartdPrivate: The “private” ads, containing the claim IDs associated with a particular slot. These require additional authorization to read as the claim ID may be used to run jobs on the slot.

Schedd: Schedd ads, produced by the condor_schedd daemon.

Master: Master ads, produced by the condor_master daemon.

Collector: Ads from the condor_collector daemon.

Negotiator: Negotiator ads, produced by the condor_negotiator daemon.

Submitter: Ads describing the submitters with available jobs to run; produced by the condor_schedd and read by the condor_negotiator to determine which users need a new negotiation cycle.

Grid: Ads associated with the grid universe.

HAD: Ads produced by the condor_had.

License: License ads. These do not appear to be used by any modern HTCondor daemon.

Credd

Defrag

Accounting

Interacting with Schedulers

class htcondor.Schedd(location_ad)

Client object for a condor_schedd.

Parameters: location_ad (ClassAd or DaemonLocation) – An Ad describing the location of the remote condor_schedd daemon, as returned by the Collector.locate() method, or a tuple of type DaemonLocation as returned by Schedd.location(). If the parameter is omitted, the local condor_schedd daemon is used.

transaction(flags=0, continue_txn=False) → Transaction :

Start a transaction with the condor_schedd.

Starting a new transaction while one is ongoing is an error unless the continue_txn flag is set.

Parameters

flags (TransactionFlags) – Flags controlling the behavior of the transaction, defaulting to 0.
continue_txn (bool) – Set to True if you would like this transaction to extend any pre-existing transaction; defaults to False. If this is not set, starting a transaction inside a pre-existing transaction will cause an exception to be thrown.

Returns

A transaction context manager object.

query(constraint='true', projection=[], callback=None, limit=- 1, opts=htcondor.htcondor.QueryOpts.Default) → object :

Query the condor_schedd daemon for job ads.

Warning

This returns a list of ClassAd objects, meaning all results must be held in memory simultaneously. This may be memory-intensive for queries that return many and/or large jobs ads. If you are retrieving many large ads, consider using xquery() instead to reduce memory requirements.

Parameters

constraint (str or ExprTree) – A query constraint. Only jobs matching this constraint will be returned. Defaults to 'true', which means all jobs will be returned.
projection (list[str]) – Attributes that will be returned for each job in the query. At least the attributes in this list will be returned, but additional ones may be returned as well. An empty list (the default) returns all attributes.
callback – A callable object; if provided, it will be invoked for each ClassAd. The return value (if not None) will be added to the returned list instead of the ad.
limit (int) – The maximum number of ads to return; the default (-1) is to return all ads.
opts (QueryOpts.) – Additional flags for the query; these may affect the behavior of the condor_schedd.

Returns

ClassAds representing the matching jobs.

Return type

list[ClassAd]

xquery(constraint='true', projection=[], limit=- 1, opts=htcondor.htcondor.QueryOpts.Default, name=None) → QueryIterator :

Query the condor_schedd daemon for job ads.

Warning

This returns an iterator of ClassAd objects, which means you may not need to hold all of the ads returned by the query in memory simultaneously. However, this method holds a connection open to the schedd, and a fork of the schedd will remain active, until you finish iterating. If you are not retrieving many large ads, consider using query() instead to reduce load on the schedd.

Parameters

constraint (str or ExprTree) – A query constraint. Only jobs matching this constraint will be returned. Defaults to 'true', which means all jobs will be returned.
projection (list[str]) – Attributes that will be returned for each job in the query. At least the attributes in this list will be returned, but additional ones may be returned as well. An empty list (the default) returns all attributes.
limit (int) – A limit on the number of matches to return. The default (-1) indicates all matching jobs should be returned.
opts (QueryOpts) – Additional flags for the query, from QueryOpts.
name (str) – A tag name for the returned query iterator. This string will always be returned from the QueryIterator.tag() method of the returned iterator. The default value is the condor_schedd’s name. This tag is useful to identify different queries when using the poll() function.

Returns

An iterator for the matching job ads

Return type

QueryIterator

act(action, job_spec, reason=None) → object :

Change status of job(s) in the condor_schedd daemon. The return value is a ClassAd object describing the number of jobs changed.

This will throw an exception if no jobs are matched by the constraint.

Parameters

action (JobAction) – The action to perform; must be of the enum JobAction.
job_spec (list[str] or str) – The job specification. It can either be a list of job IDs, or an ExprTree or string specifying a constraint. Only jobs matching this description will be acted upon.
reason (str) – The reason for the action. If omitted, the reason will be “Python-initiated action”.

edit(job_spec, attr, value, flags=0) → EditResult :

Edit one or more jobs in the queue.

This will throw an exception if no jobs are matched by the job_spec constraint.

Parameters

job_spec (list[str] or str) – The job specification. It can either be a list of job IDs or a string specifying a constraint. Only jobs matching this description will be acted upon.
attr (str) – The name of the attribute to edit.
value (str or ExprTree) – The new value of the attribute. It should be a string, which will be converted to a ClassAd expression, or an ExprTree object. Be mindful of quoting issues; to set the value to the string foo, one would set the value to ''foo''
flags (TransactionFlags) – Flags controlling the behavior of the transaction, defaulting to 0.

Returns

An EditResult containing the number of jobs that were edited.

Return type

EditResult

history(constraint, projection, match=- 1, since=None) → HistoryIterator :

Fetch history records from the condor_schedd daemon.

Parameters

constraint (str or ExprTree) – A query constraint. Only jobs matching this constraint will be returned. None will return all jobs.
projection (list[str]) – Attributes that will be returned for each job in the query. At least the attributes in this list will be returned, but additional ones may be returned as well. An empty list returns all attributes.
match (int) – A limit on the number of jobs to include; the default (-1) indicates to return all matching jobs. The schedd may return fewer than match jobs because of its setting of HISTORY_HELPER_MAX_HISTORY (default 10,000).
since (int, str, or ExprTree) – A cluster ID, job ID, or expression. If a cluster ID (passed as an int) or job ID (passed a str in the format {clusterID}.{procID}), only jobs recorded in the history file after (and not including) the matching ID will be returned. If an expression (passed as a str or ExprTree), jobs will be returned, most-recently-recorded first, until the expression becomes true; the job making the expression become true will not be returned. Thus, 1038 and clusterID == 1038 return the same set of jobs.

Returns

All matching ads in the Schedd history, with attributes according to the projection keyword.

Return type

HistoryIterator

submit(description, count=1, spool=False, ad_results=None, itemdata=None) → object :

Submit one or more jobs to the condor_schedd daemon.

This method requires the invoker to provide a Submit object that describes the jobs to submit. The return value will be a SubmitResult that contains the cluster ID and ClassAd of the submitted jobs.

For backward compatibility, this method will also accept a ClassAd that describes a single job to submit, but use of this form of is deprecated. Use submit_raw to submit raw job ClassAds. If the deprecated form is used the return value will be the cluster ID, and ad_results will optionally be the actual job ClassAds that were submitted.

Parameters

description (Submit (or deprecated ClassAd)) – The Submit description or ClassAd describing the job cluster.
count (int) – The number of jobs to submit to the job cluster. Defaults to 1.
spool (bool) – If True, jobs will be submitted in a spooling hold mode so that input files can be spooled to a remote condor_schedd daemon before starting the jobs. This parameter is necessary for jobs submitted to a remote condor_schedd that use HTCondor file transfer. When True, job will be left in the HOLD state until the spool() method is called.
ad_results (list[ClassAd]) – deprecated. If set to a list and a raw job ClassAd is passed as the first argument, the list object will contain the job ads that were submitted.

Returns

a SubmitResult, containing the cluster ID, cluster ClassAd and range of Job ids of the submitted job(s). If using the deprecated first argument, the return value will be an int and ad_results may contain submitted jobs ClassAds.

Return type

SubmitResult or int

submitMany(cluster_ad, proc_ads, spool=False, ad_results=None) → int :

Submit multiple jobs to the condor_schedd daemon, possibly including several distinct processes.

Parameters

cluster_ad (ClassAd) – The base ad for the new job cluster; this is the same format as in the submit() method.
proc_ads (list) – A list of 2-tuples; each tuple has the format of (proc_ad, count). For each list entry, this will result in count jobs being submitted inheriting from both cluster_ad and proc_ad.
spool (bool) – If True, the client inserts the necessary attributes into the job for it to have the input files spooled to a remote condor_schedd daemon. This parameter is necessary for jobs submitted to a remote condor_schedd that use HTCondor file transfer. When True, job will be left in the HOLD state until the spool() method is called.
ad_results (list[ClassAd]) – If set to a list, the list object will contain the job ads resulting from the job submission.

Returns

The newly created cluster ID.

Return type

int

spool(ad_list) → None :

Spools the files specified in a list of job ClassAds to the condor_schedd.

Parameters: ad_list (list[ClassAds]) – A list of job descriptions; typically, this is the list returned by the jobs() method on the submit result object.
Raises: RuntimeError – if there are any errors.

retrieve(arg1, arg2) → None :

Retrieve the output sandbox from one or more jobs.

Parameters: job_spec (str or list[ClassAd]) – An expression matching the list of job output sandboxes to retrieve.

refreshGSIProxy(cluster, proc, proxy_filename, lifetime) → int :

Refresh the GSI proxy of a job; the job’s proxy will be replaced the contents of the provided proxy_filename.

Note

Depending on the lifetime of the proxy in proxy_filename, the resulting lifetime may be shorter than the desired lifetime.

Parameters

cluster (int) – Cluster ID of the job to alter.
proc (int) – Process ID of the job to alter.
proxy_filename (str) – The name of the file containing the new proxy for the job.
lifetime (int) – Indicates the desired lifetime (in seconds) of the delegated proxy. A value of 0 specifies to not shorten the proxy lifetime. A value of -1 specifies to use the value of configuration variable DELEGATE_JOB_GSI_CREDENTIALS_LIFETIME.

reschedule() → None :: Send reschedule command to the schedd.

export_jobs(job_spec, export_dir, new_spool_dir) → object :

Export one or more job clusters from the queue to put those jobs into the externally managed state.

Parameters

job_spec (list[str] or str or ExprTree) – The job specification. It can either be a list of job IDs or a string specifying a constraint. Only jobs matching this description will be acted upon.
export_dir (str) – The path to the directory that exported jobs will be written into.
new_spool_dir (str) – The path to the base directory that exported jobs will use as IWD while they are exported

Returns

A ClassAd containing information about the export operation.

Return type

import_exported_job_results(import_dir) → object :

Import results from previously exported jobs, and take those jobs back out of the externally managed state.

Parameters: import_dir (str) – The path to the modified form of a previously-exported directory.
Returns: A ClassAd containing information about the import operation.
Return type: ClassAd

unexport_jobs(job_spec) → object :

Unexport one or more job clusters that were previously exported from the queue.

Parameters: job_spec (list[str] or str or ExprTree) – The job specification. It can either be a list of job IDs or a string specifying a constraint. Only jobs matching this description will be acted upon.
Returns: A ClassAd containing information about the unexport operation.
Return type: ClassAd

class htcondor.JobAction

An enumeration describing the actions that may be performed on a job in queue.

The values of the enumeration are:

Hold: Put a job on hold, vacating a running job if necessary. A job will stay in the hold state until explicitly acted upon by the admin or owner.

Release: Release a job from the hold state, returning it to Idle.

Suspend: Suspend the processes of a running job (on Unix platforms, this triggers a SIGSTOP). The job’s processes stay in memory but no longer get scheduled on the CPU.

Continue: Continue a suspended jobs (on Unix, SIGCONT). The processes in a previously suspended job will be scheduled to get CPU time again.

Remove: Remove a job from the Schedd’s queue, cleaning it up first on the remote host (if running). This requires the remote host to acknowledge it has successfully vacated the job, meaning Remove may not be instantaneous.

RemoveX: Immediately remove a job from the schedd queue, even if it means the job is left running on the remote resource.

Vacate: Cause a running job to be killed on the remote resource and return to idle state. With Vacate, jobs may be given significant time to cleanly shut down.

VacateFast: Vacate a running job as quickly as possible, without providing time for the job to cleanly terminate.

class htcondor.TransactionFlags

Enumerated flags affecting the characteristics of a transaction.

The values of the enumeration are:

NonDurable: Non-durable transactions are changes that may be lost when the condor_schedd crashes. NonDurable is used for performance, as it eliminates extra fsync() calls.

SetDirty: This marks the changed ClassAds as dirty, causing an update notification to be sent to the condor_shadow and the condor_gridmanager, if they are managing the job.

ShouldLog: Causes any changes to the job queue to be logged in the relevant job event log.

class htcondor.QueryOpts

Enumerated flags sent to the condor_schedd during a query to alter its behavior.

The values of the enumeration are:

Default: Queries should use default behaviors, and return jobs for all users.

AutoCluster: Instead of returning job ads, return an ad per auto-cluster.

GroupBy: Instead of returning job ads, return an ad for each unique combination of values for the attributes in the projection. Similar to AutoCluster, but using the projection as the significant attributes for auto-clustering.

DefaultMyJobsOnly: Queries should use all default behaviors, and return jobs only for the current user.

SummaryOnly: Instead of returning job ads, return only the final summary ad.

IncludeClusterAd: Query should return raw cluster ads as well as job ads if the cluster ads match the query constraint.

class htcondor.BlockingMode

An enumeration that controls the behavior of query iterators once they are out of data.

The values of the enumeration are:

Blocking: Sets the iterator to block until more data is available.

NonBlocking: Sets the iterator to return immediately if additional data is not available.

class htcondor.HistoryIterator: An iterator over ads in the history produced by Schedd.history().

class htcondor.QueryIterator

An iterator class for managing results of the Schedd.query() and Schedd.xquery() methods.

nextAdsNonBlocking() → list :

Retrieve as many ads are available to the iterator object.

If no ads are available, returns an empty list. Does not throw an exception if no ads are available or the iterator is finished.

Returns: Zero-or-more job ads.
Return type: list[ClassAd]

tag() → str :

Retrieve the tag associated with this iterator; when using the poll() method, this is useful to distinguish multiple iterators.

Returns: The query’s tag.

done() → bool :

Returns: True if the iterator is finished; False otherwise.
Return type: bool

watch() → int :

Returns an inotify-based file descriptor; if this descriptor is given to a select() instance, select will indicate this file descriptor is ready to read whenever there are more jobs ready on the iterator.

If inotify is not available on this platform, this will return -1.

Returns: A file descriptor associated with this query.
Return type: int

htcondor.poll(queries, timeout_ms=20000) → BulkQueryIterator :

Wait on the results of multiple query iterators.

This function returns an iterator which yields the next ready query iterator. The returned iterator stops when all results have been consumed for all iterators.

Parameters: active_queries (list[QueryIterator]) – Query iterators as returned by xquery().
Returns: An iterator producing the ready QueryIterator.
Return type: BulkQueryIterator

class htcondor.BulkQueryIterator

Returned by poll(), this iterator produces a sequence of QueryIterator objects that have ads ready to be read in a non-blocking manner.

Once there are no additional available iterators, poll() must be called again.

class htcondor.JobStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

An enumeration of HTCondor job status values.

IDLE

RUNNING

REMOVED

COMPLETED

HELD

TRANSFERRING_OUTPUT

SUSPENDED

Submitting Jobs

class htcondor.Submit

An object representing a job submit description. It uses the same submit language as condor_submit.

The submit description contains key = value pairs and implements the python dictionary protocol, including the get, setdefault, update, keys, items, and values methods.

object __init__(tuple args, dict kwds) :

param input
Submit descriptors as key = value pairs in a dictionary, or as keyword arguments, or as a string containing the text of a submit file. For example, these calls all produce identical submit descriptions:
from_file = htcondor.Submit(
    """
    executable = /bin/sleep
    arguments = 5s
    My.CustomAttribute = "foobar"
    """
)

# we need to quote the string "foobar" correctly
from_dict = htcondor.Submit({
    "executable": "/bin/sleep",
    "arguments": "5s",
    "My.CustomAttribute": classad.quote("foobar"),
})

# the **{} is a trick to get a keyword argument that contains a .
from_kwargs = htcondor.Submit(
    executable = "/bin/sleep",
    arguments = "5s",
    **{
        "My.CustomAttribute": classad.quote("foobar"),
    }
)
If a string is used, it may include a single condor_submit QUEUE statement. The arguments to the QUEUE statement will be stored in the QArgs member of this class and used when Submit.queue() or Submit.queue_with_itemdata() are called. If omitted, the submit description is initially empty.
type input

dict or str

queue(txn, count=0, ad_results=None) → int :

Submit the current object to a remote queue.

Parameters

txn (Transaction) – An active transaction object (see Schedd.transaction()).
count (int) – The number of jobs to create (defaults to 0). If not specified, or a value of 0 is given the QArgs member of this class is used to determine the number of procs to submit. If no QArgs were specified, one job is submitted.
ad_results – A list to receive the ClassAd resulting from this submit. As with Schedd.submit(), this is often used to later spool the input files.

Returns

The ClusterID of the submitted job(s).

Return type

int

Raises

RuntimeError – if the submission fails.

queue_with_itemdata(txn, count=1, itemdata=None, spool=False) → SubmitResult :

Submit the current object to a remote queue.

Parameters

txn (Transaction) – An active transaction object (see Schedd.transaction()).
count (int) – A queue count for each item from the iterator, defaults to 1.
from – an iterator of strings or dictionaries containing the itemdata for each job as in queue in or queue from.
spool (bool) – Modify the job ClassAds to indicate that it should wait for input before starting. defaults to false.

Returns

a SubmitResult, containing the cluster ID, cluster ClassAd and range of Job ids Cluster ID of the submitted job(s).

Return type

SubmitResult

Raises

RuntimeError – if the submission fails.

expand(attr) → str :

Expand all macros for the given attribute.

Parameters: attr (str) – The name of the relevant attribute.
Returns: The value of the given attribute; all macros are expanded.
Return type: str

jobs(count=0, itemdata=None, clusterid=1, procid=0, qdate=0, owner='') → SubmitJobsIterator :

Turn the current object into a sequence of simulated job ClassAds

Parameters

count (int) – the queue count for each item in the from list, defaults to 1
from – a iterator of strings or dictionaries containing the itemdata for each job e.g. ‘queue in’ or ‘queue from’
clusterid (int) – the value to use for ClusterId when making job ads, defaults to 1
procid (int) – the initial value for ProcId when making job ads, defaults to 0
qdate (str) – a UNIX timestamp value for the QDATE attribute of the jobs, 0 means use the current time.
owner (str) – a string value for the Owner attribute of the job

Returns

An iterator for the resulting job ads.

Raises

RuntimeError – if valid job ads cannot be made

procs(count=0, itemdata=None, clusterid=1, procid=0, qdate=0, owner='') → SubmitJobsIterator :

Turn the current object into a sequence of simulated job proc ClassAds. The first ClassAd will be the cluster ad plus a ProcId attribute

Parameters

count (int) – the queue count for each item in the from list, defaults to 1
from – a iterator of strings or dictionaries containing the foreach data e.g. ‘queue in’ or ‘queue from’
clusterid (int) – the value to use for ClusterId when making job ads, defaults to 1
procid (int) – the initial value for ProcId when making job ads, defaults to 0
qdate (str) – a UNIX timestamp value for the QDATE attribute of the jobs, 0 means use the current time.
owner (str) – a string value for the Owner attribute of the job

Returns

An iterator for the resulting job ads.

Raises

RuntimeError – if valid job ads cannot be made

itemdata(qargs='') → QueueItemsIterator :

Create an iterator over itemdata derived from a queue statement.

For example itemdata("matching *.dat") would return an iterator of filenames that end in .dat from the current directory. This is the same iterator used by condor_submit when processing QUEUE statements.

Parameters: queue (str) – a submit queue statement, or the arguments to a submit queue statement.
Returns: An iterator for the resulting items

getQArgs() → str :: Returns arguments specified in the QUEUE statement passed to the constructor. These are the arguments that will be used by the Submit.queue() and Submit.queue_with_itemdata() methods if not overridden by arguments to those methods.

setQArgs(args) → None :

Sets the arguments to be used by subsequent calls to the Submit.queue() and Submit.queue_with_itemdata() methods if not overridden by arguments to those methods.

Parameters: args (str) – The arguments to pass to the QUEUE statement.

static from_dag(filename, options={}) → Submit :

Constructs a new Submit that could be used to submit the DAG described by the file found at filename.

This static method essentially does the first half of the work that condor_submit_dag does: it produces the submit description for the DAGMan job that will execute the DAG. However, in addition to writing this submit description to disk, it also produces a Submit object with the same information that can be submitted via the normal Python bindings submit machinery.

Parameters

filename (str) – The path to the DAG description file.
options (dict) – Additional arguments to condor_submit_dag. Supports dagman (str), force (bool), schedd-daemon-ad-file (str), schedd-address-file (str), AlwaysRunPost (bool), maxidle (int), maxjobs (int), MaxPre (int), MaxPost (int), UseDagDir (bool), debug (int), outfile_dir (str), config (str), batch-name (str), AutoRescue (bool), DoRescueFrom (int), AllowVersionMismatch (bool), do_recurse (bool), update_submit (bool), import_env (bool), DumpRescue (bool), valgrind (bool), priority (int), suppress_notification (bool), DoRecov (bool)

Returns

A Submit description for the DAG described in filename

Return type

Submit

setSubmitMethod(method_value=- 1, allow_reserved_values=False) → None :

Sets the Job Ad attribute JobSubmitMethod to passed over number. method_value is recommended to be set to a value of 100 or greater to avoid confusion to pre-set values. Negative numbers will result in JobSubmitMethod to not be defined in the Job Ad. If wanted, any number can be set by passing True to allow_reserved_values. This allows any positive number to be set to JobSubmitMethod. This includes all reserved numbers. Note~ Setting of JobSubmitMethod must occur before job is submitted to Schedd.

Parameters

method_value (int) – Value set to JobSubmitMethod.
allow_reserved_values (bool) – Boolean that allows any number to be set to JobSubmitMethod.

getSubmitMethod() → int :

Returns: JobSubmitMethod attribute value. See table or use condor_q -help Submit for values.
Return type: int

class htcondor.QueueItemsIterator: An iterator over itemdata produced by Submit.itemdata().

class htcondor.SubmitResult

cluster() → int :

Returns: the ClusterID of the submitted jobs.
Return type: int

clusterad() → ClassAd :

Returns: the cluster Ad of the submitted jobs.
Return type: classad.ClassAd

first_proc() → int :

Returns: the first ProcID of the submitted jobs.
Return type: int

num_procs() → int :

Returns: the number of submitted jobs.
Return type: int

Interacting with Negotiators

class htcondor.Negotiator(ad)

This class provides a query interface to the condor_negotiator. It primarily allows one to query and set various parameters in the fair-share accounting.

Parameters: location_ad (ClassAd or DaemonLocation) – A ClassAd or DaemonLocation describing the condor_negotiator location and version. If omitted, the default pool negotiator is assumed.

deleteUser(user) → None :

Delete all records of a user from the Negotiator’s fair-share accounting.

Parameters: user (str) – A fully-qualified user name (USER@DOMAIN).

getPriorities(rollup) → list :

Retrieve the pool accounting information, one per entry. Returns a list of accounting ClassAds.

Parameters: rollup (bool) – Set to True if accounting information, as applied to hierarchical group quotas, should be summed for groups and subgroups.
Returns: A list of accounting ads, one per entity.
Return type: list[ClassAd]

getResourceUsage(user) → list :

Get the resources (slots) used by a specified user.

Parameters: user (str) – A fully-qualified user name (USER@DOMAIN).
Returns: List of ads describing the resources (slots) in use.
Return type: list[ClassAd]

resetAllUsage() → None :: Reset all usage accounting. All known user records in the negotiator are deleted.

resetUsage(user) → None :

Reset all usage accounting of the specified user.

Parameters: user (str) – A fully-qualified user name (USER@DOMAIN).

setBeginUsage(user, value) → None :

Manually set the time that a user begins using the pool.

Parameters

user (str) – A fully-qualified user name (USER@DOMAIN).
value (int) – The Unix timestamp of initial usage.

setCeiling(user, ceiling) → None :

Set the submitter ceiling of a specified user.

Parameters

user (str) – A fully-qualified user name (USER@DOMAIN).
ceiling (float) – The ceiling t be set for the submitter; must be greater-than or equal-to -1.0.

setLastUsage(user, value) → None :

Manually set the time that a user last used the pool.

Parameters

user (str) – A fully-qualified user name (USER@DOMAIN).
value (int) – The Unix timestamp of last usage.

setFactor(user, factor) → None :

Set the priority factor of a specified user.

Parameters

user (str) – A fully-qualified user name (USER@DOMAIN).
factor (float) – The priority factor to be set for the user; must be greater-than or equal-to 1.0.

setPriority(user, prio) → None :

Set the real priority of a specified user.

Parameters

user (str) – A fully-qualified user name (USER@DOMAIN).
prio (float) – The priority to be set for the user; must be greater-than 0.0.

setUsage(user, usage) → None :

Set the accumulated usage of a specified user.

Parameters

user (str) – A fully-qualified user name (USER@DOMAIN).
usage (float) – The usage, in hours, to be set for the user.

Managing Starters and Claims

class htcondor.Startd(ad=None)

A class that represents a Startd.

Parameters: locaton_ad – A ClassAd or DaemonLocation describing the the startd location and version. If omitted, the local startd is assumed.

drainJobs(drain_type=0, on_completion=0, check_expr='true', start_expr='false', reason='by command') → str :

Begin draining jobs from the startd.

Parameters

drain_type (DrainTypes) – How fast to drain the jobs. Defaults to DRAIN_GRACEFUL if not specified.
on_completion (int) – Whether the startd should start accepting jobs again once draining is complete. Otherwise, it will remain in the drained state. Values are 0 for Nothing, 1 for Resume, 2 for Exit, 3 for Restart. Defaults to 0.
check_expr (str or ExprTree) – An expression string that must evaluate to true for all slots for draining to begin. Defaults to 'true'.
start_expr (str or ExprTree) – The expression that the startd should use while draining.
reason (str) – A string describing the reason for draining. defaults to “by command”

Returns

An opaque request ID that can be used to cancel draining via Startd.cancelDrainJobs()

Return type

str

cancelDrainJobs(request_id='') → None :

Cancel a draining request.

Parameters: request_id (str) – Specifies a draining request to cancel. If not specified, all draining requests for this startd are canceled.

class htcondor.DrainTypes

Draining policies that can be sent to a condor_startd.

The values of the enumeration are:

Fast

Graceful

Quick

class htcondor.VacateTypes

Vacate policies that can be sent to a condor_startd.

The values of the enumeration are:

Fast

Graceful

Security Management

class htcondor.Credd(ad=None)

A class for sending Credential commands to a Credd, Schedd or Master.

Parameters: location_ad (ClassAd or DaemonLocation) – A ClassAd or DaemonLocation describing the Credd, Schedd or Master location. If omitted, the local schedd is assumed.

add_password(password, user='') → None :

Store the password in the Credd for the current user (or for the given user).

Parameters

password (str) – The password.
user (str) – Which user to store the credential for (defaults to the current user).

delete_password(user='') → None :

Delete the password in the Credd for the current user (or for the given user).

Parameters: user (str) – Which user to store the credential for (defaults to the current user).

query_password(user='') → bool :

Check to see if the current user (or the given user) has a password stored in the Credd.

Parameters: user (str) – Which user to store the credential for (defaults to the current user).
Returns: bool

add_user_cred(credtype, credential, user='') → None :

Store a credential in the Credd for the current user (or for the given user).

Parameters

credtype (CredTypes) – The type of credential to store.
credential (bytes) – The credential to store.
user (str) – Which user to store the credential for (defaults to the current user).

delete_user_cred(credtype, user='') → None :

Delete a credential of the given credtype for the current user (or for the given user).

Parameters

credtype (CredTypes) – The type of credential to delete.
user (str) – Which user to store the credential for (defaults to the current user).

query_user_cred(credtype, user='') → int :

Query whether the current user (or the given user) has a credential of the given type stored.

Parameters

credtype (CredTypes) – The type of credential to query for.
user (str) – Which user to store the credential for (defaults to the current user).

Returns

The time that the user credential was last updated, or None if there is no credential

add_user_service_cred(credtype, credential, service, handle='', user='') → None :

Store a credential in the Credd for the current user, or for the given user.

To specify multiple credential for the same service (e.g., you want to transfer files from two different accounts that are on the same service), give each a unique handle.

Parameters

credtype (CredTypes) – The type of credential to store.
credential (bytes) – The credential to store.
service (str) – The service name.
handle (str) – Optional service handle (defaults to no handle).
user (str) – Which user to store the credential for (defaults to the current user).

delete_user_service_cred(credtype, service, handle='', user='') → None :

Delete a credential of the given credtype for service service for the current user (or for the given user).

Parameters

credtype (CredTypes) – The type of credential to delete.
service (str) – The service name.
handle (str) – Optional service handle (defaults to no handle).
user (str) – Which user to store the credential for (defaults to the current user).

query_user_service_cred(credtype, service, handle='', user='') → CredStatus :

Query whether the current user (or the given user) has a credential of the given credtype stored.

Parameters

credtype (CredTypes) – The type of credential to check storage for.
service (str) – The service name.
handle (str) – Optional service handle (defaults to no handle).
user (str) – Which user to store the credential for (defaults to the current user).

Returns

CredStatus

check_user_service_creds(credtype, services, user='') → CredCheck :

Check to see if the current user (or the given user) has a given set of service credentials, and if any credentials are missing, create a temporary URL that can be used to acquire the missing service credentials.

Parameters

credtype (CredTypes) – The type of credentials to check for.
services (List[classad.ClassAd]) – The list of services that are needed.
user (str) – Which user to store the credential for (defaults to the current user).

Returns

CredCheck

class htcondor.CredTypes

The types of credentials that can be managed by a condor_credd.

The values of the enumeration are:

Password

Kerberos

OAuth

class htcondor.CredCheck

class htcondor.CredStatus

class htcondor.SecMan(arg1)

A class that represents the internal HTCondor security state.

If a security session becomes invalid, for example, because the remote daemon restarts, reuses the same port, and the client continues to use the session, then all future commands will fail with strange connection errors. This is the only mechanism to invalidate in-memory sessions.

The SecMan can also behave as a context manager; when created, the object can be used to set temporary security configurations that only last during the lifetime of the security object.

invalidateAllSessions() → None :: Invalidate all security sessions. Any future connections to a daemon will cause a new security session to be created.

ping(ad, command='DC_NOP') → ClassAd :

Perform a test authorization against a remote daemon for a given command.

Parameters

ad (str or ClassAd) – The ClassAd of the daemon as returned by Collector.locate(); alternately, the sinful string can be given directly as the first parameter.
command – The DaemonCore command to try; if not given, 'DC_NOP' will be used.

Returns

An ad describing the results of the test security negotiation.

Return type

getCommandString(command_int) → str :

Return the string name corresponding to a given integer command.

Parameters: command_int (int) – The integer command to get the string name of.

setConfig(key, value) → None :

Set a temporary configuration variable; this will be kept for all security sessions in this thread for as long as the SecMan object is alive.

Parameters

key (str) – Configuration key to set.
value (str) – Temporary value to set.

setPoolPassword(new_pass) → None :

Set the pool password.

Parameters: new_pass (str) – Updated pool password to use for new security negotiations.

setTag(tag) → None :

Set the authentication context tag for the current thread.

All security sessions negotiated with the same tag will only be utilized when that tag is active.

For example, if thread A has a tag set to 'Joe' and thread B has a tag set to 'Jane', then all security sessions negotiated for thread A will not be used for thread B.

Parameters: tag (str) – New tag to set.

setToken(token) → None :

Set the token used for auth.

Parameters: token (Token) – The object representing the token contents

class htcondor.Token(contents)

A class representing a generated HTCondor authentication token.

Parameters: contents (str) – The contents of the token.

write(tokenfile=None) → None :

Write the contents of the token into the appropriate token directory on disk.

Parameters: tokenfile – Filename inside the user token directory where the token will be written.

class htcondor.TokenRequest(identity='', bounding_set=None, lifetime=- 1)

A class representing a request for a HTCondor authentication token.

Parameters

identity (str) – Requested identity from the remote daemon (the empty string implies condor user).
bounding_set (list[str]) – A list of authorizations that the token is restricted to.
lifetime (int) – Requested lifetime, in seconds, that the token will be valid for.

done() → bool :

Check to see if the token request has completed.

Returns: True if the request is complete; False otherwise. May throw an exception.
Return type: bool

property request_id: The ID of the request at the remote daemon.

result(timeout=0) → Token :

Return the result of the token request. Will block until the token request is approved or the timeout is hit (a timeoute of 0, the default, indicates this method may block indefinitely).

Returns: The token resulting from this request.
Return type: Token

submit(ad=None) → None :

Submit the token request to a remote daemon.

Parameters: ad (ClassAd) – ClassAd describing the location of the remote daemon.

Reading Job Events

The following is a complete example of submitting a job and waiting (forever) for it to finish. The next example implements a time-out.

#!/usr/bin/env python3

import htcondor

# Create a job description.  It _must_ set `log` to create a job event log.
logFileName = "sleep.log"
submit = htcondor.Submit(
    f"""
    executable = /bin/sleep
    transfer_executable = false
    arguments = 5

    log = {logFileName}
    """
)

# Submit the job description, creating the job.
result = htcondor.Schedd().submit(submit, count=1)
clusterID = result.cluster()

# Wait (forever) for the job to finish.
jel = htcondor.JobEventLog(logFileName)
for event in jel.events(stop_after=None):
    # HTCondor appends to job event logs by default, so if you run
    # this example more than once, there will be more than one job
    # in the log.  Make sure we have the right one.
    if event.cluster != clusterID or event.proc != 0:
        continue

    if event.type == htcondor.JobEventType.JOB_TERMINATED:
        if(event["TerminatedNormally"]):
            print(f"Job terminated normally with return value {event['ReturnValue']}.")
        else:
            print(f"Job terminated on signal {event['TerminatedBySignal']}.");
        break

    if event.type in { htcondor.JobEventType.JOB_ABORTED,
                       htcondor.JobEventType.JOB_HELD,
                       htcondor.JobEventType.CLUSTER_REMOVE }:
        print("Job aborted, held, or removed.")
        break

    # We expect to see the first three events in this list, and allow
    # don't consider the others to be terminal.
    if event.type not in { htcondor.JobEventType.SUBMIT,
                           htcondor.JobEventType.EXECUTE,
                           htcondor.JobEventType.IMAGE_SIZE,
                           htcondor.JobEventType.JOB_EVICTED,
                           htcondor.JobEventType.JOB_SUSPENDED,
                           htcondor.JobEventType.JOB_UNSUSPENDED }:
        print(f"Unexpected job event: {event.type}!");
        break

The following example includes a deadline for the job to finish. To make it quick to run the example, the deadline is only ten seconds; real jobs will almost always take considerably longer. You can change arguments = 20 to arguments = 5 to verify that this example correctly detects the job finishing. For the same reason, we check once a second to see if the deadline has expired. In practice, you should check much less frequently, depending on how quickly your script needs to react and how long you expect the job to last. In most cases, even once a minute is more frequent than necessary or appropriate on shared resources; every five minutes is better.

#!/usr/bin/env python3

import time
import htcondor

# Create a job description.  It _must_ set `log` to create a job event log.
logFileName = "sleep.log"
submit = htcondor.Submit(
    f"""
    executable = /bin/sleep
    transfer_executable = false
    arguments = 20

    log = {logFileName}
    """
)

# Submit the job description, creating the job.
result = htcondor.Schedd().submit(submit, count=1)
clusterID = result.cluster()

def waitForJob(deadline):
    jel = htcondor.JobEventLog(logFileName)
    while time.time() < deadline:
        # In real code, this should be more like stop_after=300; see above.
        for event in jel.events(stop_after=1):
            # HTCondor appends to job event logs by default, so if you run
            # this example more than once, there will be more than one job
            # in the log.  Make sure we have the right one.
            if event.cluster != clusterID or event.proc != 0:
                continue
            if event.type == htcondor.JobEventType.JOB_TERMINATED:
                if(event["TerminatedNormally"]):
                    print(f"Job terminated normally with return value {event['ReturnValue']}.")
                else:
                    print(f"Job terminated on signal {event['TerminatedBySignal']}.");
                return True
            if event.type in { htcondor.JobEventType.JOB_ABORTED,
                               htcondor.JobEventType.JOB_HELD,
                               htcondor.JobEventType.CLUSTER_REMOVE }:
                print("Job aborted, held, or removed.")
                return True
            # We expect to see the first three events in this list, and allow
            # don't consider the others to be terminal.
            if event.type not in { htcondor.JobEventType.SUBMIT,
                                   htcondor.JobEventType.EXECUTE,
                                   htcondor.JobEventType.IMAGE_SIZE,
                                   htcondor.JobEventType.JOB_EVICTED,
                                   htcondor.JobEventType.JOB_SUSPENDED,
                                   htcondor.JobEventType.JOB_UNSUSPENDED }:
                print(f"Unexpected job event: {event.type}!");
                return True
    else:
        print("Deadline expired.")
        return False

# Wait no more than 10 seconds for the job finish.
waitForJob(time.time() + 10);

Note that which job events are terminal, expected, or allowed may vary somewhat from job to job; for instance, it’s possible to submit a job which releases itself from certain hold conditions.

class htcondor.JobEventLog(filename)

Reads user job event logs from filename.

By default, it waits for new events, but it may be used to poll for them:

import htcondor

jel = htcondor.JobEventLog("file.log")

# Read all currently-available events without blocking.
for event in jel.events(stop_after=0):
    print(event)

print("We found the the end of file")

A pickled JobEventLog resumes iterating over events where it left off if and only if, after being unpickled, the job event log file is identical except for appended events.

Parameters: filename (str) – A file containing a user job event log.

events(stop_after) → object :

Return an iterator over JobEvent objects from the filename given in the constructor.

Parameters: stop_after (int) – After how many seconds should the iterator stop waiting for new events? If None (the default), wait forever. If 0, never wait.

close() → None :: Closes any open underlying file. This object will no longer iterate.

class htcondor.JobEvent

Represents a single job event from the job event log. Use JobEventLog to get an iterator over the job events from a file.

Because all events have type, cluster, proc, and timestamp, those are accessed via attributes (see below).

The rest of the information in the JobEvent can be accessed by key. JobEvent behaves like a read-only Python dict, with get, keys, items, and values methods, and supports len and in (if "attribute" in job_event, for example).

Attention

Although the attribute type is a JobEventType type, when acting as dictionary, a JobEvent object returns types as if it were a ClassAd, so comparisons to enumerated values must use the == operator. (No current event type has ExprTree values.)

type

The event type.

Return type: JobEventType

cluster

The clusterid of the job the event is for.

Return type: int

proc

The procid of the job the event is for.

Return type: int

timestamp

The timestamp of the event.

Return type: str

get(key, default=None) → object :: As dict.get().

keys() → list :: As dict.keys().

values() → list :: As dict.values().

items() → list :: As dict.items().

class htcondor.JobEventType

The type event of a user log event; corresponds to ULogEventNumber in the C++ source.

The values of the enumeration are:

SUBMIT

EXECUTE

EXECUTABLE_ERROR

CHECKPOINTED

JOB_EVICTED

JOB_TERMINATED

IMAGE_SIZE

SHADOW_EXCEPTION

GENERIC

JOB_ABORTED

JOB_SUSPENDED

JOB_UNSUSPENDED

JOB_HELD

JOB_RELEASED

NODE_EXECUTE

NODE_TERMINATED

POST_SCRIPT_TERMINATED

GLOBUS_SUBMIT

GLOBUS_SUBMIT_FAILED

GLOBUS_RESOURCE_UP

GLOBUS_RESOURCE_DOWN

REMOTE_ERROR

JOB_DISCONNECTED

JOB_RECONNECTED

JOB_RECONNECT_FAILED

GRID_RESOURCE_UP

GRID_RESOURCE_DOWN

GRID_SUBMIT

JOB_AD_INFORMATION

JOB_STATUS_UNKNOWN

JOB_STATUS_KNOWN

JOB_STAGE_IN

JOB_STAGE_OUT

ATTRIBUTE_UPDATE

PRESKIP

CLUSTER_SUBMIT

CLUSTER_REMOVE

FACTORY_PAUSED

FACTORY_RESUMED

NONE

FILE_TRANSFER

RESERVE_SPACE

RELEASE_SPACE

FILE_COMPLETE

FILE_USED

FILE_REMOVED

class htcondor.FileTransferEventType

The event type for file transfer events; corresponds to FileTransferEventType in the C++ source.

The values of the enumeration are:

IN_QUEUED

IN_STARTED

IN_FINISHED

OUT_QUEUED

OUT_STARTED

OUT_FINISHED

HTCondor Configuration

htcondor.param = <htcondor.htcondor._Param object>

Provides dictionary-like access the HTCondor configuration.

An instance of _Param. Upon importing the htcondor module, the HTCondor configuration files are parsed and populate this dictionary-like object.

htcondor.reload_config() → None :: Reload the HTCondor configuration from disk.

class htcondor._Param

A dictionary-like object for the local HTCondor configuration; the keys and values of this object are the keys and values of the HTCondor configuration.

The get, setdefault, update, keys, items, and values methods of this class have the same semantics as a Python dictionary.

Writing to a _Param object will update the in-memory HTCondor configuration.

class htcondor.RemoteParam(ad)

The RemoteParam class provides a dictionary-like interface to the configuration of an HTCondor daemon. The get, setdefault, update, keys, items, and values methods of this class have the same semantics as a Python dictionary.

Parameters: ad (ClassAd) – An ad containing the location of the remote daemon.

refresh() → None :: Rebuilds the dictionary based on the current configuration of the daemon.

htcondor.platform() → str :: Returns the platform of HTCondor this module is running on.

htcondor.version() → str :: Returns the version of HTCondor this module is linked against.

HTCondor Logging

htcondor.enable_debug() → None :: Enable debugging output from HTCondor, where output is sent to stderr. The logging level is controlled by the TOOL_DEBUG parameter.

htcondor.enable_log() → None :: Enable debugging output from HTCondor, where output is sent to a file. The log level is controlled by the parameter TOOL_DEBUG, and the file used is controlled by TOOL_LOG.

htcondor.log(level, msg) → None :

Log a message using the HTCondor logging subsystem.

Parameters

level (LogLevel) – The log category and formatting indicator. Multiple LogLevel enum attributes may be OR’d together.
msg (str) – A message to log.

class htcondor.LogLevel

The log level attribute to use with log(). Note that HTCondor mixes both a class (debug, network, all) and the header format (Timestamp, PID, NoHeader) within this enumeration.

The values of the enumeration are:

Always

Audit

Config

DaemonCore

Error

FullDebug

Hostname

Job

Machine

Network

NoHeader

PID

Priv

Protocol

Security

Status

SubSecond

Terse

Timestamp

Verbose

Esoteric Functionality

htcondor.send_command(ad, dc, target) → None :

Send a command to an HTCondor daemon specified by a location ClassAd.

Parameters

ad (ClassAd) – Specifies the location of the daemon (typically, found by using Collector.locate()).
dc (DaemonCommands) – A command type
target (str) – An additional command to send to a daemon. Some commands require additional arguments; for example, sending DaemonOff to a condor_master requires one to specify which subsystem to turn off.

class htcondor.DaemonCommands

An enumeration of various state-changing commands that can be sent to a HTCondor daemon using send_command().

The values of the enumeration are:

DaemonOn

DaemonOff

DaemonOffFast

DaemonOffPeaceful

DaemonsOn

DaemonsOff

DaemonsOffFast

DaemonsOffPeaceful

OffFast

OffForce

OffGraceful

OffPeaceful

Reconfig

Restart

RestartPeacful

SetForceShutdown

SetPeacefulShutdown

htcondor.send_alive([ ad=None, pid=None, timeout=None) → None :

Send a keep alive message to an HTCondor daemon.

This is used when the python process is run as a child daemon under the condor_master.

Parameters

ad (ClassAd) – A ClassAd specifying the location of the daemon. This ad is typically found by using Collector.locate().
pid (int) – The process identifier for the keep alive. The default value of None uses the value from os.getpid().
timeout (int) – The number of seconds that this keep alive is valid. If a new keep alive is not received by the condor_master in time, then the process will be terminated. The default value is controlled by configuration variable NOT_RESPONDING_TIMEOUT.

htcondor.set_subsystem(subsystem, type=htcondor.htcondor.SubsystemType(15)) → None :

Set the subsystem name for the object.

The subsystem is primarily used for the parsing of the HTCondor configuration file.

Parameters

name (str) – The subsystem name.
daemon_type (SubsystemType) – The HTCondor daemon type. The default value of Auto infers the type from the name parameter.

class htcondor.SubsystemType

An enumeration of known subsystem names.

The values of the enumeration are:

Collector

Daemon

Dagman

GAHP

Job

Master

Negotiator

Schedd

Shadow

SharedPort

Startd

Starter

Submit

Tool

Exceptions

For backwards-compatibility, the exceptions in this module inherit from the built-in exceptions raised in earlier (pre-v8.9.9) versions.

class htcondor.HTCondorException: Never raised. The parent class of all exceptions raised by this module.

class htcondor.HTCondorEnumError: Raised when a value must be in an enumeration, but isn’t.

class htcondor.HTCondorInternalError: Raised when HTCondor encounters an internal error.

class htcondor.HTCondorIOError: Raised instead of IOError for backwards compatibility.

class htcondor.HTCondorLocateError: Raised when HTCondor cannot locate a daemon.

class htcondor.HTCondorReplyError: Raised when HTCondor received an invalid reply from a daemon, or the daemon’s reply indicated that it encountered an error.

class htcondor.HTCondorTypeError: Raised instead of TypeError for backwards compatibility.

class htcondor.HTCondorValueError: Raised instead of ValueError for backwards compatibility.

Thread Safety

Most of the htcondor module is protected by a lock that prevents multiple threads from executing locked functions at the same time. When two threads both want to call locked functions or methods, they will wait in line to execute them one at a time (the ordering between threads is not guaranteed beyond “first come first serve”). Examples of locked functions include: Schedd.query(), Submit.queue(), and Schedd.edit().

Threads that are not trying to execute locked htcondor functions will be allowed to proceed normally.

This locking may cause unexpected slowdowns when using htcondor from multiple threads simultaneously.

`htcondor.htchirp` API Reference

htcondor.htchirp is a Python Chirp client compatible with the condor_starter Chirp proxy server. It is intended for use inside a running HTCondor job to access files on the submit machine or to query and modify job ClassAd attributes. Files can be read, written, or removed. Job attributes can be read, and most attributes can be updated.

Jobs that use htcondor.htchirp module must have the attribute WantIOProxy set to true in the job ClassAd (My.WantIOProxy = true in the submit description). htcondor.htchirp only works for jobs run in the vanilla, paralllel, and java universes.

htcondor.htchirp provides two objects for interacting with the condor_starter Chirp proxy server, HTChirp and condor_chirp().

We recommend using HTChirp as a context manager, which automatically handles openining and closing the connection to the condor_starter Chirp proxy server:

from htcondor.htchirp import HTChirp

with HTChirp() as chirp:
    # inside this block, the connection is open
    i = chirp.get_job_attr("IterationNum")
    chirp.set_job_attr("IterationNum") = i + 1

The connection may be manually opened and closed using HTChirp.connect() and HTChirp.disconnect().

condor_chirp() is a wrapper around HTChirp that takes a string containing a condor_chirp command (with arguments) and returns the value from the relevant HTChirp method.

class htcondor.htchirp.HTChirp(host=None, port=None, auth=['cookie'], cookie=None, timeout=10)

Chirp client for HTCondor

A Chirp client compatible with the HTCondor Chirp implementation.

If the host and port of a Chirp server are not specified, you are assumed to be running in a HTCondor job with $_CONDOR_CHIRP_CONFIG that contains the host, port, and cookie for connecting to the embedded chirp proxy.

Parameters

host – the hostname or ip of the Chirp server
port – the port of the Chirp server
auth – a list of authentication methods to try
cookie – the cookie string, if trying cookie authentication
timeout – socket timeout, in seconds

connect(auth_method=None)

Connect to and authenticate with the Chirp server

Parameters: auth_method – If set, try the specific authentication method

is_connected(): Check if Chirp client is connected.

disconnect(): Close connection with the Chirp server

fetch(remote_file, local_file)

Copy a file from the submit machine to the execute machine.

Parameters

remote_file – Path to file to be sent from the submit machine
local_file – Path to file to be written to on the execute machine

Returns

Bytes written

put(local_file, remote_file, flags='wct', mode=None)

Copy a file from the execute machine to the submit machine.

Specifying flags other than ‘wct’ (i.e. ‘create or truncate file’) when putting large files is not recommended as the entire file must be read into memory.

To put individual bytes into a file on the submit machine instead of an entire file, see the write() method.

Parameters

local_file – Path to file to be sent from the execute machine
remote_file – Path to file to be written to on the submit machine
flags – File open modes (one or more of ‘rwatcx’) [default: ‘wct’]
mode – Permission mode to set [default: 0777]

Returns

Size of written file

remove(remote_file)

Remove a file from the submit machine.

Parameters: remote_file – Path to file on the submit machine

get_job_attr(job_attribute)

Get the value of a job ClassAd attribute.

Parameters: job_attribute – The job attribute to query
Returns: The value of the job attribute as a string

set_job_attr(job_attribute, attribute_value)

Set the value of a job ClassAd attribute.

Parameters

job_attribute – The job attribute to set
attribute_value – The job attribute’s new value

get_job_attr_delayed(job_attribute)

Get the value of a job ClassAd attribute from the local Starter.

This may differ from the value in the Schedd.

Parameters: job_attribute – The job attribute to query
Returns: The value of the job attribute as a string

set_job_attr_delayed(job_attribute, attribute_value)

Set the value of a job ClassAd attribute.

This variant of set_job_attr will not push the update immediately, but rather as a non-durable update during the next communication between starter and shadow.

Parameters

job_attribute – The job attribute to set
attribute_value – The job attribute’s new value

ulog(text)

Log a generic string to the job log.

Parameters: text – String to log

phase(phasestring)

Tell HTCondor that the job is changing phases.

Parameters: phasestring – New phase

read(remote_path, length, offset=None, stride_length=None, stride_skip=None)

Read up to ‘length’ bytes from a file on the remote machine.

Optionally, start at an offset and/or retrieve data in strides.

Parameters

remote_path – Path to file
length – Number of bytes to read
offset – Number of bytes to offset from beginning of file
stride_length – Number of bytes to read per stride
stride_skip – Number of bytes to skip per stride

Returns

Data read from file

write(data, remote_path, flags='w', mode=None, length=None, offset=None, stride_length=None, stride_skip=None)

Write bytes to a file on the remote matchine.

Optionally, specify the number of bytes to write, start at an offset, and/or write data in strides.

Parameters

data – Bytes to write
remote_path – Path to file
flags – File open modes (one or more of ‘rwatcx’) [default: ‘w’]
mode – Permission mode to set [default: 0777]
length – Number of bytes to write [default: len(data)]
offset – Number of bytes to offset from beginning of file
stride_length – Number of bytes to write per stride
stride_skip – Number of bytes to skip per stride

Returns

Number of bytes written

rename(old_path, new_path)

Rename (move) a file on the remote machine.

Parameters

old_path – Path to file to be renamed
new_path – Path to new file name

unlink(remote_file)

Delete a file on the remote machine.

Parameters: remote_file – Path to file

rmdir(remote_path, recursive=False)

Delete a directory on the remote machine.

The directory must be empty unless recursive is set to True.

Parameters

remote_path – Path to directory
recursive – If set to True, recursively delete remote_path

rmall(remote_path)

Recursively delete an entire directory on the remote machine.

Parameters: remote_path – Path to directory

mkdir(remote_path, mode=None)

Create a new directory on the remote machine.

Parameters

remote_path – Path to new directory
mode – Permission mode to set [default: 0777]

getfile(remote_file, local_file)

Retrieve an entire file efficiently from the remote machine.

Parameters

remote_file – Path to file to be sent from remote machine
local_file – Path to file to be written to on local machine

Returns

Bytes written

putfile(local_file, remote_file, mode=None)

Store an entire file efficiently to the remote machine.

This method will create or overwrite the file on the remote machine. If you want to append to a file, use the write() method.

Parameters

local_file – Path to file to be sent from local machine
remote_file – Path to file to be written to on remote machine
mode – Permission mode to set [default: 0777]

Returns

Size of written file

getdir(remote_path, stat_dict=False)

List a directory on the remote machine.

Parameters

remote_path – Path to directory
stat_dict – If set to True, return a dict of file metadata

Returns

List of files, unless stat_dict is True

getlongdir(remote_path)

List a directory and all its file metadata on the remote machine.

Parameters: remote_path – Path to directory
Returns: A dict of file metadata

whoami()

Get the user’s current identity with respect to this server.

Returns: The user’s identity

whoareyou(remote_host)

Get the server’s identity with respect to the remote host.

Parameters: remote_host – Remote host
Returns: The server’s identity

link(old_path, new_path, symbolic=False)

Create a link on the remote machine.

Parameters

old_path – File path to link from on the remote machine
new_path – File path to link to on the remote machine
symbolic – If set to True, use a symbolic link

symlink(old_path, new_path)

Create a symbolic link on the remote machine.

Parameters

old_path – File path to symlink from on the remote machine
new_path – File path to symlink to on the remote machine

readlink(remote_path)

Read the contents of a symbolic link.

Parameters: remote_path – File path on the remote machine
Returns: Contents of the link

stat(remote_path)

Get metadata for file on the remote machine.

If remote_path is a symbolic link, examine its target.

Parameters: remote_path – Path to file
Returns: Dict of file metadata

lstat(remote_path)

Get metadata for file on the remote machine.

If remote path is a symbolic link, examine the link.

Parameters: remote_path – Path to file
Returns: Dict of file metadata

statfs(remote_path)

Get metadata for a file system on the remote machine.

Parameters: remote_path – Path to examine
Returns: Dict of filesystem metadata

access(remote_path, mode_str)

Check access permissions.

Parameters

remote_path – Path to examine
mode_str – Mode to check (one or more of ‘frwx’)

Raises

NotAuthorized – If any access mode is not authorized

chmod(remote_path, mode)

Change permission mode of a path on the remote machine.

Parameters

remote_path – Path
mode – Permission mode to set

chown(remote_path, uid, gid)

Change the UID and/or GID of a path on the remote machine.

If remote_path is a symbolic link, change its target.

Parameters

remote_path – Path
uid – UID
gid – GID

lchown(remote_path, uid, gid)

Changes the ownership of a file or directory.

If the path is a symbolic link, change the link.

Parameters

remote_path – Path
uid – UID
gid – GID

truncate(remote_path, length)

Truncates a file on the remote machine to a given number of bytes.

Parameters

remote_path – Path to file
length – Truncated length

utime(remote_path, actime, mtime)

Change the access and modification times of a file on the remote machine.

Parameters

remote_path – Path to file
actime – Access time, in seconds (Unix epoch)
mtime – Modification time, in seconds (Unix epoch)

htcondor.htchirp.condor_chirp(chirp_args, return_exit_code=False)

Call HTChirp methods using condor_chirp-style commands

See https://htcondor.readthedocs.io/en/latest/man-pages/condor_chirp.html for a list of commands, or use a Python interpreter to run htchirp.py --help.

Parameters

chirp_args – List or string of arguments as would be passed to condor_chirp
return_exit_code – If True, format and print return value in condor_chirp-style, and return 0 (success) or 1 (failure) (defaults to False).

Returns

Return value from the HTChirp method called, unless return_exit_code=True (see above).

`htcondor.dags` API Reference

Attention

This is not documentation for DAGMan itself! If you run into DAGMan jargon that isn’t explained here, see DAGMan Workflows.

Creating DAGs

class htcondor.dags.DAG(dagman_config=None, dagman_job_attributes=None, max_jobs_by_category=None, dot_config=None, jobstate_log=None, node_status_file=None)

This object represents the entire DAGMan workflow, including both the execution graph and miscellaneous configuration options.

It contains the individual NodeLayer and SubDAG that are the “logical” nodes in the graph, created by the layer() and subdag() methods respectively.

Parameters

dagman_config (Optional[Mapping[str, Any], None]) – A mapping of DAGMan configuration options.
dagman_job_attributes (Optional[Mapping[str, Any], None]) – A mapping that describes additional HTCondor JobAd attributes for the DAGMan job itself.
max_jobs_by_category (Optional[Mapping[str, int], None]) – A mapping that describes the maximum number of jobs (values) that should be run simultaneously from each category (keys).
dot_config (Optional[DotConfig, None]) – Configuration options for writing a DOT file, as a DotConfig.
jobstate_log (Optional[Path, None]) – The path to the jobstate log. If not given, the jobstate log will not be written.
node_status_file (Optional[NodeStatusFile, None]) – Configuration options for the node status file, as a NodeStatusFile.

describe()

Return a tabular description of the DAG’s structure.

Return type: str

property edges: Iterator[Tuple[Tuple[htcondor.dags.node.BaseNode, htcondor.dags.node.BaseNode], htcondor.dags.edges.BaseEdge]]

Iterate over ((parent, child), edge) tuples, for every edge in the graph.

Return type: Iterator[Tuple[Tuple[BaseNode, BaseNode], BaseEdge]]

final(**kwargs)

Create the FINAL node of the DAG. A DAG can only have one FINAL node; if you call this method multiple times, it will override any previous calls. To customize the FINAL node after creation, modify the FinalNode instance that it returns.

Return type: FinalNode

glob(pattern)

Return a Nodes of the nodes in the DAG whose names match the glob pattern.

Return type: Nodes

layer(**kwargs)

Create a new NodeLayer in the graph with no parents or children. Keyword arguments are forwarded to NodeLayer.

Return type: NodeLayer

property leaves: htcondor.dags.node.Nodes

A Nodes of the nodes in the DAG that have no children.

Return type: Nodes

property node_to_children: Dict[htcondor.dags.node.BaseNode, htcondor.dags.node.Nodes]

Return a dictionary that maps each node to a Nodes containing its children. The Nodes will be empty if the node has no children.

Return type: Dict[BaseNode, Nodes]

property node_to_parents: Dict[htcondor.dags.node.BaseNode, htcondor.dags.node.Nodes]

Return a dictionary that maps each node to a Nodes containing its parents. The Nodes will be empty if the node has no parents.

Return type: Dict[BaseNode, Nodes]

property nodes: htcondor.dags.node.Nodes

Iterate over all of the nodes in the DAG, in no particular order.

Return type: Nodes

property roots: htcondor.dags.node.Nodes

A Nodes of the nodes in the DAG that have no parents.

Return type: Nodes

select(selector)

Return a Nodes of the nodes in the DAG that satisfy selector. selector should be a function which takes a single BaseNode and returns True (will be included) or False (will not be included).

Return type: Nodes

subdag(**kwargs)

Create a new SubDAG in the graph with no parents or children. Keyword arguments are forwarded to SubDAG.

Return type: SubDAG

walk(order=WalkOrder.DEPTH_FIRST)

Iterate over all of the nodes in the DAG, starting from the roots (i.e., the nodes with no parents), in either depth-first or breadth-first order.

Sibling order is not specified, and may be different in different calls to this method.

Parameters: order (WalkOrder) – Walk depth-first (children before siblings) or breadth-first (siblings before children).
Return type: Iterator[BaseNode]

walk_ancestors(node, order=WalkOrder.DEPTH_FIRST)

Iterate over all of the ancestors (i.e., parents, parents of parents, etc.) of some node, in either depth-first or breadth-first order.

Sibling order is not specified, and may be different in different calls to this method.

Parameters

node (BaseNode) – The node to begin walking from. It will not be included in the results.
order (WalkOrder) – Walk depth-first (parents before siblings) or breadth-first (siblings before parents).

Return type

Iterator[BaseNode]

walk_descendants(node, order=WalkOrder.DEPTH_FIRST)

Iterate over all of the descendants (i.e., children, children of children, etc.) of some node, in either depth-first or breadth-first order.

Sibling order is not specified, and may be different in different calls to this method.

Parameters

node (BaseNode) – The node to begin walking from. It will not be included in the results.
order (WalkOrder) – Walk depth-first (children before siblings) or breadth-first (siblings before children).

Return type

Iterator[BaseNode]

class htcondor.dags.WalkOrder(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

An enumeration for keeping track of which order to walk through a graph. Depth-first means that parents/children will be visited before siblings. Breadth-first means that siblings will be visited before parents/children.

BREADTH_FIRST = 'BREADTH'

DEPTH_FIRST = 'DEPTH'

Nodes and Node-likes

class htcondor.dags.BaseNode(dag, *, name, dir=None, noop=False, done=False, retries=None, retry_unless_exit=None, pre=None, post=None, pre_skip_exit_code=None, priority=0, category=None, abort=None)

This is the superclass for all node-like objects (things that can be the logical nodes in a DAG, like NodeLayer and SubDAG).

Generally, you do not need to construct nodes yourself; instead, they are created by calling methods like DAG.layer(), DAG.subdag(), BaseNode.child_layer(), and so forth. These methods automatically attach the new node to the same DAG as the node you called the method on.

Parameters

dag (DAG) – Which DAG to attach this node to.
name (str) – The human-readable name of this node.
dir (Optional[Path, None]) – The directory to submit from. If None, it will be the directory the DAG itself was submitted from.
noop (Union[bool, Mapping[int, bool]]) – If this is True, this node will be skipped and marked as completed, no matter what it says it does. For a NodeLayer, this can be dictionary mapping individual underlying node indices to their desired value.
done (Union[bool, Mapping[int, bool]]) – If this is True, this node will be considered already completed. For a NodeLayer, this can be dictionary mapping individual underlying node indices to their desired value.
retries (Optional[int, None]) – The number of times to retry the node if it fails (defined by retry_unless_exit).
retry_unless_exit (Optional[int, None]) – If the node exits with this code, it will not be retried.
pre (Optional[Script, None]) – A Script to run before the node itself.
post (Optional[Script, None]) – A Script to run after the node itself.
pre_skip_exit_code (Optional[int, None]) – If the pre-script exits with this code, the node will be skipped.
priority (int) – The internal priority for DAGMan to run this node.
category (Optional[str, None]) – Which CATEGORY this node belongs to.
abort (Optional[DAGAbortCondition, None]) – A DAGAbortCondition which may cause the entire DAG to stop if this node exits in a certain way.

add_children(*nodes, edge=None)

Makes all of the nodes children of this node.

Parameters

nodes – The nodes to make children of this node.
edge (Optional[BaseEdge, None]) – The type of edge to use; an instance of a concrete subclass of BaseEdge. If None, a ManyToMany edge will be used.

Returns

self – This method returns self.

Return type

BaseNode

add_parents(*nodes, edge=None)

Makes all of the nodes parents of this node.

Parameters

nodes – The nodes to make parents of this node.
edge (Optional[BaseEdge, None]) – The type of edge to use; an instance of a concrete subclass of BaseEdge. If None, a ManyToMany edge will be used.

Returns

self – This method returns self.

Return type

BaseNode

child_layer(edge=None, **kwargs)

Create a new NodeLayer which is a child of this node.

Parameters

edge (Optional[BaseEdge, None]) – The type of edge to use; an instance of a concrete subclass of BaseEdge. If None, a ManyToMany edge will be used.
kwargs – Additional keyword arguments are passed to the NodeLayer constructor.

Returns

node_layer – The newly-created node layer.

Return type

child_subdag(edge=None, **kwargs)

Create a new SubDAG which is a child of this node.

Parameters

edge (Optional[BaseEdge, None]) – The type of edge to use; an instance of a concrete subclass of BaseEdge. If None, a ManyToMany edge will be used.
kwargs – Additional keyword arguments are passed to the SubDAG constructor.

Returns

subdag – The newly-created sub-DAG.

Return type

property children: htcondor.dags.node.Nodes

Return a Nodes containing all of the children of this node.

Return type: Nodes

parent_layer(edge=None, **kwargs)

Create a new NodeLayer which is a parent of this node.

Parameters

edge (Optional[BaseEdge, None]) – The type of edge to use; an instance of a concrete subclass of BaseEdge. If None, a ManyToMany edge will be used.
kwargs – Additional keyword arguments are passed to the NodeLayer constructor.

Returns

node_layer – The newly-created node layer.

Return type

parent_subdag(edge=None, **kwargs)

Create a new SubDAG which is a parent of this node.

Parameters

edge (Optional[BaseEdge, None]) – The type of edge to use; an instance of a concrete subclass of BaseEdge. If None, a ManyToMany edge will be used.
kwargs – Additional keyword arguments are passed to the SubDAG constructor.

Returns

subdag – The newly-created sub-DAG.

Return type

property parents: htcondor.dags.node.Nodes

Return a Nodes containing all of the parents of this node.

Return type: Nodes

remove_children(*nodes)

Makes sure that the nodes are not children of this node.

Parameters: nodes – The nodes to remove edges from.
Returns: self – This method returns self.
Return type: BaseNode

remove_parents(*nodes)

Makes sure that the nodes are not parents of this node.

Parameters: nodes – The nodes to remove edges from.
Returns: self – This method returns self.
Return type: BaseNode

walk_ancestors(order=WalkOrder.DEPTH_FIRST)

Walk over all of the ancestors of this node, in the given order.

Return type: Iterator[BaseNode]

walk_descendants(order=WalkOrder.DEPTH_FIRST)

Walk over all of the descendants of this node, in the given order.

Return type: Iterator[BaseNode]

class htcondor.dags.NodeLayer(dag, *, submit_description=None, vars=None, **kwargs)

Bases: htcondor.dags.node.BaseNode

Represents a “layer” of actual JOB nodes that share a submit description and edge relationships. Each underlying actual node’s attributes may be customized using vars.

Parameters

dag (DAG) – The DAG to connect this node to.
submit_description (Union[Submit, None, Path]) – The HTCondor submit description for this node. Can be either an htcondor.Submit object or a Path to an existing submit file on disk.
vars (Optional[Iterable[Dict[str, str]], None]) – The VARS for this logical node; one actual node will be created for each dictionary in the vars.
kwargs – Additional keyword arguments are passed to the BaseNode constructor.

class htcondor.dags.SubDAG(dag, *, dag_file, **kwargs)

Bases: htcondor.dags.node.BaseNode

Represents a SUBDAG in the graph.

See A DAG Within a DAG Is a SUBDAG for more information on sub-DAGs.

Parameters

dag (DAG) – The DAG to connect this node to.
dag_file (Path) – The pathlib.Path to where the sub-DAG’s DAG description file is (or will be).
kwargs – Additional keyword arguments are passed to the BaseNode constructor.

class htcondor.dags.FinalNode(dag, submit_description=None, **kwargs)

Bases: htcondor.dags.node.BaseNode

Represents the FINAL node in a DAG.

See PROVISIONER node for more information on the FINAL node.

Parameters

dag (DAG) – The DAG to connect this node to.
submit_description (Union[Submit, None, Path]) – The HTCondor submit description for this node. Can be either an htcondor.Submit object or a Path to an existing submit file on disk.
kwargs – Additional keyword arguments are passed to the BaseNode constructor.

class htcondor.dags.Nodes(*nodes)

This class represents an arbitrary collection of BaseNode. In many cases, especially when manipulating the structure of the graph, it can be used as a replacement for directly iterating over collections of nodes.

Parameters: nodes (Union[BaseNode, Iterable[BaseNode]]) – The logical nodes that will be in this Nodes.

add_children(*nodes, type=None)

Makes all of the nodes children of all of the nodes in this Nodes.

Parameters

nodes – The nodes to make children of this Nodes.
type (Optional[BaseEdge, None]) – The type of edge to use; an instance of a concrete subclass of BaseEdge. If None, a ManyToMany edge will be used.

Returns

self – This method returns self.

Return type

Nodes

add_parents(*nodes, type=None)

Makes all of the nodes parents of all of the nodes in this Nodes.

Parameters

nodes – The nodes to make parents of this Nodes.
type (Optional[BaseEdge, None]) – The type of edge to use; an instance of a concrete subclass of BaseEdge. If None, a ManyToMany edge will be used.

Returns

self – This method returns self.

Return type

Nodes

child_layer(type=None, **kwargs)

Create a new NodeLayer which is a child of all of the nodes in this Nodes.

Parameters

type (Optional[BaseEdge, None]) – The type of edge to use; an instance of a concrete subclass of BaseEdge. If None, a ManyToMany edge will be used.
kwargs – Additional keyword arguments are passed to the NodeLayer constructor.

Returns

node_layer – The newly-created node layer.

Return type

child_subdag(type=None, **kwargs)

Create a new SubDAG which is a child of all of the nodes in this Nodes.

Parameters

type (Optional[BaseEdge, None]) – The type of edge to use; an instance of a concrete subclass of BaseEdge. If None, a ManyToMany edge will be used.
kwargs – Additional keyword arguments are passed to the SubDAG constructor.

Returns

subdag – The newly-created sub-DAG.

Return type

parent_layer(type=None, **kwargs)

Create a new NodeLayer which is a parent of all of the nodes in this Nodes.

Parameters

type (Optional[BaseEdge, None]) – The type of edge to use; an instance of a concrete subclass of BaseEdge. If None, a ManyToMany edge will be used.
kwargs – Additional keyword arguments are passed to the NodeLayer constructor.

Returns

node_layer – The newly-created node layer.

Return type

parent_subdag(type=None, **kwargs)

Create a new SubDAG which is a parent of all of the nodes in this Nodes.

Parameters

type (Optional[BaseEdge, None]) – The type of edge to use; an instance of a concrete subclass of BaseEdge. If None, a ManyToMany edge will be used.
kwargs – Additional keyword arguments are passed to the SubDAG constructor.

Returns

subdag – The newly-created sub-DAG.

Return type