datareadingrequests's Introduction

Data Reading Requests

A new client for Energize Andover's Building Energy Gateway, with a focus on clarity and usability.

Notice 2022-01-07

Tests are currently failing because there is something wrong with Building Energy Gateway's live feature. To be clear, this is not a datareadingrequests issue: the same thing occurs when you use building_data_requests. While we wait for this to be fixed, do not use live=True.

Features

It's packaged, so you can install it with pip!
It's fully unit-tested.
It's open source, and contributions are welcome.

API Changes from building_data_requests

For compatibility, datareadingrequests' function definitions are similar to those of building_data_requests. However, there are a few key differences between the two modules:

Instead of a tuple, datareadingrequests' get_value() returns a DataReading namedtuple. This allows you to use the original tuple notation or the cleaner dot notation. Read more about namedtuples here.
datareadingrequests has a predictable, single return type for get_value(). With building_data_requests, get_value() could return a valid result or None. Here, it can only return a valid result; it raises an exception if the server returns no data. The reasoning for this is well-explained by williballenthin:

I've learned that returning more than one type of data from a function is a recipe for trouble. For example, when a function can return a string or a list, then every place that the function is called must check "is it a string or a list?". If the programmer forgets this, then inevitably, the program breaks at an inconvenient time. By extension, if a function returns a string or None, then every invocation must check "is the result None?". This is easy to forget, and leads to latent bugs. With the existing style, forgetting a try/except block is also a bug, but when the exception is generated, the programmer gets a very explicit stack trace with easy-to-find line number.

In the same way, datareadingrequests' get_bulk() raises an exception if the server returns no data for any specific instance.
datareadingrequests has no way (currently) to change hostname or port.
datareadingrequests does not retry requests without SSL.

Setup

Use your favorite Python package manager, and do as you would with pandas, matplotlib, etc.

pip:

pip install datareadingrequests
pip freeze > requirements.txt

Poetry:

poetry add datareadingrequests

datareadingrequests's People

Contributors

Stargazers

Watchers

datareadingrequests's Issues

get_value() should have live = False by default

To match building_data_requests, make get_value's live parameter False by default. Also, modify unit tests to test both live and non-live queries.

Live parameter added to arguments incorrectly

There is a bug in these lines: the key added to args becomes the value of live (True or False) instead of the actual string "live". Silly mistake, @tactlessfish !