TupleUtils.py

Go to the documentation of this file.

#!/usr/bin/env python
# =============================================================================
## This module contains set of simple and useful utilities to booking and
#  manipulation with N-Tuples (in the spirit of GaudiTuples<TYPE>)
#  @author Vanya BELYAEV ibelyaev@physics.syr.edu
#  @date 2007-08-04
# =============================================================================
"""
This module contains set of simple and useful utilities to booking and
manipulation with N-Tuples (in the spirit of GaudiTuples<TYPE>)

"""
# =============================================================================
__author__ = "Vanya BELYAEV ibelyaev@physics.syr.edu"
# =============================================================================
__all__ = (
    'nTuple'        ,  ## function to book/retrieve N-tuple
    'getNTuple'     ,  ## ditto
    'getNtuple'     ,  ## ditto
    'getntuple'     ,  ## ditto
    'gettuple'      ,  ## ditto
    'activeTuples'  ,  ## get the list of all active n-tuples
    'releaseTuples'    ## release all actibe N-tuples
    )
# =============================================================================

from   GaudiPython.Bindings  import gbl as cpp
from   GaudiPython.Bindings  import AppMgr
import GaudiPython.GaudiAlgs

_Tool = cpp.ITupleTool
_Deco = cpp.GaudiPython.TupleToolDecorator

# the list of aquired tools (to be released)
_TOOLS_ = []

# =============================================================================
## Helper private auxillary utility to get Tool Service
def _getToolSvc( **kwargs ) :
    """ Helper private auxillary utility to get Tool Service """
    svc = kwargs.get ( 'toolSvc' , None )
    if not svc : svc = kwargs.get ( 'toolsvc' , None )
    if not svc : svc = kwargs.get ( 'service' , None )
    if not svc : svc = kwargs.get ( 'svc'     , None )
    else       : return svc                                ## RETURN
    gaudi = kwargs.get ( 'gaudi' , None )
    if not gaudi : gaudi = AppMgr()
    return gaudi.toolsvc()                                 ## RETURN


# =============================================================================
## Retrive N-Tuple ( book on demand )
def _nTuple_ ( s , *args ) :
    """ Retrive N-tuple ( book on demand )  """
    return _Deco.nTuple ( s , *args)

# =============================================================================
_nTuple_. __doc__ += "\n" + _Deco.nTuple . __doc__
_Tool.nTuple = _nTuple_
_Tool.ntuple = _nTuple_


# =============================================================================
## Retrieve (book-on-demand) 'Smart'-N-tuple object.
def nTuple ( dirpath , ID , ID2 = None , topdir = None , LUN = 'FILE1' ) :
    """
    Retrieve 'Smart'-N-tuple object.
    N-tuple is booked on-demand.

    Atetntion !!
    The logical unit LUN must be configured by N-Tuple Service

    Retrieve (book-n-demand) N-Tuple using
    the  directory name and the title:
    >>> t = nTuple ( 'the/path/to/directory' , ## the path to the directory
                     'N-tuple title'         , ## the title for N-Tuple
                      LUN = 'FILE1'          ) ## logical file unit

    Retrieve (book-n-demand) N-Tuple using
    the  directory name, literal ID and the title:
    >>> t = nTuple ( 'the/path/to/directory' , ## the path to the directory
                     'Tuple1'                , ## the literal ID for N-Tuple
                     'N-tuple title'         , ## the title for N-Tuple
                      LUN = 'FILE1'          ) ## logical file unit

    Retrieve (book-n-demand) N-Tuple using
    the  directory name, numerical ID and the title:
    >>> t = nTuple ( 'the/path/to/directory' , ## the path to the directory
                     124                     , ## the numerical ID for N-Tuple
                     'N-tuple title'         , ## the title for N-Tuple
                      LUN = 'FILE1'          ) ## logical file unit


    """
    toolSvc = _getToolSvc ()

    # construct the name of the intermediate TupleTool
    name = 'Tuple'+LUN+"/"
    if topdir : name += topdir
    name += dirpath
    name += "_%s"%ID
    if  ID2 : name += "_%s"%ID2
    name=name.replace ( '.'  , '_' )
    name=name.replace ( '/'  , '_' )
    name=name.replace ( '\\' , '_' )
    name=name.replace ( ' '  , '_' )

    ## define tool properties
    t0 = GaudiPython.iAlgTool( 'ToolSvc.'+name )
    t0.OutputLevel      = 1
    t0.NTupleLUN        = LUN
    t0.NTupleDir        = dirpath
    t0.PropertiesPrint  = False
    t0.OutputLevel      = 4
    if topdir : t0.NTupleTopDir = topdir

    ## get the tool from Tool service
    tool = toolSvc.create ( 'TupleTool'       ,
                            name              ,
                            interface = _Tool )

    ## check the properties and redefine them if needed
    t1 = GaudiPython.iAlgTool ( tool.name() , tool )
    if t1.NTupleLUN != LUN     : t1.NTupleLUN = LUN
    if t1.NTupleDir != dirpath : t1.NTupleDir = dirpath
    if topdir and ( t1.NTupleTopDir != topdir ) :
        t1.NTupleTopDir = topdir

    _TOOLS_.append ( tool )
    if not ID2 : return tool.nTuple ( ID )               ## RETURN

    return tool.nTuple ( ID , ID2 )                      ## RETURN


nTuple . __doc__ += "\n\t help(ITupleTool.nTuple) : \n" \
                    + _Tool.nTuple.__doc__

ntuple    = nTuple
getNTuple = nTuple
getNtuple = nTuple
getntuple = nTuple
getTuple  = nTuple
gettuple  = nTuple

# =============================================================================
## Return the list of active tools
def activeTuples () :
    """
    Return the list of active tools
    """
    return _TOOLS_

# =============================================================================
## Release the active tool/tuples
def releaseTuples () :
    """
    Release the active tool/tuples
    The method needs to be invoked explicitely at the end of the job
    """
    if not _TOOLS_ : return
    from GaudiPython.Bindings import _gaudi
    if not _gaudi : return

    toolSvc = _getToolSvc()
    if toolSvc.isValid() :
        while _TOOLS_ :
            t = _TOOLS_.pop()
            if not t : continue
            while 1 < t.refCount() :
                toolSvc._its.releaseTool( t )

# =============================================================================
def _TupleUtils_AtExit_ () :
    """
    AtExit function for GaudiPython.TupleUtils module
    """
    if activeTuples() :
        print 'WARNING: the list of local TupleTools is not empty!'
        print 'WARNING: please use GaudiPython.TupleUtils.releaseTuples() at the end'

import atexit
atexit.register ( _TupleUtils_AtExit_ )

# =============================================================================
if "__main__" == __name__ :
    import sys
    print __doc__ , __all__
    for o in __all__ :
        print "\n\n\t",o,"\n"
        print sys.modules[__name__].__dict__[o].__doc__

# =============================================================================
# The end
# =============================================================================