uproot.Model

class uproot.model.Model

Abstract class for all objects extracted from ROOT files (except for uproot.ReadOnlyFile, uproot.ReadOnlyDirectory, and uproot.reading.ReadOnlyKey).

A model is instantiated from a file using the read classmethod or synthetically using the empty classmethod, not through a normal constructor.

Models point back to the file from which they were created, though only a few classes (named in uproot.reading.must_be_attached) have an open, readable file attached; the rest have a uproot.reading.DetachedFile with information about the file, while not holding the file open.

Uproot recognizes some of ROOT’s thousands of classes, by way of methods and properties defined in uproot.behaviors. Examples include

These classes are the most convenient to work with and have specialized documentation.

Classes that don’t have any predefined behaviors are still usable through their member data.

members: a dict of C++ member names and values directly in this class.
all_members: a dict of C++ member names and values in this class or any superclasses.
member: method that takes a C++ member name and returns its value (from this or any superclass).
has_member: method that takes a C++ member name and returns True if it exists (in this or any superclass), False otherwise.

Accessing a data structure through its C++ members may be a prelude to adding custom behaviors for it. Before we know what conveniences to add, we need to know how they’ll be used: this information comes from the user community.

Pythonic models don’t follow the same class inheritance tree as their C++ counterparts: most of them are direct subclasses of uproot.Model, uproot.model.DispatchByVersion, or uproot.model.VersionedModel. To separate an object’s members from its superclass members, a model instance is created for each and the superclass parts are included in a list called bases.

classname

Model.classname

The C++ (decoded) classname of the modeled class.

See uproot.classname_decode, uproot.classname_encode, and uproot.model.classname_version.

encoded_classname

Model.encoded_classname

The Python (encoded) classname of the modeled class. May or may not include version.

See uproot.classname_decode, uproot.classname_encode, and uproot.model.classname_version.

class_version

Model.class_version

The version number of the modeled class (int) if any; None otherwise.

See uproot.classname_decode, uproot.classname_encode, and uproot.model.classname_version.

cursor

Model.cursor: A cursor pointing to the start of this instance in the byte stream (before read_numbytes_version).

file

Model.file: A uproot.ReadOnlyFile, which may be open and readable, or a uproot.reading.DetachedFile, which only contains information about the original file (not an open file handle).

close

Model.close(): Closes the file from which this object is derived, if such a file is still attached (i.e. not uproot.reading.DetachedFile).

closed

Model.closed: True if the associated file is known to be closed; False if it is known to be open. If the associated file is detached (uproot.reading.DetachedFile), then the value is None.

parent

Model.parent: The object that was deserialized before this one in recursive descent, usually the containing object (or the container’s container).

concrete

Model.concrete: The Python instance corresponding to the concrete (instantiated) class in C++, which is self if this is the concrete class or another object if this is actually a holder of superclass members for that other object (i.e. if this object is in the other’s bases).

members

Model.members: A dict of C++ member data directly associated with this class (i.e. not its superclasses). For all members, see all_members.

all_members

Model.all_members: A dict of C++ member data for this class and its superclasses. For only direct members, see members.

has_member

Model.has_member(name, all=True): Returns True if calling member with the same arguments would return a value; False if the member is missing.

member

Model.member(name, all=True, none_if_missing=False)

Parameters:

name (str) – The name of the member datum to retrieve.
all (bool) – If True, recursively search all superclasses in bases. Otherwise, search the direct class only.
none_if_missing (bool) – If a member datum doesn’t exist in the search path, none_if_missing=True has this function return None, but none_if_missing=False would have it raise an exception. Note that None is a possible value for some member data.

Returns a C++ member datum by name.

bases

Model.bases

List of uproot.Model objects representing superclass data for this object in the order given in C++ (opposite method resolution order).

If this object has no superclasses, bases is empty.
If it has one superclass, which itself might have superclasses, bases has length 1.
Only if this object multiply inherits from more than one superclass at the same level does bases have length greater than 1.

Since multiple inheritance is usually avoided, bases rarely has length greater than 1. A linear chain of superclasses deriving from super-superclasses is represented by bases containing an object whose bases contains objects.

base

Model.base(*cls)

Extracts instances from bases by Python class type.

The cls arguments may be Python classes or C++ classname strings to match.

is_instance

Model.is_instance(*cls)

Returns True if this object matches a given type in the C++ class hierarchy.

The cls arguments may be Python classes or C++ classname strings to match.

num_bytes

Model.num_bytes

Number of bytes expected in the (uncompressed) serialization of this instance.

This value may be None (unknown before reading) or an integer.

If the value is an integer and the object exists (no exceptions in read), then the expected number of bytes agreed with the actual number of bytes, and this numer is reliable.

If this object is re-serialized, it won’t necessarily occupy the same number of bytes.

instance_version

Model.instance_version

Version of this instance as read from the byte stream.

If this model is versioned (uproot.model.VersionedModel), the instance_version ought to be equal to the class_version.

If this model is versionless, the instance_version contains new information about the actual version deserialized.

is_memberwise

Model.is_memberwise: True if the object was serialized in ROOT’s memberwise format; False otherwise.

awkward_form

classmethod Model.awkward_form(file, context)

Parameters:

cls (subclass of uproot.Model) – This class.
file (uproot.ReadOnlyFile) – File to use to generate uproot.Model classes from its streamers and file_path for error messages.
context (dict) – Context for the Form-generation; defaults are the remaining arguments below.
index_format (str) – Format to use for indexes of the awkward.forms.Form; may be "i32", "u32", or "i64".
header (bool) – If True, include header fields of each C++ class.
tobject_header (bool) – If True, include header fields of each TObject base class.
breadcrumbs (tuple of class objects) – Used to check for recursion. Types that contain themselves cannot be Awkward Arrays because the depth of instances is unknown.

