podio package

Subpackages

• podio.pythonizations package
  • Subpackages
    • podio.pythonizations.utils package
      • Submodules
      • podio.pythonizations.utils.pythonizer module
      • Module contents
  • Submodules
  • podio.pythonizations.collection_subscript module
    • CollectionSubscriptPythonizer
      • CollectionSubscriptPythonizer.filter()
      • CollectionSubscriptPythonizer.modify()
      • CollectionSubscriptPythonizer.priority()
  • podio.pythonizations.freeze_class module
    • FreezeClassPythonizer
      • FreezeClassPythonizer.filter()
      • FreezeClassPythonizer.modify()
      • FreezeClassPythonizer.priority()
  • Module contents
    • load_pythonizations()

Submodules

podio.base_reader module

Python module for defining the basic reader interface that is used by the backend specific bindings

class podio.base_reader.BaseReaderMixin

Bases: object

Mixin class the defines the base interface of the readers.

The backend specific readers inherit from here and have to initialize the following members: - _reader: The actual reader that is able to read frames

Initialize common members.

In inheriting classes this needs to be called after the _reader has been setup.

property categories

Get the available categories from this reader.

Returns:

The names of the available categories from this reader

Return type:

tuple(str)

current_file_version(edm_name=None)

Get the (build) version that was used to write this file

If called without argument or None, the podio build version is returned otherwise the build version of the datamodel

Parameters:

edm_name (str, optional) – The package name of the datamodel

Returns:

The build version of podio or the build

version of the datamodel (if available) that was used to write this file

Return type:

podio.version.Version

Raises:

• KeyError – If the datamodel does not have a version stored

• RuntimeError – If the reader is a legacy reader and a datamodel version is requested

property datamodel_definitions

Get the available datamodel definitions from this reader.

Returns:

The names of the available datamodel definitions

Return type:

tuple(str)

get(category, coll_names=None)

Get an iterator with access functionality for a given category.

Parameters:

• category (str) – The name of the desired category

• coll_names (list[str]) – The list of collections to read (optional, all available collections will by default)

Returns:

The iterator granting access to all Frames of the

desired category

Return type:

FrameCategoryIterator

get_datamodel_definition(edm_name)

Get the datamodel definition as JSON string.

Parameters:

str – The name of the datamodel

Returns:

The complete model definition in JSON format. Use, e.g. json.loads

to convert it into a python dictionary.

Return type:

str

property is_legacy

Whether this is a legacy file reader or not.

Returns:

True if this is a legacy file reader

Return type:

bool

podio.base_writer module

Python module for defining the basic writer interface that is used by the backend specific bindings

class podio.base_writer.AllWriters

Bases: object

Class to manage all writers in the program so that they can be properly finished at the end of the program

add(writer)

Add a writer to the list of managed writers

finish()

Finish all managed writers

writers = []

class podio.base_writer.BaseWriterMixin

Bases: object

Mixin class that defines the base interface of the writers.

The backend specific writers inherit from here and have to initialize the following members:

• _writer: The actual writer that is able to write frames

Initialize the writer

write_frame(frame, category, collections=None)

Write the given frame under the passed category, optionally limiting the collections that are written.

Parameters:

• frame (podio.frame.Frame) – The Frame to write

• category (str) – The category name

• collections (optional, default=None) – The subset of collections to write. If None, all collections are written

podio.data_source module

Python module for creating ROOT RDataFrame with files containing podio Frames

podio.frame module

Module for the python bindings of the podio::Frame

class podio.frame.Frame(data=None)

Bases: object

Frame class that serves as a container of collection and meta data.

Create a Frame.

Parameters:

data (FrameData, optional) – Almost arbitrary FrameData, e.g. from file

get(name)

Get a collection from the Frame by name.

Parameters:

name (str) – The name of the desired collection

Returns:

The collection stored in the Frame

Return type:

collection (podio.CollectionBase)

Raises:

KeyError – If the collection with the name is not available

getAvailableCollections()

Get the currently available collection (names) from this Frame.

Returns:

The names of the available collections from this Frame.

Return type:

tuple(str)

getName(token)

Get the name of the collection from the Frame

Parameters:

token (podio.CollectionBase | int) – A collection or its ID

Returns:

The name of the collection inside the frame

Return type:

str

Raises:

KeyError – If no collection can be found in the frame

get_param_info(name)

Get the parameter type information stored under the given name.

Parameters:

name (str) – The parameter name

Returns:

int): The c++-type(s) of the stored parameter and the number of

parameters

Return type:

