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

The ExprTree class represents an expression in the ClassAd language.

The ExprTree constructor takes 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, a ClassAd to evaluate the ExprTree in the context of. 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.
Returns:The evaluated expression as a Python object.

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.

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