bifrost-common-py 0.8
Common python library functions for interacting with BIFROST.
Keywords: bifrost,bifrost-common

# bifrost-common

A library of commonly used functions to interact with BIFROST. Useful for module developers.

## Installation

```
pip install bifrost-common-py
```

## Components

### Log

A module to print nice logging information to the console and, optionally, to files.

```
from bifrost_common_py.Log import Log

log = Log('myComponent', 'myApplication', options={'maxLogFileSize':1e4, 'enableLogFiles':True})

log.write(`Abandon ship`, Log.WARNING)
log.write(`Run like hell`, Log.INFO)
```

Log levels are `DEBUG`, `INFO`, `WARNING`, `ERROR`, `FAILURE`

Allowed `options` are:
- `enableLogFiles` (default: `false`): log to files as well as the console
- `logDir` (default: `log`): the log file directory (will be created as necessary)
- `maxLogFileSize` (default: `0`): maximum byte size of the log files, after which a new file will be started, default =`0` never rollover
- `maxArchiveSize`(default: 5): maximum number of log files to keep

### time

Some useful operations involving time, mostly for formatting `Log` output.

### idOfRef

Resolve the ID contained in an object. If no 'id' field is found in the
object pointed to with `ref`, the last part of the reference is returned instead.

```
from bifrost_common_py.idOfRef import idOfRef

print(idOfRef({ 'A': { 'id': '1' }}, '/A')) // '1'

```

### tokens

An object collecting string tokens commonly used in the BIFROST state.

```
import bifrost_common_py.tokens as tokens

print(tokens.tkId) // "id"
```

### select

Selectors returning fully-qualified JSON paths into the BIFROST state.

```
import bifrost_common_py.pathSelectors as select

print(select.meta())                      # "/meta"
print(select.dynamicId('DYNAMIC-1'))      # "/dynamics/byId/DYNAMIC-1"
print(select.eventParentRef('EVENT-1'))   # "/events/byId/EVENT-1/parentRef"
```

### safepointer

A wrapper that allows to specify default values if paths can not be resolved. This is best used in conjunction with `select` and a copy of the BIFROST state.

#### API

```
import bifrost_common_py.safepointer
```

##### .has(obj, path)

Determine whether the fully-qualified JSON pointer `path` points to something in `obj`.

```
safepointer.has({ 'A': { 'B': 1} }, '/A/B') # true
safepointer.has({ 'A': { 'B': 1} }, '/A/C') # false
```

##### .get(obj, path, def = null)

Resolve `path` against `obj`. If the path does not exist, `def` is returned instead.

```
safepointer.get({ 'A': { 'B': 1} }, '/A/B', 0)  # 1
safepointer.get({ 'A': { 'B': 1} }, '/A/C', 0)  # 0

import bifrost_common_py.pathSelectors as select

safepointer.get(state, select.meta(), {}) // { id: ... }
```

### SelectFrom

A declarative state selection library. Use this to select elements from the BIFROST state or from module subscription data.

```
    from bifrost_common_py.SelectFrom import SelectFrom

    SelectFrom(state).allDynamics().ofType('VOLTAGE-3P').asValueMap()

    SelectFrom(subs).allEntries().ofType('CLIMATE-MODEL').asValueList()

    SelectFrom(subs, state).allEntries().withParentOfType('WEATHER').asValueMap()
```