order.mixins ¶

Mixin classes providing common functionality.

Contents

order.mixins

Class CopyMixin¶

class CopyMixin¶

Bases: object

Mixin-class that adds copy features to inheriting classes.

Inheriting classes should define a copy_specs class member, which is supposed to be a list containing specifications per attribute to be copied. See CopySpec and CopySpec.new() for information about possible copy specifications.

Example

import order as od

some_object = object()

class MyClass(od.CopyMixin):

    copy_specs = [
        "name",
        {"attr": "obj", "ref": True},
    ]

    def __init__(self, name, obj):
        super(MyClass, self).__init__()
        self.name = name
        self.obj = obj

a = MyClass("foo", some_object)
a.name
# -> "foo"

b = a.copy()
b.name
# -> "foo"

b.obj is a.obj
# -> True

c = a.copy(name="bar")
c.name
# -> "bar"

# one can also use the python copy module
import copy

d = copy.copy(a)

d.name
# -> "foo"

d.obj is a.obj
# -> True

# no distinction is made between copy and deepcopy
e = copy.deepcopy(a)

e.obj is a.obj
# -> True

Members

classattributecopy_specs¶
type: list: List of copy specifications per attribute.

_copy_attribute(obj, spec)¶: Copies an object obj, taking into account the CopySpec speficications spec, and returns the copy. Internally, copy.copy and copy.deepcopy are used to copy objects.

_copy_attribute_manual(inst, obj, spec)¶: Hook that is called in copy() to invoke the manual copying of an object obj after the copied instance inst was created. spec is the associated CopySpec object. Instead of returning the copied object, the method should directly alter inst.

_copy_ref(kwargs, cls, specs)¶: Hook that is called in copy() before an instance is actually copied. When this method returns True, no new instance is created but rather a reference will be returned. The default is False. This is useful in special situations that require flexible copy decisions. kwargs is a dictionary that contains all args and kwargs passed to copy() (args are included by mapping them to the target argument names via inspection), cls is the target class to instantiate, and specs is the full list of CopySpec instances.

copy(*args, **kwargs, _cls=None, _specs=None, _replace_specs=False, _skip=None)¶: Creates a copy of this instance and returns it. Internally, an instance if _cls is created, defaulting to the class of this instance, with all args and kwargs forwarded to its constructor. Attributes that are not present in args or kwargs are copied over from this instance based in the attribute specifications given in copy_specs. They can be extended by _specs or even replaced when _replace_specs is True. _skip can be a sequence of destination attribute names that should be skipped.

__copy__()¶: Shorthand to copy() without arguments.

__deepcopy__(memo)¶: Shorthand to copy() without arguments.

Class CopySpec¶

class CopySpec(dst, src=None, ref=False, shallow=False, use_setter=False, manual=False)¶

Bases: object

Class holding attribute copy specifications. Instances of this class are used in CopyMixin to describe the copy behavior individually per attribute.

Arguments

dst is the destination attribute name, src is the source attribute. When ref is True, the attribute is not copied but a reference is passed to the newly created instance. By default, copy.deepcopy is used to copy attributes (if ref is False). When shallow is True, copy.copy is used instead. The standard way to pass copied attributes to new instances is via constructor arguments. However, you can set use_setter to True to use a plain setter to add the copied attribute to the instance. manual denotes whether the custom CopyMixin._copy_attribute_manual() method should be invoked to copy an attribute. This method must be implemented by inheriting functions.

Members

dst¶
type: string: The destination attribute.

src¶
type: string: The source attribute.

ref¶
type: bool: Whether or not the attribute should be passed as a reference instead of copying.

shallow¶
type: bool: Whether or not the attribute should be copied shallow or deep.

use_setter¶
type: bool: Whether or not a setter should be invoked to set the copied attribute. When False, it is passed as a constructor argument (the default).

manual¶
type: bool: Whether or not the attribute should be copied manually by the custom CopyMixin._copy_attribute_manual() method.

Class AuxDataMixin¶

class AuxDataMixin(aux=None)¶

