Overview

The Orange Button Python Library, also called, pyoblib, provides functions to interact and work with the SunSpec Orange Button Taxonomy and provides capabilities that simplify working with Orange Button data.

The pyoblib library leverages the Python standard library to the extent possible to minimize required dependencies. pyoblib is Open Sourced and is maintained by the Orange Button Open Source community. The source code is available on GitHub - pyoblib. The code is licensed under Apache 2.0.

The SunSpec Orange Button Taxonomy is also published as open source on GitHub - solar-taxonomy.

Features

  • Includes an in-memory data model
  • Includes in-memory meta-data about the SunSpec Orange Button Taxonomy
  • Provides support for XML/JSON input-output
  • Provides support for data conversion and data validation
  • Supports identifier generation and validation

pyoblib Class and Module Structure

pyoblib module structure

Requirements

  • Python 3.4-3.6

Installation

Installing the library from PyPI

To install the library from the Python Package Index (PyPI), run the following command:

pip install oblib

Installing the library from GitHub

Follow the steps outlined below to install the library for development from GitHub.

  1. Create a fork of the pyoblib GitHub repository.
  2. Clone it locally.
  3. Navigate to the pyoblib root directory - cd pyoblib
  4. Run the setup script - scripts/setup-dev.sh
  5. Install using setup.py - python setup.py install

A series of Bash (Mac/Linux) shell scripts are available to assist with development and packaging.

  • cli.sh: Runs the CLI before it is packaged.
  • dist-cli.sh: Packages the CLI into a single executable file.
  • setup-dev.sh: Downloads the solar-taxonomy, us-gaap taxonomy, and Units registry.
  • tests.sh: Runs the python tests.
  • tests-cli.sh: Runs the CLI test suite.

All scripts must be run from the root directory (i.e. scripts/tests.sh is the correct usage). Run scripts/setup-dev.sh before usage of other scripts.

Running the Tests

In order to run the tests run the following scripts:

  • tests.sh - Runs the python tests.
  • tests-cli.sh - Runs the CLI test suite.

Installing the CLI Tool

Follow the steps outlined below to the Command Line Interface (CLI) tool.

  1. Download an executable that matches your system type -

    • Mac - OB Mac Executable
    • Windows - OB Windows Executable
    • Linux - OB Linux Executable

  2. Register the executable -

To be able to run the executable from the command line, follow one of the two options -
  1. Move the downloaded file to the executable path -
    • Mac, Linux - sudo mv ob /usr/local/bin
  2. Or, add the OB executable file path to the system PATH environment variable.

Now, the CLI tool can be invoked from the command line by using the command ob. For the full set of commands, use the help option as ob --help