uproot.Cursor

Defined in uproot.source.cursor on line 31.

class uproot.source.cursor.Cursor(index: int, origin: int = 0, refs: dict | None = None)
Parameters:

Represents a seek point in a ROOT file, which may be held for later reference or advanced while interpreting data from a uproot.source.chunk.Chunk.

A cursor also holds references to previously read data that might be requested by uproot.deserialization.read_object_any.

index

Cursor.index

Global seek position in the ROOT file or local position in an uncompressed uproot.source.chunk.Chunk.

origin

Cursor.origin

Zero-point for numerical keys in refs.

refs

Cursor.refs

References to data already read in uproot.deserialization.read_object_any.

displacement

Cursor.displacement(other: Cursor | None = None) int

The number of bytes between this uproot.Cursor and its origin (if None) or the other uproot.Cursor (if provided).

If the displacement is positive, self is later in the file than the origin or other; if negative, it is earlier.

copy

Cursor.copy(link_refs: bool = True) Cursor

Returns a copy of this uproot.Cursor. If link_refs is True, any refs will be referenced, rather than copied.

move_to

Cursor.move_to(index: int)

Move the index to a specified seek position.

skip

Cursor.skip(num_bytes: int)

Move the index forward num_bytes.

skip_after

Cursor.skip_after(obj)

Move the index just after an object that has a starting obj.cursor and an expected obj.num_bytes.

skip_over

Cursor.skip_over(chunk: Chunk, context: dict)
Parameters:

Move the index to a seek position beyond the serialized data for an object that can be interpreted with uproot.deserialization.numbytes_version.

Returns True if successful (cursor has moved), False otherwise (cursor has NOT moved).

fields

Cursor.fields(chunk: Chunk, format: Struct, context: dict, move: bool = True)
Parameters:
  • chunk (uproot.source.chunk.Chunk) – Buffer of contiguous data from the file uproot.source.chunk.Source.

  • format (struct.Struct) – Specification to interpret the bytes of data.

  • context (dict) – Auxiliary data used in deserialization.

  • move (bool) – If True, move the index past the fields; otherwise, leave it where it is.

Interpret data at this index with a specified format. Returns a tuple of data whose types and length are determined by the format.

field

Cursor.field(chunk: Chunk, format: Struct, context: dict, move: bool = True)
Parameters:
  • chunk (uproot.source.chunk.Chunk) – Buffer of contiguous data from the file uproot.source.chunk.Source.

  • format (struct.Struct) – Specification to interpret the bytes of data.

  • context (dict) – Auxiliary data used in deserialization.

  • move (bool) – If True, move the index past the fields; otherwise, leave it where it is.

Interpret data at this index with a format that only specifies one field, returning a single item instead of a tuple.

double32

Cursor.double32(chunk: Chunk, context: dict, move: bool = True) float
Parameters:

Interpret data at this index as ROOT’s Double32_t type, returning the Python float.

float16

Cursor.float16(chunk: Chunk, num_bits: int, context: dict, move: bool = True) float
Parameters:
  • chunk (uproot.source.chunk.Chunk) – Buffer of contiguous data from the file uproot.source.chunk.Source.

  • num_bits (int) – Number of bits in the mantissa.

  • context (dict) – Auxiliary data used in deserialization.

  • move (bool) – If True, move the index past the fields; otherwise, leave it where it is.

Interpret data at this index as ROOT’s Float16_t type, returning the Python float.

byte

Cursor.byte(chunk: Chunk, context: dict, move: bool = True)
Parameters:

Interpret data at this index as a raw byte.

bytes

Cursor.bytes(chunk, length, context, move=True)
Parameters:
  • chunk (uproot.source.chunk.Chunk) – Buffer of contiguous data from the file uproot.source.chunk.Source.

  • length (int) – Number of bytes to retrieve.

  • context (dict) – Auxiliary data used in deserialization.

  • move (bool) – If True, move the index past the fields; otherwise, leave it where it is.

Interpret data at this index as raw bytes with a given length.

array

Cursor.array(chunk: Chunk, length: int, dtype: dtype, context: dict, move: bool = True) ndarray
Parameters:
  • chunk (uproot.source.chunk.Chunk) – Buffer of contiguous data from the file uproot.source.chunk.Source.

  • length (int) – Number of bytes to retrieve.

  • dtype (numpy.dtype) – Data type for the array.

  • context (dict) – Auxiliary data used in deserialization.

  • move (bool) – If True, move the index past the fields; otherwise, leave it where it is.

