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) → 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.

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