From 610f48dcbca6275a86a789c8ed6dfae8fe32cf55 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yago=20Gonz=C3=A1lez?= Date: Sun, 13 May 2018 21:02:41 +0200 Subject: [PATCH] docs: Explain how to configure the Python bindings. The Python bindings (which are used for bots, amongst other things) can be configured either with a .zuliprc file or with environment variables in the host machine. This new page in the user docs explains how to set the bindings up using both techniques, and is a good reference on the setup required by Zulip bots. --- templates/zerver/api/api-keys.md | 33 +----- .../zerver/api/configuring-python-bindings.md | 104 ++++++++++++++++++ templates/zerver/api/sidebar.md | 1 + 3 files changed, 108 insertions(+), 30 deletions(-) create mode 100644 templates/zerver/api/configuring-python-bindings.md diff --git a/templates/zerver/api/api-keys.md b/templates/zerver/api/api-keys.md index 4e39a1bfea..71130b730c 100644 --- a/templates/zerver/api/api-keys.md +++ b/templates/zerver/api/api-keys.md @@ -22,34 +22,7 @@ your bot's details: -Or you may also create it manually, as follows: - -``` -[api] -key=BOT_API_KEY -email=BOT_EMAIL_ADDRESS -``` - -Additionally, you can also specify the parameters as environment variables as follows: - -``` -export ZULIP_CONFIG=/path/to/zulipconfig -export ZULIP_EMAIL=BOT_EMAIL_ADDRESS -export ZULIP_API_KEY=BOT_API_KEY -``` - -The parameters specified in environment variables would override the parameters -provided in the config file. For example, if you specify the variable `key` -in the config file and specify `ZULIP_API_KEY` as an environment variable, -the value of `ZULIP_API_KEY` would be considered. - -The following variables can be specified: - -1. `ZULIP_CONFIG` -2. `ZULIP_API_KEY` -3. `ZULIP_EMAIL` -4. `ZULIP_SITE` -5. `ZULIP_CERT` -6. `ZULIP_CERT_KEY` -7. `ZULIP_CERT_BUNDLE` +Another alternative is manually creating your own `.zuliprc` file, or setting +environment variables that are equivalent. You can find out more about these +methods [here](/api/configuring-python-bindings). diff --git a/templates/zerver/api/configuring-python-bindings.md b/templates/zerver/api/configuring-python-bindings.md new file mode 100644 index 0000000000..c8161178ad --- /dev/null +++ b/templates/zerver/api/configuring-python-bindings.md @@ -0,0 +1,104 @@ +# Configuring the Python bindings + +Zulip provides a set of tools that allows interacting with its API more +easily, called the [Python bindings](https://pypi.python.org/pypi/zulip/). +One of the most notable use cases for these bindings are bots developed +using Zulip's [bot framework](/#writing-bots). + +In order to use them, you need to configure them with your API key and other +settings. There are two ways to achieve that: + + - With a file called `.zuliprc`, located in your home directory. + - With [environment variables](https://en.wikipedia.org/wiki/ +Environment_variable) set up in your host machine. + +A `.zuliprc` file is a plain text document that has the same format as +Microsft Windows INI files. It looks like this: + +``` +[api] +key= +email= +site= +... +``` + +The keys you can use in this file (and their equivalent environment variables) +can be found in the following table: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
.zuliprc keyEnvironment variableRequiredDescription
keyZULIP_API_KEYYes + API key, which you can get through + Zulip's web interface. +
emailZULIP_EMAILYes + The email address of the user who owns the API key mentioned + above. +
siteZULIP_SITENo + URL where your Zulip server is located. +
client_cert_keyZULIP_CERT_KEYNo + Path to the SSL/TLS private key that the binding should use to + connect to the server. +
client_certZULIP_CERTNo* + The public counterpart of client_cert_key/ + ZULIP_CERT_KEY. This setting is required if a cert + key has been set. +
client_bundleZULIP_CERT_BUNDLENo + Path where the server's PEM-encoded certificate is located. CA + certificates are also accepted, in case those CA's have issued the + server's certificate. Defaults to the built-in CA bundle trusted + by Python. +
insecureZULIP_ALLOW_INSECURENo + Allows connecting to Zulip servers with an invalid SSL/TLS + certificate. Please note that enabling this will make the HTTPS + connection insecure. Defaults to false. +
diff --git a/templates/zerver/api/sidebar.md b/templates/zerver/api/sidebar.md index 9c89b7b2fe..2c62b42321 100644 --- a/templates/zerver/api/sidebar.md +++ b/templates/zerver/api/sidebar.md @@ -19,6 +19,7 @@ * [Overview](/api/rest) * [Installation instructions](/api/installation-instructions) * [API keys](/api/api-keys) +* [Configuring the Python bindings](/api/configuring-python-bindings) * [Error handling](/api/rest-error-handling) {!rest_endpoints.md!}