The awkward.forms.Form to use to put objects of type type in an Awkward Array.

strided_interpretation

classmethod Model.strided_interpretation(file, header=False, tobject_header=True, breadcrumbs=(), original=None)

Parameters:

cls (subclass of uproot.Model) – This class.
file (uproot.ReadOnlyFile) – File to use to generate uproot.Model classes from its streamers and file_path for error messages.
header (bool) – If True, assume the outermost object has a header.
tobject_header (bool) – If True, assume that TObjects have headers.
original (None, uproot.Model, or uproot.containers.Container) – The original, non-strided model or container.
breadcrumbs (tuple of class objects) – Used to check for recursion. Types that contain themselves cannot be strided because the depth of instances is unknown.

Returns a list of (str, numpy.dtype) pairs to build a uproot.AsStridedObjects interpretation.

tojson

Model.tojson(): Serializes this object in its ROOT JSON form (as Python lists and dicts, which can be passed to json.dump or json.dumps).

empty

classmethod Model.empty(): Creates a model instance (of subclass cls) with no data; all required attributes are None or empty.

read

classmethod Model.read(chunk, cursor, context, file, selffile, parent, concrete=None)

Parameters:

cls (subclass of uproot.Model) – Class to instantiate.
chunk (uproot.source.chunk.Chunk) – Buffer of contiguous data from the file uproot.source.chunk.Source.
cursor (uproot.Cursor) – Current position in that chunk.
context (dict) – Auxiliary data used in deserialization.
file (uproot.ReadOnlyFile) – An open file object, capable of generating new uproot.Model classes from its streamers.
selffile (uproot.reading.CommonFileMethods) – A possibly uproot.reading.DetachedFile associated with this object.
parent (None or calling object) – The previous read in the recursive descent.
concrete (None or uproot.Model instance) – If None, this model corresponds to the concrete (instantiated) class in C++. Otherwise, this model represents a superclass part of the object, and concrete points to the concrete instance.

Creates a model instance by reading data from a file.

read_numbytes_version

Model.read_numbytes_version(chunk, cursor, context)

Parameters:

chunk (uproot.source.chunk.Chunk) – Buffer of contiguous data from the file uproot.source.chunk.Source.
cursor (uproot.Cursor) – Current position in that chunk.
context (dict) – Auxiliary data used in deserialization.

Reads the number of bytes and instance version from the byte stream, which is usually 6 bytes (4 + 2). Bits with special meanings are appropriately masked out.

Some types don’t have a 6-byte header or handle it differently; in those cases, this method should be overridden.

read_members

Model.read_members(chunk, cursor, context, file)

Parameters:

chunk (uproot.source.chunk.Chunk) – Buffer of contiguous data from the file uproot.source.chunk.Source.
cursor (uproot.Cursor) – Current position in that chunk.
context (dict) – Auxiliary data used in deserialization.
file (uproot.ReadOnlyFile) – An open file object, capable of generating new uproot.Model classes from its streamers.

Reads the member data for this class. The abstract class uproot.Model has an empty read_members method; this must be overridden by subclasses.

check_numbytes

Model.check_numbytes(chunk, cursor, context)

Parameters:

chunk (uproot.source.chunk.Chunk) – Buffer of contiguous data from the file uproot.source.chunk.Source.
cursor (uproot.Cursor) – Current position in that chunk.
context (dict) – Auxiliary data used in deserialization.

Reads nothing; checks the expected number of bytes against the actual movement of the cursor at the end of the object, possibly raising a uproot.DeserializationError exception.

If num_bytes is None, this method does nothing.

It is possible that a subclass would override this method, but not likely.

postprocess

Model.postprocess(chunk, cursor, context, file)

Parameters:

chunk (uproot.source.chunk.Chunk) – Buffer of contiguous data from the file uproot.source.chunk.Source.
cursor (uproot.Cursor) – Current position in that chunk.
context (dict) – Auxiliary data used in deserialization.
file (uproot.ReadOnlyFile) – An open file object, capable of generating new uproot.Model classes from its streamers.

Called for any additional processing after the object has been fully read.

The return value from this method is the object that actually represents the ROOT data, which might be a different instance or even a different type from this class. The default in uproot.Model is to return self.

Note that for versioned models, postprocess is called first, then postprocess is called on its output, allowing a uproot.model.DispatchByVersion to refine all data of its type, regardless of version.

hook_before_read

Model.hook_before_read(**kwargs): Called in read, before any data have been read.

hook_before_read_members

Model.hook_before_read_members(**kwargs): Called in read, after read_numbytes_version and before read_members.

hook_after_read_members

Model.hook_after_read_members(**kwargs): Called in read, after read_members and before check_numbytes.

hook_before_postprocess

Model.hook_before_postprocess(**kwargs): Called in read, after check_numbytes and before postprocess.

to_writable

Model.to_writable()

Parameters:: obj (uproot.Model instance of the same C++ class) – The object to convert to this class version.

Returns a writable version of this object or raises a NotImplementedError if no writable version exists.

serialize

Model.serialize(name=None)

Serialize a object (from num_bytes and version onward) for writing into an output ROOT file.

If a name is given, override the object’s current name.

This method has not been implemented on all classes (raises NotImplementedError).

to_pyroot

Model.to_pyroot(name=None)

Parameters:: name (str or None) – A name for the new PyROOT object.

Converts this uproot.Model into a PyROOT object if it is writable. A minority of Uproot models are writable, mostly just histograms. Writability is necessary for conversion to PyROOT because it is serialized through a ROOT TMessage.