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 identity
(account, API key, and Zulip server URL). There are a few ways to
achieve that:
- Using a
zuliprc file, referenced via the --config-file option or
the config_file option to the zulip.Client constructor
(recommended for bots).
- Using a
zuliprc file in your home directory at ~/.zuliprc
(recommended for your own API key).
- Using the environment
variables
documented below.
- Using the
--api-key, --email, and --site variables as command
line parameters.
- Using the
api_key, email, and site parameters to the
zulip.Client constructor.
Download a zuliprc file
-
Click on the gear () icon in the upper
right corner of the web or desktop app.
-
Select Personal settings.
-
On the left, click Bots.
-
Click the download () icon on the profile
card of the desired bot to download the bot's zuliprc file.
Anyone with a bot's API key can impersonate the bot, so be careful with it!
-
Click on the gear () icon in the upper
right corner of the web or desktop app.
-
Select Personal settings.
-
On the left, click Account & privacy.
-
Under API key, click Manage your API key.
-
Enter your password, and click Get API key. If you don't know your
password, click reset it and follow the
instructions from there.
-
Click Download zuliprc to download your zuliprc file.
-
(optional) If you'd like your credentials to be used by default
when using the Zulip API on your computer, move the zuliprc file
to ~/.zuliprc in your home directory.
Anyone with your API key can impersonate you, so be doubly careful with it.
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