Clarify external packages must have source code published (#2172)
* Clarify external packages must have source code published * Improve language * Improve language * Update docs/api_lib_index.md Co-authored-by: Joost Lekkerkerker <joostlek@outlook.com> * Update docs/creating_component_code_review.md * Update docs/api_lib_index.md * Update docs/api_lib_index.md --------- Co-authored-by: Joost Lekkerkerker <joostlek@outlook.com>
This commit is contained in:
parent
613d1190f3
commit
adb09ecf85
|
@ -5,6 +5,14 @@ sidebar_label: "Introduction"
|
|||
|
||||
One of the foundational rules of Home Assistant is that we do not include any protocol specific code. Instead, this code should be put into a standalone Python library and published to PyPI. This guide will describe how to get started with this!
|
||||
|
||||
## Basic library requirements
|
||||
|
||||
- The library must have source distribution packages available, it's not allowed to rely on packages that only have binary distribution packages.
|
||||
- Issue trackers must be enabled for external Python libraries that communicate with external devices or services.
|
||||
- If the library is mainly used for Home Assistant and you are a code owner of the integration, it is encouraged to use an issue template picker with links to [Home Assistant Core Issues](https://github.com/home-assistant/core/issues). For example: [zwave-js-server-python - New Issue](https://github.com/home-assistant-libs/zwave-js-server-python/issues/new/choose)
|
||||
- The library and possible subdependencies of the library must be licensed using an [OSI-approved license](https://opensource.org/license). This should be reflected in the metadata of the library.
|
||||
|
||||
|
||||
For this guide we're going to assume that we're building a library for a Rest API that is accessible over HTTP and returning data structured as JSON objects. This is the most common type of API that we see. These APIs can either be accessible on the device itself, or in the cloud.
|
||||
|
||||
This guide is not a perfect fit for every API. You might have to tweak the examples.
|
||||
|
|
|
@ -15,11 +15,11 @@ Not all existing code follows the requirements in this checklist. This cannot be
|
|||
2. Use existing constants from [`const.py`](https://github.com/home-assistant/core/blob/dev/homeassistant/const.py)
|
||||
- Only add new constants to `const.py` if they are widely used. Otherwise keep them on components level
|
||||
|
||||
### 1. Requirements
|
||||
### 1. External requirements
|
||||
|
||||
1. Requirements have been added to [`manifest.json`](creating_integration_manifest.md). The `REQUIREMENTS` constant is deprecated.
|
||||
2. Requirement version should be pinned: `"requirements": ['phue==0.8.1']`
|
||||
3. We no longer want requirements hosted on GitHub. Please upload to PyPi.
|
||||
2. Requirement version must be pinned: `"requirements": ['phue==0.8.1']`
|
||||
4. Each requirement meets the [library requirements](api_lib_index.md#basic-library-requirements).
|
||||
|
||||
### 2. Configuration
|
||||
|
||||
|
|
|
@ -16,11 +16,12 @@ Not all existing platforms follow the requirements in this checklist. This canno
|
|||
- Only add new constants to `const.py` if they are widely used. Otherwise keep them on platform level
|
||||
- Use `CONF_MONITORED_CONDITIONS` instead of `CONF_MONITORED_VARIABLES`
|
||||
|
||||
### 1. Requirements
|
||||
### 1. External requirements
|
||||
|
||||
1. Requirements have been added to [`manifest.json`](creating_integration_manifest.md). The `REQUIREMENTS` constant is deprecated.
|
||||
2. Requirement version should be pinned: `"requirements": ['phue==0.8.1']`
|
||||
3. We no longer want requirements hosted on GitHub. Please upload to PyPi.
|
||||
4. Each requirement meets the [library requirements](api_lib_index.md#basic-library-requirements).
|
||||
|
||||
### 2. Configuration
|
||||
|
||||
|
|
|
@ -16,6 +16,6 @@ We have created two example integrations that should give you a look at how this
|
|||
|
||||
One Home Assistant rule is that the integration should never interface directly with devices. Instead, it should interact with a third-party Python 3 library. This way, Home Assistant can share code with the Python community and keep the project maintainable.
|
||||
|
||||
Once you have your Python library ready and published to PyPI, add it to the [manifest](creating_integration_manifest.md). It will now be time to implement the Entity base class that is provided by the integration that you are creating a platform for.
|
||||
Once you have your Python library [ready and published to PyPI](api_lib_index.md), add it to the [manifest](creating_integration_manifest.md). It will now be time to implement the Entity base class that is provided by the integration that you are creating a platform for.
|
||||
|
||||
Find your integration at the [entity index](core/entity.md) to see what methods and properties are available to implement.
|
||||
|
|
|
@ -6,8 +6,9 @@ sidebar_label: Introduction
|
|||
Before you commit any changes, check your work against these requirements:
|
||||
|
||||
- All communication to external devices or services must be wrapped in an external Python library hosted on [pypi](https://pypi.org/).
|
||||
- Issue trackers must be enabled for external Python libraries that has communication with external devices or services.
|
||||
- If the library is mainly used for Home Assistant and you are a code owner of the integration it is encouraged to use an issue template picker with links to [Home Assistant Core Issues](https://github.com/home-assistant/core/issues). For example: [zwave-js-server-python - New Issue](https://github.com/home-assistant-libs/zwave-js-server-python/issues/new/choose)
|
||||
- The library must have source distribution packages available; it's not allowed to rely on packages that only have binary distribution packages.
|
||||
- Issue trackers must be enabled for external Python libraries that communicate with external devices or services.
|
||||
- If the library is mainly used for Home Assistant and you are a code owner of the integration, it is encouraged to use an issue template picker with links to [Home Assistant Core Issues](https://github.com/home-assistant/core/issues). For example: [zwave-js-server-python - New Issue](https://github.com/home-assistant-libs/zwave-js-server-python/issues/new/choose)
|
||||
- New dependencies are added to `requirements_all.txt` (if applicable), using `python3 -m script.gen_requirements_all`
|
||||
- New codeowners are added to `CODEOWNERS` (if applicable), using `python3 -m script.hassfest`
|
||||
- The `.strict-typing` file is updated to include your code if it provides a fully type hinted source.
|
||||
|
|
Loading…
Reference in New Issue