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
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 theorigin
orother
; 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
skip
skip_after
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 Pythonfloat
.
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 Pythonfloat
.
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
anddtype
.
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
rntuple_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 withskip_bytes
, which determines which bytes are shown at all. Anyoffset
values that are equivalent modulodtype.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"
andoffset=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