Metadata-Version: 2.1
Name: datareadingrequests
Version: 2.0.1
Summary: A client for Energize Andover's Building Energy Gateway, with a focus on clarity and usability.
Home-page: https://github.com/tactlessfish/datareadingrequests
License: MIT
Author: fisher
Author-email: fisher521.fs@gmail.com
Requires-Python: >=3.8,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Dist: requests (>=2.26.0,<3.0.0)
Project-URL: Repository, https://github.com/tactlessfish/datareadingrequests
Description-Content-Type: text/markdown

# Data Reading Requests
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/datareadingrequests)](https://pypi.org/project/datareadingrequests/)
[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/tactlessfish/datareadingrequests/main)](https://github.com/tactlessfish/datareadingrequests/actions)
[![Coveralls](https://img.shields.io/coveralls/github/tactlessfish/datareadingrequests)](https://coveralls.io/github/tactlessfish/datareadingrequests)

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

## 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](https://realpython.com/python-namedtuple/).
- 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
```

