From ee87fdc05e5b7a2b1614d46cb4b7e5016bfd69f3 Mon Sep 17 00:00:00 2001 From: Nathan Henrie Date: Mon, 25 Jul 2016 23:46:08 -0600 Subject: [PATCH] Add docs for timeout kwarg to Python API (#673) --- source/developers/python_api.markdown | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/source/developers/python_api.markdown b/source/developers/python_api.markdown index cc1144edb54..2df1fe16b75 100644 --- a/source/developers/python_api.markdown +++ b/source/developers/python_api.markdown @@ -142,6 +142,30 @@ time.sleep(5) remote.call_service(api, domain, 'turn_off', {'entity_id': '{}'.format(switch_name)}) ``` +### {% linkable_title Specify a timeout %} + +The default timeout for an API call with `call_service` is 5 seconds. Service +taking longer than this to return will raise +`homeassistant.exceptions.HomeAssistantError: Timeout` unless provided with a +longer timeout. + +```python +import homeassistant.remote as remote + +api = remote.API('host', 'password') +domain = 'switch' + +# Assuming switch.timeout_switch takes 10 seconds to return +switch_name = 'switch.timeout_switch' + +# Raises homeassistant.exceptions.HomeAssistantError: Timeout when talking to +remote.call_service(api, domain, 'turn_on', {'entity_id': switch_name}) + +# Runs withous exception +remote.call_service(api, domain, 'turn_on', {'entity_id': switch_name}, + timeout=11) +``` + ### {% linkable_title Send a notification %} The example uses the jabber notification platform to send a single message to the given recipient in the `configuration.yaml` file.