-
Notifications
You must be signed in to change notification settings - Fork 12
PyPI package
The Python Package Index (PyPI) is the most commonly used means of downloading libraries within the global Python user community.
According to the basic principles of development within Home Assistant we should 'not include any protocol specific code'. This is likely why @alex0103 's repo published the warmup API interface-related code into https://pypi.org/project/warmup4ie/. As this projected used that as an upstream fork, we inherited that code. Although some tweaks have been made since @alex0103 published v0.1.5 into pyPI in May 2019, we have not managed to get any Pull Requests to have our updates published.
This is why, for now, we keep the more up-to-date version copied inside the custom_components/warmup folder.
If we were looking for our code to become a part of Home Assistant proper, then we would have to make sure that the protocol-specific code for interacting with the Warmup API was published into a standalone Python library made available via PyPI. We could just go ahead and publish an alternative PyPI package, although we would not be compelled to do this if we leave the project as a HACS integration / custom component. And perhaps that would involve more effort than we have the bandwidth to deliver.
Also, if we are the only project using the code, perhaps it's not worthwhile? So, before making further decisions, lets look at comparing our code with other projects, and any possible areas of collaboration. We should evaluate:
- how much commonality there already is between these projects
- how we could increase the likelihood that our code can be reused by other projects implementing features for different platforms
Looking for other python code, mentioning Warmup Plc devices, I have found:
which is part of the project behind the pywarmup package
- Package: https://pypi.org/project/pywarmup/
- Source: https://github.com/lkollar/pywarmup
Although it was only first committed to github in Dec 2019, this seems like a reasonably well-developed python project, including some code cleaning, error-handling, tests, setup. It is clear and well-structured, and although it lacks many of the properties that have been added to warmup4ie in v0.1.6, there may be some aspects of this code that could compliment what we have already.
It has a single developer and has had one minor release, in 2022, since it was created.
It was 'heavily inspired by' the previously released warmup4ie so it might also be worth looking for opportunities to collaborate, especially if the goal is a PyPI package that can be used more widely than only HA.
https://github.com/openhab/openhab-addons/tree/main/bundles/org.openhab.binding.warmup
This appears to be a currently supported integration for Warmup devices, but is written in Java.
This is code that inspired @alex0103's Python Package, written in the Java-like Apache Groovy language. It would appear that SmartThings have obsoleted these types of integration, and I can find nothing newer serving Warmup.
The first third of the code is for frontend, the middle is some local logic, the API related code is towards the end. The following methods communicate with the device API:
- setHeatingSetpoint(temp)
- setThermostatMode(mode)
- poll()
The code does not seem overly mature in comparison with warmup4ie.py and has not been updated since Oct 2018
Warmup Plc mention integrations for Crestron, Control4, IFTTT, and a skill for Alexa.
See the HA Dev Docs guide for how to structure the Python library for an API
Although HA has a very narrow window of supported Python releases, we should be mindful of the fact that the API interface code in this library shold be much more flexible, therefore we should only set Requires-Python according to code-internal constraints, and not be limited by HA-specific requirements.
We should be mindful of the fact that the PyPI library has a much narrower purpose than the HA Integration, and we should focus the documentaion on what is in that code, and what might be useful to other developers who might build off this package.
We should start off with the Guide to PyPI-friendly ReadMes. We maybe do not need to worry just yet about publishing help to 'ReadTheDocs'
One of the complications of testing is that the main purpose of the code is to interact with an API that requires authentication. For manual testing a specific tester can use their own credentials, if the have an account. However because these effective ly allow control of a device in that persons home, it would not be recommended to publish these credentials for others to use. Therefore autmated testing could be difficult to acheive, unless perhaps we could ask the vendor to provide access to simulated devicespurely for test purposes.
The Project Owner on PyPI can add collaborators who may then upload releases. Accounts on PyPI support two factor authentication for additional security.
We should evaluate whether TestPyPI would only be useful at initial setup of our tools and processes, or whether it has features that might be useful at each release. See the guide
See a tutorial on package release
Later we might decide to use GitHub Actions to publish the package
If at any point we wish to view statistics for how many times the PyPi package has been downloaded, we can see this at the site https://pepy.tech/project/warmup4ie If we were feeling expansive/boastful we could display this automatically on the project ReadMe with a badge.
For different statistics we could also use a free Google BigQuery account to pull this data from a public dataset as described here