PyStoreArray Class Reference

A (simplified) python wrapper for StoreArray. More...

#include <PyStoreArray.h>

Public Member Functions
	PyStoreArray (const std::string &name, DataStore::EDurability durability=DataStore::EDurability::c_Event)
	constructor.
	PyStoreArray (TClass *objClass, DataStore::EDurability durability=DataStore::EDurability::c_Event)
	constructor.
	PyStoreArray (TClass *objClass, const std::string &name, DataStore::EDurability durability=DataStore::EDurability::c_Event)
	constructor.
bool	registerInDataStore (DataStore::EStoreFlags storeFlags)
	Register the array in the data store.
bool	registerInDataStore (const std::string &name="", DataStore::EStoreFlags storeFlags=DataStore::EStoreFlags::c_WriteOut)
	Register the array in the data store.
bool	isRequired (const std::string &name="")
	Ensure this array has been registered previously.
bool	isOptional (const std::string &name="")
	Tell the DataStore about an optional input.
bool	registerRelationTo (const PyStoreArray &toArray, DataStore::EDurability durability=DataStore::EDurability::c_Event, DataStore::EStoreFlags storeFlags=DataStore::EStoreFlags::c_WriteOut, std::string const &namedRelation="") const
	Register a relation to the given PyStoreArray.
bool	requireRelationTo (const PyStoreArray &toArray, DataStore::EDurability durability=DataStore::c_Event, std::string const &namedRelation="") const
	Produce error if no relation from this array to 'toArray' has been registered.
bool	optionalRelationTo (const PyStoreArray &toArray, DataStore::EDurability durability=DataStore::c_Event, std::string const &namedRelation="") const
	Tell the data store about a relation that we could make use of.
bool	hasRelationTo (const PyStoreArray &toArray, DataStore::EDurability durability=DataStore::c_Event, const std::string &namedRelation="") const
	Check for the existence of a relation to the provided toArray (from this Pystorearray)
bool	hasRelationFrom (const PyStoreArray &fromArray, DataStore::EDurability durability=DataStore::c_Event, const std::string &namedRelation="") const
	Check for the existence of a relation from the provided toArray (to this Pystorearray)
std::string	getName () const
	Return name under which the object is saved in the DataStore.
bool	hasValidClass () const
	Check whether a TClass of the objects in this PyStoreArray could be determined.
bool	isValid () const
	Check whether the array was registered and created.
	operator bool () const
	Does this PyStoreArray contain a valid datastore array?
TObject *	operator[] (int i) const
	returns object at index i, or null pointer if out of range (+error)
int	getEntries () const
	returns number of entries for current event.
int	__len__ () const
	Support for len().
TIter	__iter__ () const
	Allow iteration using for in Python.
TObject *	appendNew ()
	Construct a new object of the array's type at the end of the array.
TClonesArray *	getPtr ()
	Raw access to the underlying TClonesArray.

Static Public Member Functions
static std::vector< std::string >	list (DataStore::EDurability durability=DataStore::EDurability::c_Event)
	Return list of available arrays for given durability.
static void	printList (DataStore::EDurability durability=DataStore::EDurability::c_Event)
	Print list of available arrays for given durability.

Private Member Functions
void	ensureCreated ()
	Ensure that contained TClonesArray has been created on the DataStore.
bool	create (bool replace=false)
	Create constructed TClonesArray in the DataStore.
void	ensureAttached () const
	Ensure that contained TClonesArray has been attached to a memory location on the DataStore.
void	attach () const
	Lookup the store entry and cache a pointer to it.

Private Attributes
StoreAccessorBase	m_storeAccessor
	Store accessor to retrieve the object.
StoreEntry *	m_storeEntry = nullptr
	Pointer to the DataStore entry - serves as an internal cache omitting repeated look up from the DataStore.

Detailed Description

A (simplified) python wrapper for StoreArray.

