`classad` API Reference

This page is an exhaustive reference of the API exposed by the classad 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.

ClassAd Representation

ClassAds are individually represented by the ClassAd class. Their attribute are key-value pairs, as in a standard Python dictionary. The keys are strings, and the values may be either Python primitives corresponding to ClassAd data types (string, bool, etc.) or ExprTree objects, which correspond to un-evaluated ClassAd expressions.

class classad.ClassAd(input)

The ClassAd object is the Python representation of a ClassAd. Where possible, ClassAd attempts to mimic a Python dict. When attributes are referenced, they are converted to Python values if possible; otherwise, they are represented by a ExprTree object.

New ClassAd objects can be initialized via a string (which is parsed as an ad) or a dictionary-like object containing attribute-value pairs.

The ClassAd object is iterable (returning the attributes) and implements the dictionary protocol. The items, keys, values, get, setdefault, and update methods have the same semantics as a dictionary.

Note

Where possible, we recommend using the dedicated parsing functions (parseOne(), parseNext(), or parseAds()) instead of using the constructor.

Parameters: input (str or dict) – A string or dictionary which will be interpreted as a classad.

eval(attr) → object :

Evaluate an attribute to a Python object. The result will not be an ExprTree but rather an built-in type such as a string, integer, boolean, etc.

Parameters: attr (str) – Attribute to evaluate.
Returns: The Python object corresponding to the evaluated ClassAd attribute
Raises: ValueError – if unable to evaluate the object.

lookup(attr) → ExprTree :

Look up the ExprTree object associated with attribute.

No attempt will be made to convert to a Python object.

Parameters: attr (str) – Attribute to evaluate.
Returns: The ExprTree object referenced by attr.

printOld() → str :

Serialize the ClassAd in the old ClassAd format.

Returns: The ‘old ClassAd’ representation of the ad.
Return type: str

printJson(arg1) → str :

Serialize the ClassAd as a string in JSON format.

Returns: The JSON representation of the ad.
Return type: str

flatten(expr) → object :

Given ExprTree object expression, perform a partial evaluation. All the attributes in expression and defined in this ad are evaluated and expanded. Any constant expressions, such as 1 + 2, are evaluated; undefined attributes are not evaluated.

Parameters: expr (ExprTree) – The expression to evaluate in the context of this ad.
Returns: The partially-evaluated expression.
Return type: ExprTree

matches(ad) → bool :

Lookup the Requirements attribute of given ad return True if the Requirements evaluate to True in our context.

Parameters: ad (ClassAd) – ClassAd whose Requirements we will evaluate.
Returns: True if we satisfy ad’s requirements; False otherwise.
Return type: bool

symmetricMatch(ad) → bool :

Check for two-way matching between given ad and ourselves.

Equivalent to self.matches(ad) and ad.matches(self).

Parameters: ad (ClassAd) – ClassAd to check for matching.
Returns: True if both ads’ requirements are satisfied.
Return type: bool

externalRefs(expr) → list :

Returns a Python list of external references found in expr.

An external reference is any attribute in the expression which is not defined by the ClassAd object.

Parameters: expr (ExprTree) – Expression to examine.
Returns: A list of external attribute references.
Return type: list[str]

internalRefs(expr) → list :

Returns a Python list of internal references found in expr.

An internal reference is any attribute in the expression which is defined by the ClassAd object.

Parameters: expr (ExprTree) – Expression to examine.
Returns: A list of internal attribute references.
Return type: list[str]

__eq__(arg1, arg2) → bool :: One ClassAd is equivalent to another if they have the same number of attributes, and each attribute is the sameAs() the other.

__ne__(arg1, arg2) → bool :: The opposite of __eq__().

class classad.ExprTree(expr)

The ExprTree class represents an expression in the ClassAd language.

The ExprTree constructor takes an ExprTree, or a string, which it will attempt to parse into a ClassAd expression. str(expr) will turn the ExprTree back into its string representation. int, float, and bool behave similarly, evaluating as necessary.

As with typical ClassAd semantics, lazy-evaluation is used. So, the expression 'foo' + 1 does not produce an error until it is evaluated with a call to bool() or the ExprTree.eval() method.

Note

