with_bf

bapsflib.utils.decorators.with_bf(wfunc=None, *, filename: str | None = None, control_path: str | None = None, digitizer_path: str | None = None, msi_path: str | None = None)

Context decorator for managing the opening and closing BaPSF HDF5 Files (bapsflib._hdf.utils.file.File). An instance of the BaPSF HDF5 file is injected into the decorated function at the end of the positional arguments. The decorator is primarily designed for use on test methods, but can also be used as a function decorator.

Parameters:

  • wfunc – function or method to be wrapped

  • filename – name of the BaPSF HDF5 file

  • control_path – internal HDF5 path for control devices

  • digitizer_path – internal HDF5 path for digitizers

  • msi_path – internal HDF5 path for MSI devices

Example:

The HDF5 file parameters (filename, control_path, digitizer_path, and msi_path) can be passed to the decorator in three ways (listed by predominance):

  1. The wrapped function arguments.

  2. If the wrapped function is a method, then through appropriately named self attributes.

  3. The decorator keywords.

Defined with wrapped function arguments:

>>> # as function keywords
>>> @with_bf
... def foo(bf, **kwargs):
...     # * bf will be the HDF5 file object
...     # * do whatever is needed with bf and @with_bf will close
...     #   the file at the end
...     return bf.filename
>>> foo(filename='test.hdf5', control_path='Raw data + config',
...     digitizer_path='Raw data + config', msi_path='MSI')
'test.hdf5'
>>>
>>> # as a function argument
>>> @with_bf
... def foo(filename, bf, **kwargs):
...     # use bf
...     return bf.filename
... foo('test.hdf5')
'test.hdf5'

Defined with wrapped method attributes:

>>> # use `self` to pass file settings
>>> class BehaveOnFile:
...     def __init__(self):
...         super().__init__()
...         self.filename = 'test.hdf5'
...         self.control_path = 'Raw data + config'
...         self.digitizer_path = 'Raw data + config'
...         self.msi_path = 'MSI'
...
...     @with_bf
...     def foo(self, bf, **kwargs):
...         return bf.filename
>>> a = BehaveOnFile()
>>> a.foo()
'test.hdf5'
>>>
>>> # but keywords will still take precedence
>>> a.foo(filename='test_2.hdf5')
'test_2.hdf5'

Defined with decorator keywords:

>>> # as function keywords
>>> @with_bf(filename='test.hdf5',
...          control_path='Raw data + config',
...          digitizer_path='Raw data +config',
...          msi_path='MSI')
... def foo(bf, **kwargs):
...     return bf.filename
>>> foo()
'test.hdf5'
>>>
>>> # function keywords will still take precedence
>>> foo(filename='test_2.hdf5')
'test_2.hdf5'