Compared to StoreArray, PyStoreArray returns only TObject pointers (since it doesn't use templates). Thanks to Python, you can still access all public functions and data members of the actual type.

Relations can also be accessed using functions like RelationsObject::getRelationsTo() as long as the data objects are derived from RelationsObject. A full example for accessing simhits and some related objects can be found in framework/examples/cdcplotmodule.py Additional registration and filling of PyStoreArrays is demonstrated in framework/examples/register_pystorearray.py

Example:

from ROOT import Belle2
simhits = Belle2.PyStoreArray('PXDSimHits')
# Alternative: simhits = Belle2.PyStoreArray(Belle2.PXDSimHits.Class())
for hit in simhits:
  part = hit.getRelatedFrom('MCParticles')
  print("Edep: ", str(hit.getEnergyDep()))
  print("Particle: ", str(part.getPDG()))

You can check the runtime type information of the returned objects by using Python's built-in type() function.

In case you want to access a named relation (for example, from "Tracks" to "KLMClusters" with a named relation "Secondary"), you can follow the following example:

from ROOT import Belle2
tracks = Belle2.PyStoreArray('Tracks')
for tracks in tracks:
  clusters = track.getRelationsTo['KLMCluster']('KLMClusters', 'Secondary')
  for cluster in clusters:
    # Do something

The synthax is: ‘getRelationsTo['ClassName’]('StoreArrayName', 'RelationName') whereStoreArrayName` can be omitted in case of default store arrays.

See also

PyStoreObj and the Conditions Data interface classes PyDBObj and PyDBArray

Definition at line 72 of file PyStoreArray.h.

Constructor & Destructor Documentation

PyStoreArray() [1/3]

PyStoreArray ( const std::string &  name, DataStore::EDurability  durability = DataStore::EDurability::c_Event  )

explicit

constructor.

Parameters

name	Name of the entry to be accessed
durability	0: event, 1: persistent

Definition at line 40 of file PyStoreArray.cc.

                                                           :
  PyStoreArray(replaceNullPtr(DataStore::getTClassFromDefaultArrayName(name),
                              TObject::Class()),
               /* Default to TObject for unknown class for backwards compatability */
               name,
               durability)
{
}

PyStoreArray() [2/3]

PyStoreArray ( TClass *  objClass, DataStore::EDurability  durability = DataStore::EDurability::c_Event  )

explicit

constructor.

Parameters

objClass	Class of the object to be accessed
durability	0: event, 1: persistent

Definition at line 50 of file PyStoreArray.cc.

                                                            :
  PyStoreArray(objClass, DataStore::defaultArrayName(objClass), durability)
{
}

PyStoreArray() [3/3]

PyStoreArray ( TClass *  objClass, const std::string &  name, DataStore::EDurability  durability = DataStore::EDurability::c_Event  )

explicit

constructor.

Parameters

objClass	Class of the object to be accessed
name	Name of the entry to be accessed
durability	0: event, 1: persistent

Definition at line 56 of file PyStoreArray.cc.

                                                            :
  m_storeAccessor(name, durability, objClass, true)
{
  attach();
}

Member Function Documentation

__iter__()

TIter __iter__

(

)

const

Allow iteration using for in Python.

Definition at line 171 of file PyStoreArray.cc.

{
  ensureAttached();
  // will create empty iterator if nullptr
  return TIter(isValid() ? m_storeEntry->getPtrAsArray() : nullptr);
}

__len__()

int __len__ ( ) const

inline

Support for len().

Definition at line 222 of file PyStoreArray.h.

{ return getEntries(); }

appendNew()

TObject * appendNew

(

)

Construct a new object of the array's type at the end of the array.

Returns

the created object, to be modified by the user

Definition at line 178 of file PyStoreArray.cc.

{
  ensureCreated();
  if (isValid()) {
    return getPtr()->ConstructedAt(getEntries());
  } else {
    B2ERROR("Cannot create an object in invalid PyStoreArray.");
    return nullptr;
  }
}

attach()

void attach ( ) const

private

Lookup the store entry and cache a pointer to it.

Definition at line 232 of file PyStoreArray.cc.

{
  m_storeEntry = DataStore::Instance().getEntry(m_storeAccessor);
}

create()

bool create ( bool  replace = false )

private

Create constructed TClonesArray in the DataStore.

Parameters

replace

Should an existing object be replaced?

Returns

True if the creation succeeded.

Definition at line 200 of file PyStoreArray.cc.

{
  ensureAttached();
  if (not m_storeEntry) {
    // Attaching failed
    B2ERROR("Cannot create unregistered PyStoreArray.");
    return false;
  }
 
  // Short cut when an array has been created and no replacement is requested.
  if (isValid() and not replace) return true;
 
  if (not isValid() and not hasValidClass()) {
    B2ERROR("Cannot create PyStoreArray with unknown TClass.");
    return false;
  } else {
    // Array has been created before or has a valid class
    // Go ahead and (re)create it
    return m_storeAccessor.create(replace);
  }
}

ensureAttached()

void ensureAttached ( ) const

private

Ensure that contained TClonesArray has been attached to a memory location on the DataStore.

Definition at line 222 of file PyStoreArray.cc.

{
  if (not m_storeEntry) {
    attach();
    if (not m_storeEntry) {
      B2ERROR("PyStoreArray " << m_storeAccessor.readableName() << " has not been registered!");
    }
  }
}

ensureCreated()

void ensureCreated ( )

private

Ensure that contained TClonesArray has been created on the DataStore.

Definition at line 195 of file PyStoreArray.cc.

{
  create(false);
}

getEntries()

int getEntries

(

)

const

returns number of entries for current event.

Definition at line 165 of file PyStoreArray.cc.

{
  ensureAttached();
  return isValid() ? (m_storeEntry->getPtrAsArray()->GetEntriesFast()) : 0;
}

getName()

std::string getName ( ) const

inline

Return name under which the object is saved in the DataStore.

Definition at line 203 of file PyStoreArray.h.

{ return m_storeAccessor.getName(); }

getPtr()

TClonesArray * getPtr

(

)

Raw access to the underlying TClonesArray.

Warning

TClonesArray is dangerously easy to misuse. Whatever you do will probably be slow, leak memory, and murder your pets. In most cases, you'll want to use functions like operator[], getEntries() or appendNew() instead.

Definition at line 189 of file PyStoreArray.cc.

{
  ensureCreated();
  return isValid() ? m_storeEntry->getPtrAsArray() : nullptr;
}

hasRelationFrom()

bool hasRelationFrom	(	const PyStoreArray &	fromArray,
		DataStore::EDurability	durability = DataStore::c_Event,
		const std::string &	namedRelation = ""
	)		const

Check for the existence of a relation from the provided toArray (to this Pystorearray)

Parameters

fromArray	Array the relation should point to (from this StoreArray)
durability	Durability of the relation.
namedRelation	Additional name for the relation, or "" for the default naming

Definition at line 134 of file PyStoreArray.cc.

{
  return DataStore::Instance().hasRelation(fromArray.m_storeAccessor,
                                           this->m_storeAccessor,
                                           durability,
                                           namedRelation);
}

hasRelationTo()

bool hasRelationTo	(	const PyStoreArray &	toArray,
		DataStore::EDurability	durability = DataStore::c_Event,
		const std::string &	namedRelation = ""
	)		const

Check for the existence of a relation to the provided toArray (from this Pystorearray)

Parameters

toArray	Array the relation should point to (from this StoreArray)
durability	Durability of the relation.
namedRelation	Additional name for the relation, or "" for the default naming

Definition at line 124 of file PyStoreArray.cc.

{
  return DataStore::Instance().hasRelation(this->m_storeAccessor,
                                           toArray.m_storeAccessor,
                                           durability,
                                           namedRelation);
}

hasValidClass()

bool hasValidClass

(

)

const

Check whether a TClass of the objects in this PyStoreArray could be determined.

Definition at line 144 of file PyStoreArray.cc.

{
  const TClass* objClass = m_storeAccessor.getClass();
  return objClass and objClass != TObject::Class();
}

isOptional()

bool isOptional

(

const std::string &

name = ""

)

Tell the DataStore about an optional input.

Mainly useful for creating diagrams of module inputs and outputs. This must be called in the initialization phase.

Parameters

name	If not empty, use non-default name for this array.

Returns

True if the array exists.

Definition at line 87 of file PyStoreArray.cc.

{
  return m_storeAccessor.isOptional(name);
}

isRequired()

bool isRequired

(

const std::string &

name = ""

)

Ensure this array has been registered previously.

Will cause an ERROR if it does not exist. This must be called in the initialization phase.

Parameters

name	If not empty, use non-default name for this array.

Returns

True if the array exists.

Definition at line 82 of file PyStoreArray.cc.

{
  return m_storeAccessor.isRequired(name);
}

isValid()

bool isValid

(

)

const

Check whether the array was registered and created.

Definition at line 150 of file PyStoreArray.cc.

{
  return m_storeEntry and m_storeEntry->ptr;
}

list()

std::vector< std::string > list ( DataStore::EDurability  durability = DataStore::EDurability::c_Event )

static

Return list of available arrays for given durability.

Definition at line 28 of file PyStoreArray.cc.

{
  return DataStore::Instance().getListOfArrays(TObject::Class(),
                                               durability);
}

operator bool()

operator bool ( ) const

inline

Does this PyStoreArray contain a valid datastore array?

Definition at line 212 of file PyStoreArray.h.

{ return isValid(); }

operator[]()

TObject * operator[]

(

int

i

)

const

returns object at index i, or null pointer if out of range (+error)

Definition at line 155 of file PyStoreArray.cc.

{
  ensureAttached();
  if (not isValid()) {
    return nullptr;
  } else {
    return m_storeEntry->getPtrAsArray()->At(i);
  }
}

optionalRelationTo()

bool optionalRelationTo	(	const PyStoreArray &	toArray,
		DataStore::EDurability	durability = DataStore::c_Event,
		std::string const &	namedRelation = ""
	)		const

Tell the data store about a relation that we could make use of.

(aka. optional input)

Mainly useful for creating diagrams of module inputs and outputs. This must be called in the initialization phase.

Parameters

toArray	Array the relation should point to (from this PyStoreArray)
durability	Durability of the relation.
namedRelation	Name of the relation in case it's not the default name

Returns

True if the relations exists.

Definition at line 114 of file PyStoreArray.cc.

{
  return DataStore::Instance().requireRelation(this->m_storeAccessor,
                                               toArray.m_storeAccessor,
                                               durability,
                                               namedRelation);
}

printList()

void printList ( DataStore::EDurability  durability = DataStore::EDurability::c_Event )

static

Print list of available arrays for given durability.

Definition at line 34 of file PyStoreArray.cc.

{
  for (const auto& n : list(durability))
    B2INFO(n);
}

registerInDataStore() [1/2]

bool registerInDataStore	(	const std::string &	name = "",
		DataStore::EStoreFlags	storeFlags = DataStore::EStoreFlags::c_WriteOut
	)

Register the array in the data store.

This must be called in the initialization phase.

Parameters

name	Name of the entry to be registered. Empty for default name.
storeFlags	ORed combination of DataStore::EStoreFlags. (default: c_WriteOut)

Returns

True if the registration succeeded.

Definition at line 69 of file PyStoreArray.cc.

{
  if (not hasValidClass()) {
    B2ERROR("Cannot register PyStoreArray '" << name << "' with unknown TClass. Please supply one to the PyStoreArray constructor.");
    return false;
  }
 
  bool success = m_storeAccessor.registerInDataStore(name, storeFlags);
  if (success) attach();
  return success;
}

registerInDataStore() [2/2]

bool registerInDataStore

(

DataStore::EStoreFlags

storeFlags

)

Register the array in the data store.

This must be called in the initialization phase.

Parameters

storeFlags

ORed combination of DataStore::EStoreFlags.

Returns

True if the registration succeeded.

Definition at line 64 of file PyStoreArray.cc.

{
  return registerInDataStore(m_storeAccessor.getName(), storeFlags);
}

registerRelationTo()

bool registerRelationTo	(	const PyStoreArray &	toArray,
		DataStore::EDurability	durability = DataStore::EDurability::c_Event,
		DataStore::EStoreFlags	storeFlags = DataStore::EStoreFlags::c_WriteOut,
		std::string const &	namedRelation = ""
	)		const

Register a relation to the given PyStoreArray.

Use this if you want to create relate objects in this array to objects in 'toArray'. Must be called in the initialization phase.

Parameters

toArray	Array the relation should point to (from this PyStoreArray)
durability	Durability of the relation.
storeFlags	ORed combination of DataStore::EStoreFlags
namedRelation	Additional name for the relation, or "" for the default naming

Definition at line 92 of file PyStoreArray.cc.

{
  return DataStore::Instance().registerRelation(this->m_storeAccessor,
                                                toArray.m_storeAccessor,
                                                durability,
                                                storeFlags,
                                                namedRelation);
}

requireRelationTo()

bool requireRelationTo	(	const PyStoreArray &	toArray,
		DataStore::EDurability	durability = DataStore::c_Event,
		std::string const &	namedRelation = ""
	)		const

Produce error if no relation from this array to 'toArray' has been registered.

Must be called in initialization phase, aborts job if it fails. (allowing you to catch problems early)

Parameters

toArray	Array the relation should point to (from this PyStoreArray)
durability	Durability of the relation.
namedRelation	Name of the relation in case it's not the default name

Returns

True if the relations exists.

Definition at line 104 of file PyStoreArray.cc.

{
  return DataStore::Instance().requireRelation(this->m_storeAccessor,
                                               toArray.m_storeAccessor,
                                               durability,
                                               namedRelation);
}

Member Data Documentation

m_storeAccessor

StoreAccessorBase m_storeAccessor

private

Store accessor to retrieve the object.

Definition at line 262 of file PyStoreArray.h.

m_storeEntry

StoreEntry* m_storeEntry = nullptr

mutableprivate

Pointer to the DataStore entry - serves as an internal cache omitting repeated look up from the DataStore.

Definition at line 265 of file PyStoreArray.h.

---

The documentation for this class was generated from the following files:

• framework/pybasf2/include/PyStoreArray.h
• framework/pybasf2/src/PyStoreArray.cc