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 Pythondict
. When attributes are referenced, they are converted to Python values if possible; otherwise, they are represented by aExprTree
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. Theitems
,keys
,values
,get
,setdefault
, andupdate
methods have the same semantics as a dictionary.Note
Where possible, we recommend using the dedicated parsing functions (
parseOne()
,parseNext()
, orparseAds()
) instead of using the constructor.- 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.
- printOld() str :
Serialize the ClassAd in the old ClassAd format.
- Returns
The ‘old ClassAd’ representation of the ad.
- Return type
- printJson(arg1) str :
Serialize the ClassAd as a string in JSON format.
- Returns
The JSON representation of the ad.
- Return type
- 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.
- matches(ad) bool :
Lookup the
Requirements
attribute of givenad
returnTrue
if theRequirements
evaluate toTrue
in our context.
- symmetricMatch(ad) bool :
Check for two-way matching between given ad and ourselves.
Equivalent to
self.matches(ad) and ad.matches(self)
.
- 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.
- 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.
- 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 theExprTree
back into its string representation.int
,float
, andbool
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 tobool()
or theExprTree.eval()
method.Note
The Python operators for
ExprTree
have been overloaded so, ife1
ande2
areExprTree
objects, thene1 + e2
is also anExprTree
object. However, Python short-circuit evaluation semantics fore1 && e2
causee1
to be evaluated. In order to get the ‘logical and’ of the two expressions without evaluating, usee1.and_(e2)
. Similarly,e1.or_(e2)
results in the ‘logical or’.- and_(expr) ExprTree :
Return a new expression, formed by
self && expr
.
- or_(expr) ExprTree :
Return a new expression, formed by
self || expr
.
- is_(expr) ExprTree :
Logical comparison using the ‘meta-equals’ operator.
- isnt_(expr) ExprTree :
Logical comparison using the ‘meta-not-equals’ operator.
- eval(scope) object :
Evaluate the expression and return as a ClassAd value, typically a Python object.
Warning
If
scope
is passed and is not theClassAd
thisExprTree
might belong to, this method is not thread-safe.- Parameters
scope (
ClassAd
) –Optionally, the
ClassAd
context in which to evaluate. Unnecessary if theExprTree
comes from its ownClassAd
, in which case it will be evaluated in the scope of that ad, or if theExprTree
can be evaluated without a context.If passed,
scope
must be aclassad.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 theClassAd
thisExprTree
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 theExprTree
comes from its ownClassAd
, in which case it will be evaluated in the scope of that ad, or if theExprTree
can be evaluated without a context.If passed,
scope
must be aclassad.ClassAd
.target (
ClassAd
) –Optionally, the
ClassAd
TARGET ad.If passed,
target
must be aclassAd.ClassAd
.
- Returns
The evaluated expression as an
ExprTree
.
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.
- 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.
- 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.
- 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'
- 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.
- 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 codeAttribute('foo') == 1
.
- classad.Function()
Given function name
name
, and zero-or-more arguments, construct anExprTree
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 expressionFunction('strcat', 'hello ', 'world')
.- Returns
Corresponding expression consisting of a function call.
- Return type
- 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
- 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.ClassAdParseError
Raised when the ClassAd library fails to parse a (putative) ClassAd.
- 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.