# Utilities (skhep.utils)

Module for miscellaneous and general utilities.

## Submodule for decorators

Note

not meant for user code in general, though possible.

`skhep.utils.decorators.``inheritdoc`(cls, gap='\n')

  Decorator to automatize the inheritance of documentation from a class method.

  Example

      >>> from skhep.utils.decorators import inheritdoc
      >>> class ADerivedClass(ABaseClass):
      ...    @inheritdoc(ABaseClass)
      ...    def amethod(self): pass

## Submodule for helpers to deal with dependencies

`skhep.utils.dependencies.``softimport`(modulename, lazy=True)

  The function that one calls to import a module softly.

## Submodule for helpers to the Dataset-like classes

User-facing classes that structure the provenance information, i.e. the history of operations performed on the dataset.

Available classes:

- `Provenance` (abstract base class).
- `Origin` (abstract base class).
- `ObjectOrigin`.
- `FileOrigin`.
- `Transformation`.
- `Formatting`.

class `skhep.utils.provenance.``FileOrigin`(files)

  Declares that the dataset came from a file or a set of files.

  Parameters: | files (str or iterable of str or file objects) – File name(s) or object(s).

  Examples

      >>> from skhep.utils import FileOrigin
      >>> prov = FileOrigin(['file1.root', 'file2.root','file3.root'])
      >>> prov
      <FileOrigin (3 files)>

class `skhep.utils.provenance.``Formatting`(format, args)

  Declares that the dataset was reformatted, keeping its semantic meaning, but changed in representation.

class `skhep.utils.provenance.``ObjectOrigin`(detail)

  Declares that the dataset came from some Python object. Its history prior to that is unknown.

  Parameters: | detail (str) – String providing detailed information about the object origin.

  Examples

      >>> from skhep.utils import ObjectOrigin
      >>> from array import array
      >>> data = array('i',[1,2,3])
      >>> provenance1 = ObjectOrigin(repr(data))
      >>> provenance1
      <ObjectOrigin>
      >>> provenance1.detail
      "array('i', [1, 2, 3])"

      >>> provenance2 = ObjectOrigin('array_of_ints')
      >>> provenance2.detail
      'array_of_ints'

class `skhep.utils.provenance.``Origin`

  Abstract base class for all classes describing the first object in a provenance list.

  Trying to instantiate it raises an exception. Instantiate one of its subclasses instead.

class `skhep.utils.provenance.``Provenance`

  Abstract base class for all classes containing provenance information.

  Trying to instantiate it raises an exception. Instantiate one of its subclasses instead.

  `detail`

    String providing detailed information about the origin, transformation, or formatting.

class `skhep.utils.provenance.``Transformation`(name, args=[])

  Declares that the dataset was transformed by some mathematical operation.

  Parameters: | name (str) – String detailing how the dataset got transformed. args (iterable, optional) – Optional set of arguments given extra detail on the transformation.

  Examples

      >>> from skhep.utils import Transformation
      >>> transf = Transformation('all elms * 2')
      >>> transf
      <Transformation(all elms * 2)>