Econnect-python

Community Improvements!

To foster growth and fortify support for this library, we've initiated steps to streamline external contributions. Our goal is to ensure clarity in our guidelines, making it straightforward for contributors to get their code merged. To this end, we've integrated the following changes:

- **GitHub Actions CI Migration**: This is a shift towards an efficient Continuous Integration process.
- **GitHub Templates**: We've added templates for both pull requests and issues, simplifying the process to report bugs, request features, and contribute.
- **Contribution Guidelines**: Introduced to maintain a consistent code and standards across the board.

We're excited to announce that our project roadmap is now public! If you're keen on keeping tabs on our development journey, peek into our [next release roadmap](https://github.com/users/palazzem/projects/3/views/1). Plus, for those who have questions or seek support regarding this library or its Home Assistant integration version, we've launched a dedicated Discord channel. [We invite you to join](https://discord.gg/NSmAPWw8tE)!

While these improvements are not that significant, they're the beginning. Our commitment is to continually update and rejuvenate the development of this library. A heartfelt thanks to our vibrant community for your invaluable feedback, bug reports, and engaging discussions on feature enhancements!

What's Changed

Dependencies and Requirements

- Update supported Python versions: removed 3.5 (EOL) and added 3.9 (https://github.com/palazzem/econnect-python/pull/60) - this change is to respect the development of `0.4.0`. We'll update the test matrix in the upcoming release.

Client/API
- `ElmoClient` constructor has defaults to establish the connection (https://github.com/palazzem/econnect-python/pull/61)
- Introduce a safer API so that only HTTPS urls can be used (https://github.com/palazzem/econnect-python/pull/63)
- The client now handles session token expiration (10m) (https://github.com/palazzem/econnect-python/pull/64)
- Improved error handling to provide better descriptions in case of exceptions (https://github.com/palazzem/econnect-python/pull/65)
- Ensure `unlock()` is called even if an exception is raised in the block (https://github.com/palazzem/econnect-python/pull/66)
- Implement long-polling to retrieve state updates (https://github.com/palazzem/econnect-python/pull/67)
- Add support for selective exclusion and readmission of inputs (https://github.com/palazzem/econnect-python/pull/55 - thanks davidecavestro!)
- Remove `check()` API (https://github.com/palazzem/econnect-python/pull/71)
- Refactor `query()` API so that a raw query is returned; add `excluded` field to returned dict (https://github.com/palazzem/econnect-python/issues/57, https://github.com/palazzem/econnect-python/pull/72)
- `query()` API returns also `last_id` field; items are grouped under `sectors` or `inputs` keys (https://github.com/palazzem/econnect-python/pull/73)
- Include `status` field in `query()` API (https://github.com/palazzem/econnect-python/pull/74)

Documentation
- Better description about how to use `secret-code` in the README example (https://github.com/palazzem/econnect-python/pull/62/)

Read the [full changeset](https://github.com/palazzem/econnect-python/compare/v0.3.1...v0.4.0) and the [release milestone](https://github.com/palazzem/econnect-python/milestone/5?closed=1).

Documentation

* Update `README.md` "Usage" section, to improve the PyPI project main page (53)

Read the [full changeset](https://github.com/palazzem/econnect-python/compare/v0.3.0...v0.3.1) and the [release milestone](https://github.com/palazzem/econnect-python/milestone/4?closed=1).

New Features

Thanks markin for helping with these new features! (draft PR: 44)

* The project has been officially released on PyPI as `econnect-python` (42, 52)
* Extend `arm()` and `disarm()` with a `sector` kwarg to enable/disable one or multiple sectors (46)
* Handle authentication redirects (49)
* Add `client.query()` public API (50)

Improvements

* Use Authentication API instead of scraping the `SessionID` (47)

Breaking Changes

* Remove Settings module (21, 51)
* Refactor global status `check()` (48). The method returns a dictionary with different keys:
python
Before
{
"areas_armed": [{"id": 0, "name": "Entryway"}, ...],
"areas_disarmed": [{"id": 1, "name": "Kitchen"}, ...],
"inputs_alerted": [{"id": 0, "name": "Door"}, ...],
"inputs_wait": [{"id": 1, "name": "Window"}, ...],
}

After
{
"sectors_armed": [{"id": 0, "name": "Entryway", "element": 1, "index": 0}, ...],
"sectors_disarmed": [{"id": 1, "name": "Kitchen", "element": 2, "index": 1}, ...],
"inputs_alerted": [{"id": 0, "name": "Door", "element": 3, "index": 0}, ...],
"inputs_wait": [{"id": 1, "name": "Window", "element": 4, "index": 1}, ...],
}


Read the [full changeset](https://github.com/palazzem/econnect-python/compare/0.2.0...v0.3.0) and the [release milestone](https://github.com/palazzem/econnect-python/milestone/3?closed=1).

Changes

New Features

* It's now possible to check the System status using the `ElmoClient.check()` API (40, 36)

Client Core

* Add `session_id` to the `ElmoClient` initializer (38, 34)
* Simplified the code structure by using requests `raise_for_status()` (39, 37)

Read the [full changeset](https://github.com/palazzem/elmo-alerting/compare/0.1.0...0.2.0) and the release [milestone](https://github.com/palazzem/elmo-alerting/milestone/2?closed=1).

Release

This is a first release for `elmo-alerting` library, which includes the following capabilities:
* Retrieving access tokens to make API calls
* Obtaining/releasing the system `Lock()` to have exclusive control of the system
* Arm/disarm all the alarms registered in the system

The following example shows how to arm or disarm an Elmo system:

python
from elmo.api.client import ElmoClient

Initialize the client with an API endpoint and a vendor and
authenticate your connection to retrieve the access token
client = ElmoClient("https://example.com", "vendor")
client.auth("username", "password")

To arm/disarm the system you must gain the exclusive Lock()
with client.lock("secret-code") as c:
c.arm() Arms all alarms
c.disarm() Disarms all alarms


This version should be considered an early version, even though it can be considered stable in terms of functionalities. That said, the API is considered `0.x.y`, meaning it can change in the near future. Migration guides will be provided if breaking changes are introduced.