Interpret data at this index as a one-dimensional array with a given length and dtype.

bytestring

Cursor.bytestring(chunk: Chunk, context: dict, move: bool = True) bytes
Parameters:

Interpret data at this index as a bytestring.

The first byte is taken to be the length of the subsequent string unless it is equal to 255, in which case, the next 4 bytes are taken to be an numpy.int32 length.

string

Cursor.string(chunk: Chunk, context: dict, move: bool = True) str
Parameters:

Interpret data at this index as a UTF-8 encoded string.

The first byte is taken to be the length of the subsequent string unless it is equal to 255, in which case, the next 4 bytes are taken to be an numpy.int32 length.

bytestring_with_length

Cursor.bytestring_with_length(chunk: Chunk, context: dict, length: int, move: bool = True) bytes
Parameters:
  • chunk (uproot.source.chunk.Chunk) – Buffer of contiguous data from the file uproot.source.chunk.Source.

  • context (dict) – Auxiliary data used in deserialization.

  • length (int) – Number of bytes in the bytestring.

  • move (bool) – If True, move the index past the fields; otherwise, leave it where it is.

Interpret data at this index as a bytestring.

string_with_length

Cursor.string_with_length(chunk: Chunk, context: dict, length: int, move: bool = True) str
Parameters:
  • chunk (uproot.source.chunk.Chunk) – Buffer of contiguous data from the file uproot.source.chunk.Source.

  • context (dict) – Auxiliary data used in deserialization.

  • length (int) – Number of bytes in the string.

  • move (bool) – If True, move the index past the fields; otherwise, leave it where it is.

Interpret data at this index as a UTF-8 encoded string.

classname

Cursor.classname(chunk: Chunk, context: dict, move: bool = True) str
Parameters:

Interpret data at this index as a null-terminated, UTF-8 encoded string.

rntuple_string

Cursor.rntuple_string(chunk: Chunk, context: dict, move: bool = True) str

rntuple_datetime

Cursor.rntuple_datetime(chunk: Chunk, context: dict, move: bool = True) datetime

debug

Cursor.debug(chunk: uproot.source.chunk.Chunk, context: dict = {}, limit_bytes: int | None = None, dtype: numpy.dtype = None, offset: int = 0, stream=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)
Parameters:
  • chunk (uproot.source.chunk.Chunk) – Data to examine.

  • context (dict) – Auxiliary data used in deserialization.

  • limit_bytes (None or int) – Number of bytes to limit the output to. A line of debugging output (without any offset) is 20 bytes, so multiples of 20 show full lines. If None, everything is shown to the end of the uproot.source.chunk.Chunk, which might be large.

  • dtype (None, numpy.dtype, or its constructor argument) – If None, present only the bytes as decimal values (0-255). Otherwise, also interpret them as an array of a given NumPy type.

  • offset (int) – Number of bytes to skip before interpreting a dtype; can be helpful if the numerical values are out of phase with the first byte shown. Not to be confused with skip_bytes, which determines which bytes are shown at all. Any offset values that are equivalent modulo dtype.itemsize show equivalent interpretations.

  • stream (object with a write(str) method) – Stream to write the debugging output to.

Peek at data by printing it to the stream (usually stdout). The data are always presented as decimal bytes and ASCII characters, but may also be interpreted as numbers.

Example output with dtype=">f4" and offset=3.

--+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+-
123 123 123  63 140 204 205  64  12 204 205  64  83  51  51  64 140 204 205  64
  {   {   {   ? --- --- ---   @ --- --- ---   @   S   3   3   @ --- --- ---   @
                        1.1             2.2             3.3             4.4
    --+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+-
    176   0   0  64 211  51  51  64 246 102 102  65  12 204 205  65  30 102 102  66
    --- --- ---   @ ---   3   3   @ ---   f   f   A --- --- ---   A ---   f   f   B
            5.5             6.6             7.7             8.8             9.9
    --+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+-
    202   0   0  67  74   0   0  67 151 128   0 123 123
    --- --- ---   C   J --- ---   C --- --- ---   {   {
          101.0           202.0           303.0