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.11 or newer installed. Download the latest Python Version from here. Then you need to install uv, a fast Python package manager. Checkout the uv Docs. You can install it with pip by running pip install uv, or see the uv docs for other installation methods. Now you can install the project’s dependencies by running cd HomeAssistantAPI && uv sync

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

Tests use pre-recorded cassettes so you do not need a running Home Assistant instance to run the test suite. Each test has its own cassette stored under tests/cassettes/<module>/<test_name>.json.

Running the test suite

$ uv run pytest

Recording cassettes for a new test

If you add a new test that makes real HTTP or WebSocket requests, you need to record its cassette against a live Home Assistant instance.

Get an API URL and a Long-Lived Access Token by following the Quickstart Section.

Export the environment variables:

$ export HOMEASSISTANTAPI_URL="http://<your-ha-host>:8123/api"
$ export HOMEASSISTANTAPI_WS_URL="ws://<your-ha-host>:8123/api/websocket"
$ export HOMEASSISTANTAPI_TOKEN="<your-token>"

Run pytest with the --record flag to record cassettes:
```
$ uv run pytest --record
```
This records a fresh .json cassette for every test. Commit the cassette files alongside your test so CI can replay them without a live server.

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, zuban, and pytest, we make sure that our code quality is top notch and that 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!