mirror of https://github.com/zulip/zulip.git
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.
This commit is contained in:
Yago González
Tim Abbott
parent
a575d69eec
commit
610f48dcbc
|
|
@ -22,34 +22,7 @@ your bot's details:
|
|||
|
||||
<img class="screenshot" src="/static/images/api/download-zuliprc.png" />
|
||||
|
||||
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).
|
||||
|
||||
|
|
|
|||
|
|
@ -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=<api key from the web interface>
|
||||
email=<your email address>
|
||||
site=<your Zulip server's URI>
|
||||
...
|
||||
```
|
||||
|
||||
The keys you can use in this file (and their equivalent environment variables)
|
||||
can be found in the following table:
|
||||
|
||||
<table class="table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th><code>.zuliprc</code> key</th>
|
||||
<th>Environment variable</th>
|
||||
<th>Required</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tr>
|
||||
<td><code>key</code></td>
|
||||
<td><code>ZULIP_API_KEY</code></td>
|
||||
<td>Yes</td>
|
||||
<td>
|
||||
<a href="/api/api-keys">API key</a>, which you can get through
|
||||
Zulip's web interface.</a>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>email</code></td>
|
||||
<td><code>ZULIP_EMAIL</code></td>
|
||||
<td>Yes</td>
|
||||
<td>
|
||||
The email address of the user who owns the API key mentioned
|
||||
above.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>site</code></td>
|
||||
<td><code>ZULIP_SITE</code></td>
|
||||
<td>No</td>
|
||||
<td>
|
||||
URL where your Zulip server is located.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>client_cert_key</code></td>
|
||||
<td><code>ZULIP_CERT_KEY</code></td>
|
||||
<td>No</td>
|
||||
<td>
|
||||
Path to the SSL/TLS private key that the binding should use to
|
||||
connect to the server.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>client_cert</code></td>
|
||||
<td><code>ZULIP_CERT</code></td>
|
||||
<td>No*</td>
|
||||
<td>
|
||||
The public counterpart of <code>client_cert_key</code>/
|
||||
<code>ZULIP_CERT_KEY</code>. <i>This setting is required if a cert
|
||||
key has been set.</i>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>client_bundle</code></td>
|
||||
<td><code>ZULIP_CERT_BUNDLE</code></td>
|
||||
<td>No</td>
|
||||
<td>
|
||||
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.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>insecure</code></td>
|
||||
<td><code>ZULIP_ALLOW_INSECURE</code></td>
|
||||
<td>No</td>
|
||||
<td>
|
||||
Allows connecting to Zulip servers with an invalid SSL/TLS
|
||||
certificate. Please note that enabling this will make the HTTPS
|
||||
connection insecure. Defaults to <code>false</code>.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
|
@ -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!}
|
||||
|
|
|
|||
Loading…
Reference in New Issue