[wip] Add tests for checking and documenting behavior on files containing only subset collections

include/podio/RNTupleReader.h

@@ -2,6 +2,7 @@
 #define PODIO_RNTUPLEREADER_H
 
 #include "podio/ROOTFrameData.h"
+#include "podio/ReadOptions.h"
 #include "podio/podioVersion.h"
 #include "podio/utilities/DatamodelRegistryIOHelpers.h"
 #include "podio/utilities/RootHelpers.h"
@@ -75,8 +76,22 @@ class RNTupleReader {
   /// @throws std::invalid_argument in case collsToRead contains collection
   /// names that are not available
   std::unique_ptr<podio::ROOTFrameData> readNextEntry(const std::string& name,
-                                                      const std::vector<std::string>& collsToRead = {});
+                                                      const std::vector<std::string>& collsToRead);
 
+  /// Read the next data entry for a given category.
+  ///
+  /// @param name The category name for which to read the next entry
+  /// @param readOptions Options for configuring the read operation, including
+  ///                    which collections to read and whether to skip unreadable ones
+  ///
+  /// @returns FrameData from which a podio::Frame can be constructed if the
+  ///          category exists and if there are still entries left to read.
+  ///          Otherwise a nullptr
+  ///
+  /// @throws std::invalid_argument in case readOptions.collsToRead contains collection
+  /// names that are not available
+  std::unique_ptr<podio::ROOTFrameData> readNextEntry(const std::string& name,
+                                                      const podio::ReadOptions& readOptions = {});
   /// Read the desired data entry for a given category.
   ///
   /// @param name  The category name for which to read the next entry
@@ -90,7 +105,22 @@ class RNTupleReader {
   /// @throws std::invalid_argument in case collsToRead contains collection
   /// names that are not available
   std::unique_ptr<podio::ROOTFrameData> readEntry(const std::string& name, const unsigned entry,
-                                                  const std::vector<std::string>& collsToRead = {});
+                                                  const std::vector<std::string>& collsToRead);
+
+  /// Read the desired data entry for a given category.
+  ///
+  /// @param name  The category name for which to read the next entry
+  /// @param entry The entry number to read
+  /// @param readOptions Options for configuring the read operation, including
+  ///                    which collections to read and whether to skip unreadable ones
+  ///
+  /// @returns FrameData from which a podio::Frame can be constructed if the
+  ///          category and the desired entry exist. Otherwise a nullptr
+  ///
+  /// @throws std::invalid_argument in case readOptions.collsToRead contains collection
+  /// names that are not available
+  std::unique_ptr<podio::ROOTFrameData> readEntry(const std::string& name, const unsigned entry,
+                                                  const podio::ReadOptions& readOptions = {});
 
   /// Get the names of all the available Frame categories in the current file(s).
   ///

include/podio/ROOTReader.h

@@ -2,6 +2,7 @@
 #define PODIO_ROOTREADER_H
 
 #include "podio/ROOTFrameData.h"
+#include "podio/ReadOptions.h"
 #include "podio/podioVersion.h"
 #include "podio/utilities/DatamodelRegistryIOHelpers.h"
 #include "podio/utilities/RootHelpers.h"
@@ -89,7 +90,22 @@ class ROOTReader {
   /// @throws std::invalid_argument in case collsToRead contains collection
   /// names that are not available
   std::unique_ptr<podio::ROOTFrameData> readNextEntry(const std::string& name,
-                                                      const std::vector<std::string>& collsToRead = {});
+                                                      const std::vector<std::string>& collsToRead);
+
+  /// Read the next data entry for a given category.
+  ///
+  /// @param name The category name for which to read the next entry
+  /// @param readOptions Options for configuring the read operation, including
+  ///                    which collections to read and whether to skip unreadable ones
+  ///
+  /// @returns FrameData from which a podio::Frame can be constructed if the
+  ///          category exists and if there are still entries left to read.
+  ///          Otherwise a nullptr
+  ///
+  /// @throws std::invalid_argument in case readOptions.collsToRead contains collection
+  /// names that are not available
+  std::unique_ptr<podio::ROOTFrameData> readNextEntry(const std::string& name,
+                                                      const podio::ReadOptions& readOptions = {});
 
   /// Read the desired data entry for a given category.
   ///
