Contributing

This page is where development related things are. See below.

Contribution Ideas

If you don’t know what you want to contribute yet you should take a look at our issues page. See what other people have been up to and if you have an idea for a new feature or a new way to implement a feature you should create an issue or fork the repository and start contributing. We’re always interested in integrating ways to make the library faster, extensible and easier to use.

Setting up your Development Environment

So now that you know what you want to contribute it is time to setup a development environment to make your changes in.

Step One: Fork the Repository

Click here to fork the repository. Then click your username.

Step Two: Clone the Repository Locally

Next run in your terminal.

$ git clone https://github.com/<YOUR_GITHUB_USERNAME>/HomeAssistantAPI

Step Three: Installing Dependencies

Firstly, you need to have Python 3.7 or newer with Pip installed. Download the latest Python Version from here. Then you need to install the very popular Python Package Manager, poetry. Checkout the Poetry Docs. You can install that with pip by running pip install poetry. Now you can install the project’s dependencies by running cd HomeAssistantAPI && poetry install

Step Four: [Optional] Setting Up a Home Assistant Development Environment.

If you do not have a Home Assistant installation running already, you can setup a Home Assistant Development environment. Which is basically a local, unpackaged, Home Assistant Core installation, that runs with just Python (no Docker or Operating System). You can start and stop the server really easily as it runs just in your terminal and gives you lots of control over it, making it ideal for testing your changes to Home Assistant API. Follow this great guide here to do that. After that you are now ready to make your changes to the codebase!

Testing

In order to test your changes you need to have an API URL, and a Long Lived Access Token. Follow the Quickstart Section for getting those. If you setup the Development Environment then your API URL will most likely be something along the lines of https://localhost:8123/api. Then you can test your changes by passing the API URL, and Long Lived Access Token to the homeassistant_api.Client object.

Code Styling Guidelines

In order to make sure that our code is easy to read, and navigate. As well as to stop stupid mistakes like typos, undefined variables, etc. We enforce code standards. Using the tools, ruff, pytest, and docker, we make make sure that our code quality is top notch, and that are changes work everywhere. You can those tools manually yourself, but they also run automatically when you open a PR.

Merging Your Contributions

Once you have tested your changes and committed them to your fork you can merge them back into the original repository. Head over to the Pull Request Page and select your fork to merge into the GrandMoff100/dev branch. Then you can hit “Create Pull Request” and we’ll review it as soon as possible. In order to be merged though, your code needs to follow our Styling Guidelines. A Github Actions workflow will run on your PR automatically to verify that it does follow the guidelines. Then once the checks have passed one of our maintainers will review the changes (basically to make sure your changes won’t break anything ;)). Then after that your changes will get merged and will be available in the next release!