Bases: object

Mixin-class that provides storage of auxiliary data via a simple interface.

Arguments

aux can be a dictionary or a list of 2-tuples to initialize the auxiliary data container. For convenient access via attributes, each instance of this mixin-class has a proxy object x which can be used to obtain auxiliary information. See example below.

Example

import order as od

class MyClass(od.AuxDataMixin):
    pass

c = MyClass(aux={"foo": "bar"})

# "foo" in c.aux
# same as c.has_aux("foo")
# -> True

c.set_aux("test", "some_value")
c.get_aux("test")
# -> "some_value"

c.get_aux("notthere")
# -> KeyError

c.get_aux("notthere", default=123)
# -> 123

c.x.test
# -> "some_value"

c.x("test")  # same as c.get_aux
# -> "some_value"

c.x.notthere
# -> AttributeError

Members

aux¶
type: OrderedDict: The dictionary of auxiliary data.

x¶
type: DotAccessProxy
read-only: An object that provides simple attribute access to auxiliary data.

set_aux(key, value)¶: Stores auxiliary value for a specific key. Returns value.

has_aux(key)¶: Returns True when an auxiliary data entry for a specific key exists, False otherwise.

get_aux(key[, default])¶: Returns the auxiliary data for a specific key. If a default is given, it is returned in case key is not found.

remove_aux(key, silent=False)¶: Removes the auxiliary data for a specific key. Unless silent is True, an exception is raised if the key to remove is not found.

clear_aux()¶: Clears the auxiliary data container.

Class TagMixin¶

class TagMixin(tags=None)¶

Bases: object

Mixin-class that allows inheriting objects to be attribute one or more tags. See the example below for more infos.

Arguments

tags initializes the internal set of stored tags.

Example

import order as od

class MyClass(od.TagMixin):
    pass

c = MyClass(tags={"foo", "bar"})

c.has_tag("foo")
# -> True

c.has_tag("baz")
# -> False

c.has_tag(("foo", "baz"), mode=any)  # the default mode
# -> True

c.has_tag(("foo", "baz"), mode=all)
# -> False

c.has_tag(("foo", "ba*"), mode=all)
# -> True

c.has_tag(("foo", "ba(r|z)"), mode=all, func="re")
# -> True

Members

tags¶
type: set: The set of tags of this object. See has_tag() for information about how to evaluate them with patterns or regular expressions.

add_tag(tag)¶: Adds a new tag to the set of tags.

remove_tag(tag)¶: Removes a previously added tag from the set if tags.

has_tag(tag, mode=any, **kwargs)¶: Returns True when this object is tagged with tag, False otherwise. When tag is a sequence of tags, the behavior is defined by mode. For any, the object is considered tagged when at least one of the provided tags matches. When all, all provided tags have to match. Each tag can be a fnmatch or re pattern. All kwargs are passed to util.multi_match().

Class DataSourceMixin¶

class DataSourceMixin(is_data=False)¶

Bases: object

Mixin-class that provides convenience attributes for distinguishing between MC and real data.

Arguments

is_data initializes the same-named attribute.

Example

import order as od

class MyClass(od.DataSourceMixin):
    pass

c = MyClass(is_data=False)

c.is_data
# -> False

c.data_source
# -> "mc"

c.is_data = True
c.data_source
# -> "data"

Members

classattributeDATA_SOURCE_DATA¶
type: string: The data source string for data ("data").

classattributeDATA_SOURCE_MC¶
type: string: The data source string for mc ("mc").

is_data¶
type: boolean: True if this object contains information on real data.

is_mc¶
type: boolean: True if this object contains information on MC data.

data_source¶
type: string: Either DATA_SOURCE_DATA or DATA_SOURCE_MC, depending on the source of contained data.

Class SelectionMixin¶

class SelectionMixin(selection=None, selection_mode=None)¶

Bases: object

Mixin-class that adds attibutes and methods to describe a selection rule using ROOT- or numexpr-style expression syntax, or a bare callable.

Arguments

selection and selection_mode initialize the same-named attributes.

