order.util

Helpful utilities.

Data:

ROOT_DEFAULT

Boolean value that denotes if ROOT-style selection strings, latex labels, etc, are used by default.

Classes:

typed([fparse, setter, deleter, name])	Shorthand for the most common property definition.
DotAccessProxy(getter[, setter])	Proxy object that provides simple attribute access to values that are retrieved by a getter and optionally set through a setter.

Functions:

make_list(obj[, cast])	Converts an object obj to a list and returns it.
multi_match(name, patterns[, mode, func])	Compares name to multiple patterns and returns True in case of at least one match (mode = any, the default), or in case all patterns matched (mode = all).
flatten(struct[, depth])	Flattens and returns a complex structured object struct up to a certain depth.
to_root_latex(s)	Converts latex expressions in a string s to ROOT-compatible latex.
join_root_selection(*selection[, op, bracket])	Returns a concatenation of root selection strings, which is done by default via logical AND.
join_numexpr_selection(*selection[, op, bracket])	Returns a concatenation of numexpr selection strings, which is done by default via logical AND.
class_id(cls)	Returns the full id of a class, i.e., the id of the module it is defined in, extended by the name of the class.
args_to_kwargs(func, args)	Converts arguments args passed to a function func to a dictionary that can be used as keyword arguments.

ROOT_DEFAULT = False

Boolean value that denotes if ROOT-style selection strings, latex labels, etc, are used by default. The value defaults to False and can be altered by setting

os.environ["ORDER_ROOT_DEFAULT"] = 1|"1"|"yes"|"true"

before importing order. This rather peculiar mechanism is favored over e.g. using a setter since also default values of various methods across the order package depend on this flag.

class typed(fparse=None, setter=True, deleter=True, name=None)

Shorthand for the most common property definition. Can be used as a decorator to wrap around a single function. Example:

class MyClass(object):

    def __init__(self):
        self._foo = None

    @typed
    def foo(self, foo):
        if not isinstance(foo, str):
            raise TypeError("not a string: '%s'" % foo)
        return foo

myInstance = MyClass()
myInstance.foo = 123   -> TypeError
myInstance.foo = "bar" -> ok
print(myInstance.foo)  -> prints "bar"

In the exampe above, set/get calls target the instance member _foo, i.e. “_<function_name>”. The member name can be configured by setting name. If setter (deleter) is True (the default), a setter (deleter) method is booked as well. Prior to updating the member when the setter is called, fparse is invoked which may implement sanity checks.

make_list(obj, cast=True)

Converts an object obj to a list and returns it. Objects of types tuple and set are converted if cast is True. Otherwise, and for all other types, obj is put in a new list.

multi_match(name, patterns, mode=<built-in function any>, func='fnmatch', *args, **kwargs)

Compares name to multiple patterns and returns True in case of at least one match (mode = any, the default), or in case all patterns matched (mode = all). Otherwise, False is returned. func determines the matching function and accepts "fnmatch", "fnmatchcase", and "re". All args and kwargs are passed to the actual matching function.

flatten(struct, depth=-1)

Flattens and returns a complex structured object struct up to a certain depth. When depth is negative, struct is flattened entirely.

to_root_latex(s)

Converts latex expressions in a string s to ROOT-compatible latex.

join_root_selection(*selection, op='&&', bracket=False)

Returns a concatenation of root selection strings, which is done by default via logical AND. (op). When bracket is True, the final selection string is placed into brackets.

join_numexpr_selection(*selection, op='&', bracket=False)

Returns a concatenation of numexpr selection strings, which is done by default via logical AND. (op). When bracket is True, the final selection string is placed into brackets.

class_id(cls)

Returns the full id of a class, i.e., the id of the module it is defined in, extended by the name of the class. Example:

# module a.b

class MyClass(object):
    ...

class_id(MyClass)
# "a.b.MyClass"

args_to_kwargs(func, args)

Converts arguments args passed to a function func to a dictionary that can be used as keyword arguments. Internally, inspect.getargspec is used to get the names of arguments in the function signature. Example:

def func(a, b, c=1):
    ...

def wrapper(*args, **kwargs):
    kwargs.update(args_to_kwargs(func, args))
    # kwargs now contains the initial args and kwargs for easy parsing
    ...
    return func(**kwargs)

class DotAccessProxy(getter, setter=None)

Proxy object that provides simple attribute access to values that are retrieved by a getter and optionally set through a setter. Example:

my_dict = {"foo": 123}

proxy = DotAccessProxy(my_dict.__getattr__)
proxy.foo
# -> 123
proxy.bar
# -> AttributeError

proxy = DotAccessProxy(my_dict.get)
proxy.foo
# -> 123
proxy.bar
# -> None

proxy = DotAccessProxy(my_dict.get, my_dict.__setitem__)
proxy.foo
# -> 123
proxy.bar
# -> None
proxy.bar = 99
proxy.bar
# -> 99