uproot.Cursor — Uproot documentation

# 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:

    - index (int) – Global seek position in the ROOT file or local position in an uncompressed uproot.source.chunk.Chunk.

    - origin (int) – Zero-point for numerical keys in `refs`.

    - refs (None or dict) – References to data already read in uproot.deserialization.read_object_any.

  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) → 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:

    - chunk (uproot.source.chunk.Chunk) – Buffer of contiguous data from the file uproot.source.chunk.Source.

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

  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:

    - chunk (uproot.source.chunk.Chunk) – Buffer of contiguous data from the file uproot.source.chunk.Source.

    - 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 `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:

    - chunk (uproot.source.chunk.Chunk) – Buffer of contiguous data from the file uproot.source.chunk.Source.

    - 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 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:

    - chunk (uproot.source.chunk.Chunk) – Buffer of contiguous data from the file uproot.source.chunk.Source.

    - 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 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:

    - chunk (uproot.source.chunk.Chunk) – Buffer of contiguous data from the file uproot.source.chunk.Source.

    - 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 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:

    - chunk (uproot.source.chunk.Chunk) – Buffer of contiguous data from the file uproot.source.chunk.Source.

    - 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 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