Example

import order as od

class MyClass(od.SelectionMixin):
    pass

# ROOT-style expressions
c = MyClass(selection="branchA > 0", selection_mode=MyClass.MODE_ROOT)

c.selection
# -> "branchA > 0"

c.add_selection("myBranchB < 100")
c.selection
# -> "(myBranchA > 0) && (myBranchB < 100)"

c.add_selection("myWeight", op="*")
c.selection
# -> "((myBranchA > 0) && (myBranchB < 100)) * (myWeight)"

# numexpr-style expressions
c = MyClass(selection="branchA > 0", selection_mode=MyClass.MODE_NUMEXPR)

c.add_selection("myBranchB < 100")
c.selection
# -> "(myBranchA > 0) & (myBranchB < 100)"

def my_selection(*args, **kwargs):
    ...

c.selection = my_selection
c.selection
# -> <function my_selection()>
c.selection_mode
# -> None
c.add_selection("myBranchB < 100")
# -> TypeError

Members

classattributeMODE_ROOT¶
type: string: Flag denoting the ROOT-style selection mode ("root").

classattributeMODE_NUMEXP¶
type: string: Flag denoting the numexpr-style selection mode ("numexpr").

classattributedefault_selection_mode¶
type: string: The default selection_mode when none is given in the instance constructor. It is initially set to MODE_NUMEXPR if order.util.ROOT_DEFAULT is false, or to MODE_ROOT otherwise.

selection¶
type: string, callable: The selection string or a callable. When a string, selection_mode decides how the string is treated.

selection_mode¶
type: string, None: The selection mode. Should either be MODE_ROOT or MODE_NUMEXPR. Only considered when selection is a string.

add_selection(selection, **kwargs)¶: Adds a selection string to the current one if it is also a string. The new string will be logically connected via AND by default, which can be configured through kwargs. All kwargs are forwarded to util.join_root_selection() or util.join_numexpr_selection().

Class LabelMixin¶

class LabelMixin(label=None, label_short=None)¶

Bases: object

Mixin-class that provides a label, a short version of that label, and some convenience attributes.

Arguments

label and label_short initialize the same-named attributes.

Example

import order as od

l = od.LabelMixin(label="Muon")

l.label
# -> "Muon"

# when not set, the short label returns the normal label
l.label_short
# -> "Muon"

l.label_short = r"$\mu$"
l.label_short
# -> "$\mu$"

# conversion to ROOT-style latex
l.label_short_root
# -> "#mu"

Members

label¶
type: string: The label. When this object has a name (configurable via _label_fallback_attr) attribute, the label defaults to that value when not set.

label_root¶
type: string
read-only: The label, converted to ROOT-style latex.

label_short¶
type: string: A short label, which defaults to the normal label when not set.

label_short_root¶
type: string
read-only: Short version of the label, converted to ROOT-style latex.

Class ColorMixin¶

class ColorMixin(color=None)¶

Bases: object

Mixin-class that provides a color in terms of RGB values as well as some convenience methods.

Arguments

color can be a tuple of 3 or 4 numbers that are interpreted as red, green and blue color values, and optinally an alpha value. Floats are stored internally. When integers are passed, they are divided by 255.

Example

import order as od

c = od.ColorMixin(color=(255, 0.5, 100))

c.color
# -> (1.0, 0.5, 0.392..)

c.color_int
# -> (255, 128, 100)

c.color_alpha
# -> 1.0

Members

color_r¶
type: float: Red component.

color_g¶
type: float: Green component.

color_b¶
type: float: Blue component.

color_r_int¶
type: int: Red component, converted to an integer in the [0, 255] range.

color_g_int¶
type: int: Green component, converted to an integer in the [0, 255] range.

color_b_int¶
type: int: Blue component, converted to an integer in the [0, 255] range.

color_alpha¶
type: float: The alpha value, defaults to 1.

color¶
type: tuple (float): The RGB color values in a 3-tuple.

color_int¶
type: tuple (int): The RGB int color values in a 3-tuple.