@@ -104,7 +120,22 @@ class ROOTReader {
   /// @throws std::invalid_argument in case collsToRead contains collection
   /// names that are not available
   std::unique_ptr<podio::ROOTFrameData> readEntry(const std::string& name, const unsigned entry,
-                                                  const std::vector<std::string>& collsToRead = {});
+                                                  const std::vector<std::string>& collsToRead);
+
+  /// Read the desired data entry for a given category.
+  ///
+  /// @param name  The category name for which to read the next entry
+  /// @param entry The entry number to read
+  /// @param readOptions Options for configuring the read operation, including
+  ///                    which collections to read and whether to skip unreadable ones
+  ///
+  /// @returns FrameData from which a podio::Frame can be constructed if the
+  ///          category and the desired entry exist. Otherwise a nullptr
+  ///
+  /// @throws std::invalid_argument in case readOptions.collsToRead contains collection
+  /// names that are not available
+  std::unique_ptr<podio::ROOTFrameData> readEntry(const std::string& name, const unsigned entry,
+                                                  const podio::ReadOptions& readOptions = {});
 
   /// Get the number of entries for the given name
   ///
@@ -192,11 +223,11 @@ class ROOTReader {
   /// counter afterwards. In case the requested entry is larger than the
   /// available number of entries, return a nullptr.
   std::unique_ptr<podio::ROOTFrameData> readEntry(ROOTReader::CategoryInfo& catInfo,
-                                                  const std::vector<std::string>& collsToRead);
+                                                  const podio::ReadOptions& readOptions);
 
   /// Get / read the buffers at index iColl in the passed category information
-  podio::CollectionReadBuffers getCollectionBuffers(CategoryInfo& catInfo, size_t iColl, bool reloadBranches,
-                                                    unsigned int localEntry);
+  std::optional<podio::CollectionReadBuffers> getCollectionBuffers(CategoryInfo& catInfo, size_t iColl,
+                                                                   bool reloadBranches, unsigned int localEntry);
 
   std::unique_ptr<TChain> m_metaChain{nullptr};                 ///< The metadata tree
   std::unordered_map<std::string, CategoryInfo> m_categories{}; ///< All categories

include/podio/ReadOptions.h

@@ -0,0 +1,29 @@
+#ifndef PODIO_READOPTIONS_H
+#define PODIO_READOPTIONS_H
+
+#include <string>
+#include <vector>
+
+namespace podio {
+
+/// Options for configuring read operations
+struct ReadOptions {
+  /// Collections to read. If empty, all collections will be read
+  std::vector<std::string> collsToRead{};
+  /// Whether to skip collections that cannot be read
+  bool skipUnreadable{false};
+
+  /// Create ReadOptions that skip unreadable collections
+  inline static ReadOptions SkipUnreadable() {
+    return {{}, true};
+  }
+
+  /// Create ReadOptions that only read specific collections
+  /// @param collections list of collection names to read
+  inline static ReadOptions Only(std::vector<std::string> collections) {
+    return {std::move(collections), false};
+  }
+};
+} // namespace podio
+
+#endif

include/podio/Reader.h

@@ -2,6 +2,7 @@
 #define PODIO_READER_H
 
 #include "podio/Frame.h"
