Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
zulip/api_docs/configuring-python-bindings.md

4.6 KiB
Raw Blame History

Configuring the Python bindings

Zulip provides a set of tools that allows interacting with its API more easily, called the Python bindings. One of the most notable use cases for these bindings are bots developed using Zulip's bot framework.

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 passed as an argument via the --config-file option.
  • With environment variables set up in your host machine.

Download a zuliprc file

{start_tabs}

{tab|for-a-bot}

{settings_tab|your-bots}

  1. Click the download () icon on the profile card of the desired bot to download the bot's zuliprc file.

!!! tip ""

If you save or move a `zuliprc` file to your home directory as `~/.zuliprc`,
the Python API bindings will automatically read it in (you won't have to
pass the `--config-file` option).

!!! warn ""

Anyone with a bot's API key can impersonate the bot, so be careful with it!

{tab|for-yourself}

{settings_tab|account-and-privacy}

  1. Under API key, click Manage your API key.

  2. Enter your password, and click Get API key. If you don't know your password, click reset it and follow the instructions from there.

  3. Click Download zuliprc to download your zuliprc file.

!!! tip ""

If you save or move a `zuliprc` file to your home directory as `~/.zuliprc`,
the Python API bindings will automatically read it in (you won't have to
pass the `--config-file` option).

!!! warn ""

Anyone with your API key can impersonate you, so be doubly careful with it.

{end_tabs}

Configuration keys and environment variables

zuliprc is a configuration file written in the INI file format, which contains key-value pairs as shown in the following example:

[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:

zuliprc key Environment variable Required Description
key ZULIP_API_KEY Yes API key, which you can get through Zulip's web interface.
email ZULIP_EMAIL Yes The email address of the user who owns the API key mentioned above.
site ZULIP_SITE No URL where your Zulip server is located.
client_cert_key ZULIP_CERT_KEY No Path to the SSL/TLS private key that the binding should use to connect to the server.
client_cert ZULIP_CERT No* The public counterpart of client_cert_key/ ZULIP_CERT_KEY. This setting is required if a cert key has been set.
client_bundle ZULIP_CERT_BUNDLE No 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.
insecure ZULIP_ALLOW_INSECURE No 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.

Related articles