classad – ClassAd 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.

This reference covers the following:

Module-Level Functions

classad.quote(input)

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)

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.parseAds(input, parser=Auto)

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=Auto)

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=Auto)

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.version()

Return the version of the linked ClassAd library.

classad.lastError()

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.Attribute(name)

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(name, arg1, arg2, ...)

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 Function("strcat", "hello ", "world").

Returns:Corresponding expression consisting of a function call.
Return type:ExprTree
classad.Literal(obj)

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.register(function, name=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(path)

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.

Module Classes

class classad.ClassAd

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

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.

__init__(ad)

Create a new ClassAd object; can be initialized via a string (which is parsed as an ad) or a dictionary-like object.

Note

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

Parameters:ad (str or dict) – Initial values for this object.
eval(attr)

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)

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()

Serialize the ClassAd in the old ClassAd format.

Returns:The “old ClassAd” representation of the ad.
Return type:str
flatten(expression)

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:expression (ExprTree) – The expression to evaluate in the context of this ad.
Returns:The partially-evaluated expression.
Return type:ExprTree
matches(ad)

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)

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)

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)

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]
class classad.ExprTree

The ExprTree class represents an expression in the ClassAd language.

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 :class: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”.

__init__(expr)

Parse the string expr as a ClassAd expression.

Parameters:expr (str) – Initial expression, serialized as a string.
__str__()

Represent and return the ClassAd expression as a string.

Returns:Expression represented as a string.
Return type:str
__int__()

Converts expression to an integer (evaluating as necessary).

__float__()

Converts expression to a float (evaluating as necessary).

and_(expr2)

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

Parameters:expr2 (ExprTree) – Right-hand-side expression to “and”
Returns:A new expression, defined to be self && expr2.
Return type:ExprTree
or_(expr2)

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

Parameters:expr2 (ExprTree) – Right-hand-side expression to “or”
Returns:A new expression, defined to be self || expr2.
Return type:ExprTree
is_(expr2)

Logical comparison using the “meta-equals” operator.

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

Logical comparison using the “meta-not-equals” operator.

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

Returns True if given ExprTree is same as this one.

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

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

Returns:The evaluated expression as a Python object.

Useful Enumerations

class classad.Parser

Controls the behavior of the ClassAd parser.

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.

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)

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)

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