dict (str

Raises:

KeyError – If no parameter is stored under the given name

get_parameter(name, as_type=None)

Get the parameter stored under the given name.

Parameters:

• name (str) – The name of the parameter

• as_type (str, optional) – Type specifier to disambiguate between parameters with the same name but different types. If there is only one parameter with a given name, this argument is ignored

Returns:

The value of the stored parameter

Return type:

int, float, str or list of those

Raises:

• KeyError – If no parameter is stored under the given name

• ValueError – If there are multiple parameters with the same name, but multiple types and no type specifier to disambiguate between them has been passed.

get_parameters()

Get the complete podio::GenericParameters object stored in this Frame.

Note

This is mainly intended for dumping things, for actually obtaining parameters please use get_parameter

Returns:

The stored generic parameters

Return type:

podio.GenericParameters

property parameters

Get the currently available parameter names from this Frame.

Returns:

The names of the available parameters from this Frame.

Return type:

tuple (str)

put(collection, name)

Put the collection into the frame

The passed collection is “moved” into the Frame, i.e. it cannot be used any longer after a call to this function. This also means that only objects that were in the collection at the time of calling this function will be available afterwards.

Parameters:

• collection (podio.CollectionBase) – The collection to put into the Frame

• name (str) – The name of the collection

Returns:

The reference to the collection that has been put

into the Frame.

Return type:

podio.CollectionBase

Note

Mutating the returned collection is not allowed.

Raises:

ValueError – If collection is not actually a podio.CollectionBase

put_parameter(key, value, as_type=None)

Put a parameter into the Frame.

Puts a parameter into the Frame after doing some (incomplete) type checks. If a list is passed the parameter type is determined from looking at the first element of the list only. Additionally, since python doesn’t differentiate between floats and doubles, floats will always be stored as doubles by default, use the as_type argument to change this if necessary.

Parameters:

• key (str) – The name of the parameter

• value (int, float, str or list of these) – The parameter value

• as_type (str, optional) – Explicitly specify the type that should be used to put the parameter into the Frame. Python types (e.g. “str”) will be converted to c++ types. This will override any automatic type deduction that happens otherwise. Note that this will be taken at pretty much face-value and there are only limited checks for this.

Raises:

ValueError – If a non-supported parameter type is passed

podio.frame_iterator module

Module defining the Frame iterator used by the Reader interface

class podio.frame_iterator.FrameCategoryIterator(reader, category, coll_names=None)

Bases: object

Iterator for iterating over all Frames of a given category available from a reader as well as accessing specific entries

Construct the iterator from the reader and the category.

Parameters:

• reader (Reader) – Any podio reader offering access to Frames

• category (str) – The category name of the Frames to be iterated over

• coll_names (list[str]) – The list of collections to read (optional, all available collections will by default)

podio.reading module

Module for general reading functionality.

class podio.reading.RootFileFormat

Bases: object

Enum to specify the ROOT file format

LEGACY = 2

RNTUPLE = 1

TTREE = 0

podio.reading.get_reader(filenames)

Get an appropriate reader for the passed files.

The reader is inferred from the first file if multiple are given. All files are assumed to be of the same I/O format.

Parameters:

filenames (str or list[str]) – The input file(s)

Returns:

an initialized reader that

is able to process the input file(s).

Return type:

root_io.[Legacy]Reader, sio_io.[Legacy]Reader

Raises:

• ValueError – If the files cannot be recognized, or if podio has not been built with the necessary backend I/O support

• IndexError – If filenames is an empty list

podio.root_io module

Python module for reading root files containing podio Frames

class podio.root_io.LegacyReader(filenames)

Bases: BaseReaderMixin

Reader class for reading legacy podio root files.

This reader can be used to read files that have not yet been written using Frame based I/O into Frames for a more seamless transition.

Create a reader that reads from the passed file(s).

Parameters:

filenames (str or list[str] or Path or list[Path]) – file(s) to open and read data from

class podio.root_io.RNTupleReader(filenames)

Bases: BaseReaderMixin

Reader class for reading podio RNTuple root files.

Create an RNTuple reader that reads from the passed file(s).

Parameters:

filenames (str or list[str] or Path or list[Path]) – file(s) to open and read data from

class podio.root_io.RNTupleWriter(filename)

Bases: BaseWriterMixin

Writer class for writing podio root files

Create a writer for writing files

Parameters:

filename (str or Path) – The name of the output file

class podio.root_io.Reader(filenames)

Bases: BaseReaderMixin

Reader class for reading podio root files.

Create a reader that reads from the passed file(s).

Parameters:

filenames (str or list[str] or Path or list[Path]) – file(s) to open and read data from

class podio.root_io.Writer(filename)

Bases: BaseWriterMixin

Writer class for writing podio root files

Create a writer for writing files

Parameters:

filename (str or Path) – The name of the output file

podio.sio_io module

Python module for reading sio files containing podio Frames

class podio.sio_io.LegacyReader(filename)

Bases: BaseReaderMixin

Reader class for reading legacy podio sio files.

This reader can be used to read files that have not yet been written using the Frame based I/O into Frames for a more seamless transition.

Create a reader that reads from the passed file.

Parameters:

filename (str or Path) – File to open and read data from.

class podio.sio_io.Reader(filename)

Bases: BaseReaderMixin

Reader class for reading podio SIO files.

Create a reader that reads from the passed file.

Parameters:

filename (str or Path) – File to open and read data from.

class podio.sio_io.Writer(filename)

Bases: BaseWriterMixin

Writer class for writing podio root files.

Create a writer for writing files.

Parameters:

filename (str or Path) – The name of the output file.

podio.utils module

utility functionality for podio

podio.utils.convert_to_str_paths(filenames)

Converts filenames to string paths, handling both string and pathlib.Path objects and

iterables of such objects.

Parameters:

• filenames (str, Path, or Iterable[str | Path]) – A single filepath or an iterable of

• object (filepaths to convert to str) –

Returns:

A list of filepaths as strings.

Return type:

list[str]

podio.utils.expand_glob(pattern)

Expands a given glob pattern into a list of matching file paths.

This function takes a glob pattern as input and returns a list of strings containing the paths that match the pattern. It supports standard glob rules extended with tilde expansion and brace expansion. If the pattern doesn’t contain any wildcards, it is placed in the returned list as is. Paths that cannot be accessed are displayed on stderr, but the expansion process is not aborted.

Parameters:

pattern (str) – The glob pattern to expand.

Returns:

A list of strings containing the matching file paths.

Return type:

list of str

Raises:

• cppyy.gbl.std.runtime_error – If no matches are found or if there is an error during glob

• expansion. –

podio.version module

Module that facilitates working with the podio::version::Version

podio.version.parse(*args)

Construct a version from either a list of integers or a version string

Module contents

Python module for the podio EDM toolkit and its utilities

class podio.Frame(data=None)

Bases: object

Frame class that serves as a container of collection and meta data.

Create a Frame.

Parameters:

data (FrameData, optional) – Almost arbitrary FrameData, e.g. from file

get(name)

Get a collection from the Frame by name.

Parameters:

name (str) – The name of the desired collection

Returns:

The collection stored in the Frame

Return type:

collection (podio.CollectionBase)

Raises:

KeyError – If the collection with the name is not available

getAvailableCollections()

Get the currently available collection (names) from this Frame.

Returns:

The names of the available collections from this Frame.

Return type:

tuple(str)

getName(token)

Get the name of the collection from the Frame

Parameters:

token (podio.CollectionBase | int) – A collection or its ID

Returns:

The name of the collection inside the frame

Return type:

str

Raises:

KeyError – If no collection can be found in the frame

get_param_info(name)

Get the parameter type information stored under the given name.

Parameters:

name (str) – The parameter name

Returns:

int): The c++-type(s) of the stored parameter and the number of