The Python operators for ExprTree have been overloaded so, if e1 and e2 are ExprTree objects, then e1 + e2 is also an ExprTree object. However, Python short-circuit evaluation semantics for e1 && e2 cause e1 to be evaluated. In order to get the ‘logical and’ of the two expressions without evaluating, use e1.and_(e2). Similarly, e1.or_(e2) results in the ‘logical or’.

and_(expr) → ExprTree :

Return a new expression, formed by self && expr.

Parameters: expr (ExprTree) – Right-hand-side expression to ‘and’
Returns: A new expression, defined to be self && expr.
Return type: ExprTree

or_(expr) → ExprTree :

Return a new expression, formed by self || expr.

Parameters: expr (ExprTree) – Right-hand-side expression to ‘or’
Returns: A new expression, defined to be self || expr.
Return type: ExprTree

is_(expr) → ExprTree :

Logical comparison using the ‘meta-equals’ operator.

Parameters: expr (ExprTree) – Right-hand-side expression to =?= operator.
Returns: A new expression, formed by self =?= expr.
Return type: ExprTree

isnt_(expr) → ExprTree :

Logical comparison using the ‘meta-not-equals’ operator.

Parameters: expr (ExprTree) – Right-hand-side expression to =!= operator.
Returns: A new expression, formed by self =!= expr.
Return type: ExprTree

sameAs(expr) → bool :

Returns True if given ExprTree is same as this one.

Parameters: expr (ExprTree) – Expression to compare against.
Returns: True if and only if expr is equivalent to this object.
Return type: bool

eval(scope) → object :

Evaluate the expression and return as a ClassAd value, typically a Python object.

Warning

If scope is passed and is not the ClassAd this ExprTree might belong to, this method is not thread-safe.

Parameters

scope (ClassAd) –

Optionally, the ClassAd context in which to evaluate. Unnecessary if the ExprTree comes from its own ClassAd, in which case it will be evaluated in the scope of that ad, or if the ExprTree can be evaluated without a context.

If passed, scope must be a classad.ClassAd.

Returns

The evaluated expression as a Python object.

simplify(scope, target) → ExprTree :

Evaluate the expression and return as a ExprTree.

Warning

If scope is passed and is not the ClassAd this ExprTree might belong to, this method is not thread-safe.

Warning

It is erroneous for scope to be a temporary; the lifetime of the returned object may depend on the lifetime of the scope object.

Parameters

scope (ClassAd) –
Optionally, the ClassAd context in which to evaluate. Unnecessary if the ExprTree comes from its own ClassAd, in which case it will be evaluated in the scope of that ad, or if the ExprTree can be evaluated without a context.

If passed, scope must be a classad.ClassAd.
target (ClassAd) –
Optionally, the ClassAd TARGET ad.

If passed, target must be a classAd.ClassAd.

Returns

The evaluated expression as an ExprTree.

class classad.Value

An enumeration of the two special ClassAd values Undefined and Error.

The values of the enumeration are:

Undefined

Error

Parsing and Creating ClassAds

classad provides a variety of utility functions that can help you construct ClassAd expressions and parse string representations of ClassAds.

classad.parseAds(input, parser=classad.classad.Parser.Auto) → object :

Parse the input as a series of ClassAds.

Parameters

input (str or file) – Serialized ClassAd input; may be a file-like object.
parser (Parser) – Controls behavior of the ClassAd parser.

Returns

An iterator that produces ClassAd.

classad.parseNext(input, parser=classad.classad.Parser.Auto) → object :

Parse the next ClassAd in the input string. Advances the input to point after the consumed ClassAd.

Parameters

input (str or file) – Serialized ClassAd input; may be a file-like object.
parser (Parser) – Controls behavior of the ClassAd parser.

Returns

An iterator that produces ClassAd.

classad.parseOne(input, parser=classad.classad.Parser.Auto) → ClassAd :

Parse the entire input into a single ClassAd object.

In the presence of multiple ClassAds or blank lines in the input, continue to merge ClassAds together until the entire input is consumed.

Parameters

input (str or file) – Serialized ClassAd input; may be a file-like object.
parser (Parser) – Controls behavior of the ClassAd parser.

Returns

Corresponding ClassAd object.

Return type

ClassAd

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

classad API Reference

ClassAd Representation

Parsing and Creating ClassAds

Parser Control

Utility Functions

Exceptions

Deprecated Functions

`classad` API Reference