+#include "podio/ReadOptions.h"
 #include "podio/podioVersion.h"
 
 namespace podio {
@@ -22,8 +23,8 @@ class Reader {
   struct ReaderConcept {
     virtual ~ReaderConcept() = default;
 
-    virtual podio::Frame readNextFrame(const std::string& name, const std::vector<std::string>&) = 0;
-    virtual podio::Frame readFrame(const std::string& name, size_t index, const std::vector<std::string>&) = 0;
+    virtual podio::Frame readNextFrame(const std::string& name, const podio::ReadOptions& readOptions) = 0;
+    virtual podio::Frame readFrame(const std::string& name, size_t index, const podio::ReadOptions& readOptions) = 0;
     virtual size_t getEntries(const std::string& name) const = 0;
     virtual podio::version::Version currentFileVersion() const = 0;
     virtual std::optional<podio::version::Version> currentFileVersion(const std::string& name) const = 0;
@@ -44,17 +45,16 @@ class Reader {
 
     ~ReaderModel() override = default;
 
-    podio::Frame readNextFrame(const std::string& name, const std::vector<std::string>& collsToRead) override {
-      auto maybeFrame = m_reader->readNextEntry(name, collsToRead);
+    podio::Frame readNextFrame(const std::string& name, const podio::ReadOptions& readOptions) override {
+      auto maybeFrame = m_reader->readNextEntry(name, readOptions);
       if (maybeFrame) {
         return maybeFrame;
       }
       throw std::runtime_error("Failed reading category " + name + " (reading beyond bounds?)");
     }
 
-    podio::Frame readFrame(const std::string& name, size_t index,
-                           const std::vector<std::string>& collsToRead) override {
-      auto maybeFrame = m_reader->readEntry(name, index, collsToRead);
+    podio::Frame readFrame(const std::string& name, size_t index, const podio::ReadOptions& readOptions) override {
+      auto maybeFrame = m_reader->readEntry(name, index, readOptions);
       if (maybeFrame) {
         return maybeFrame;
       }
@@ -113,8 +113,22 @@ class Reader {
   ///
   /// @throws std::invalid_argument in case the category is not available or in
   ///         case no more entries are available
-  podio::Frame readNextFrame(const std::string& name, const std::vector<std::string>& collsToRead = {}) {
-    return m_self->readNextFrame(name, collsToRead);
+  podio::Frame readNextFrame(const std::string& name, const std::vector<std::string>& collsToRead) {
+    return m_self->readNextFrame(name, podio::ReadOptions::Only(collsToRead));
+  }
+
+  /// Read the next frame of a given category
+  ///
+  /// @param name The category name for which to read the next frame
+  /// @param readOptions Options for configuring the read operation, including
+  ///                    which collections to read and whether to skip unreadable ones
+  ///
+  /// @returns A fully constructed Frame with the contents read from file
+  ///
+  /// @throws std::invalid_argument in case the category is not available or in
+  ///         case no more entries are available
+  podio::Frame readNextFrame(const std::string& name, const podio::ReadOptions& readOptions = {}) {
+    return m_self->readNextFrame(name, readOptions);
   }
 
   /// Read the next frame of the "events" category
@@ -125,8 +139,20 @@ class Reader {
   /// @returns A fully constructed Frame with the contents read from file
   ///
   /// @throws std::invalid_argument in case no (more) events are available
-  podio::Frame readNextEvent(const std::vector<std::string>& collsToRead = {}) {
-    return readNextFrame(podio::Category::Event, collsToRead);
+  podio::Frame readNextEvent(const std::vector<std::string>& collsToRead) {
+    return readNextFrame(podio::Category::Event, podio::ReadOptions::Only(collsToRead));
+  }
+
+  /// Read the next frame of the "events" category
+  ///
+  /// @param readOptions Options for configuring the read operation, including
+  ///                    which collections to read and whether to skip unreadable ones
+  ///
+  /// @returns A fully constructed Frame with the contents read from file
+  ///
+  /// @throws std::invalid_argument in case no (more) events are available
+  podio::Frame readNextEvent(const podio::ReadOptions& readOptions = {}) {
+    return readNextFrame(podio::Category::Event, readOptions);
   }
 
   /// Read a specific frame for a given category
@@ -140,8 +166,23 @@ class Reader {
   ///
   /// @throws std::invalid_argument in case the category is not available or in
   ///         case the specified entry is not available
-  podio::Frame readFrame(const std::string& name, size_t index, const std::vector<std::string>& collsToRead = {}) {
-    return m_self->readFrame(name, index, collsToRead);
+  podio::Frame readFrame(const std::string& name, size_t index, const std::vector<std::string>& collsToRead) {
+    return m_self->readFrame(name, index, podio::ReadOptions::Only(collsToRead));
+  }
+
+  /// Read a specific frame for a given category
+  ///
+  /// @param name  The category name for which to read the next entry
+  /// @param index The entry number to read
+  /// @param readOptions Options for configuring the read operation, including
+  ///                    which collections to read and whether to skip unreadable ones
+  ///
+  /// @returns A fully constructed Frame with the contents read from file
+  ///
+  /// @throws std::invalid_argument in case the category is not available or in
+  ///         case the specified entry is not available
+  podio::Frame readFrame(const std::string& name, size_t index, const podio::ReadOptions& readOptions = {}) {
+    return m_self->readFrame(name, index, readOptions);
   }
 
   /// Read a specific frame of the "events" category
@@ -153,8 +194,21 @@ class Reader {
   /// @returns A fully constructed Frame with the contents read from file
   ///
   /// @throws std::invalid_argument in case the desired event is not available
-  podio::Frame readEvent(size_t index, const std::vector<std::string>& collsToRead = {}) {
-    return readFrame(podio::Category::Event, index, collsToRead);
+  podio::Frame readEvent(size_t index, const std::vector<std::string>& collsToRead) {
+    return readFrame(podio::Category::Event, index, podio::ReadOptions::Only(collsToRead));
+  }
+
+  /// Read a specific frame of the "events" category
+  ///
+  /// @param index The event number to read
+  /// @param readOptions Options for configuring the read operation, including
+  ///                    which collections to read and whether to skip unreadable ones
+  ///
+  /// @returns A fully constructed Frame with the contents read from file
+  ///
+  /// @throws std::invalid_argument in case the desired event is not available
+  podio::Frame readEvent(size_t index, const podio::ReadOptions& readOptions = {}) {
+    return readFrame(podio::Category::Event, index, readOptions);
   }
 
   /// Get the number of entries for the given name

include/podio/SIOReader.h

@@ -1,6 +1,7 @@
 #ifndef PODIO_SIOREADER_H
 #define PODIO_SIOREADER_H
 
+#include "podio/ReadOptions.h"
 #include "podio/SIOBlock.h"
 #include "podio/SIOFrameData.h"
 #include "podio/podioVersion.h"
@@ -51,7 +52,25 @@ class SIOReader {
   ///          category exists and if there are still entries left to read.
   ///          Otherwise a nullptr
   std::unique_ptr<podio::SIOFrameData> readNextEntry(const std::string& name,
-                                                     const std::vector<std::string>& collsToRead = {});
+                                                     const std::vector<std::string>& collsToRead);
+
+  /// Read the next data entry for a given category.
+  ///
+  /// @note Given how the SIO files are currently laid out it is in fact not
+  /// possible to only read a subset of a Frame. Rather the subset of
+  /// collections to read will be an artificial limit on the returned
+  /// SIOFrameData. Limiting the collections to read will not improve I/O
+  /// performance.
+  ///
+  /// @param name The category name for which to read the next entry
+  /// @param readOptions Options for configuring the read operation, including
+  ///                    which collections to read and whether to skip unreadable ones
+  ///
+  /// @returns FrameData from which a podio::Frame can be constructed if the
+  ///          category exists and if there are still entries left to read.
+  ///          Otherwise a nullptr
+  std::unique_ptr<podio::SIOFrameData> readNextEntry(const std::string& name,
+                                                     const podio::ReadOptions& readOptions = {});
 
   /// Read the desired data entry for a given category.
   ///
@@ -69,7 +88,25 @@ class SIOReader {
   /// @returns FrameData from which a podio::Frame can be constructed if the
   ///          category and the desired entry exist. Otherwise a nullptr
   std::unique_ptr<podio::SIOFrameData> readEntry(const std::string& name, const unsigned entry,
-                                                 const std::vector<std::string>& collsToRead = {});
+                                                 const std::vector<std::string>& collsToRead);
+
+  /// Read the desired data entry for a given category.
+  ///
+  /// @note Given how the SIO files are currently laid out it is in fact not
+  /// possible to only read a subset of a Frame. Rather the subset of
+  /// collections to read will be an artificial limit on the returned
+  /// SIOFrameData. Limiting the collections to read will not improve I/O
+  /// performance.
+  ///
+  /// @param name  The category name for which to read the next entry
+  /// @param entry The entry number to read
+  /// @param readOptions Options for configuring the read operation, including
+  ///                    which collections to read and whether to skip unreadable ones
+  ///
+  /// @returns FrameData from which a podio::Frame can be constructed if the
+  ///          category and the desired entry exist. Otherwise a nullptr
+  std::unique_ptr<podio::SIOFrameData> readEntry(const std::string& name, const unsigned entry,
+                                                 const podio::ReadOptions& readOptions = {});
 
   /// Get the number of entries for the given name
   ///

python/podio/__init__.py

@@ -27,4 +27,15 @@
 except ImportError:
     pass
 
-__all__ = ["__version__", "Frame", "root_io", "sio_io", "reading", "data_source", "version"]
+ReadOptions = podio.ReadOptions
+
+__all__ = [
+    "__version__",
+    "Frame",
+    "root_io",
+    "sio_io",
+    "reading",
+    "data_source",
+    "version",
+    "ReadOptions",
+]