parameters

Return type:

dict (str

Raises:

KeyError – If no parameter is stored under the given name

get_parameter(name, as_type=None)

Get the parameter stored under the given name.

Parameters:

• name (str) – The name of the parameter

• as_type (str, optional) – Type specifier to disambiguate between parameters with the same name but different types. If there is only one parameter with a given name, this argument is ignored

Returns:

The value of the stored parameter

Return type:

int, float, str or list of those

Raises:

• KeyError – If no parameter is stored under the given name

• ValueError – If there are multiple parameters with the same name, but multiple types and no type specifier to disambiguate between them has been passed.

get_parameters()

Get the complete podio::GenericParameters object stored in this Frame.

Note

This is mainly intended for dumping things, for actually obtaining parameters please use get_parameter

Returns:

The stored generic parameters

Return type:

podio.GenericParameters

property parameters

Get the currently available parameter names from this Frame.

Returns:

The names of the available parameters from this Frame.

Return type:

tuple (str)

put(collection, name)

Put the collection into the frame

The passed collection is “moved” into the Frame, i.e. it cannot be used any longer after a call to this function. This also means that only objects that were in the collection at the time of calling this function will be available afterwards.

Parameters:

• collection (podio.CollectionBase) – The collection to put into the Frame

• name (str) – The name of the collection

Returns:

The reference to the collection that has been put

into the Frame.

Return type:

podio.CollectionBase

Note

Mutating the returned collection is not allowed.

Raises:

ValueError – If collection is not actually a podio.CollectionBase

put_parameter(key, value, as_type=None)

Put a parameter into the Frame.

Puts a parameter into the Frame after doing some (incomplete) type checks. If a list is passed the parameter type is determined from looking at the first element of the list only. Additionally, since python doesn’t differentiate between floats and doubles, floats will always be stored as doubles by default, use the as_type argument to change this if necessary.

Parameters:

• key (str) – The name of the parameter

• value (int, float, str or list of these) – The parameter value

• as_type (str, optional) – Explicitly specify the type that should be used to put the parameter into the Frame. Python types (e.g. “str”) will be converted to c++ types. This will override any automatic type deduction that happens otherwise. Note that this will be taken at pretty much face-value and there are only limited checks for this.

Raises:

ValueError – If a non-supported parameter type is passed