Zulip Python API Client

Warnings

• gotcha Naming a local file or directory 'zulip.py' or 'zulip' in your project can cause a module shadowing issue, leading to `AttributeError: module 'zulip' has no attribute 'Client'`.
  Fix: Rename your local file/directory to something other than `zulip` to avoid conflicts with the installed `zulip` package.
• breaking Some API queries beyond `send_message` are under active development. While they function, their interfaces or behaviors might change in future versions without major version bumps (as the library is pre-1.0.0).
  Fix: Consult the official Zulip API documentation and the `python-zulip-api` GitHub repository for the latest status of specific API endpoints. If using actively developed APIs, monitor the project's updates.
• gotcha When handling API errors, always check the `response['code']` field for specific error conditions rather than `response['msg']`. The `msg` field is human-readable, internationalized, and its string content can change, making it unreliable for programmatic checks.
  Fix: Implement error handling logic that relies on the machine-readable `code` field in API responses.
• gotcha API success responses might include an `ignored_parameters_unsupported` array. This indicates parameters sent in the request that were not supported by the specific endpoint, potentially signaling a client bug or an attempt to use a new feature on an older Zulip server.
  Fix: Check for this array in responses and adjust your client code or ensure compatibility with the target Zulip server version.
• gotcha Configuration for the `zulip.Client` can be provided via command-line options, environment variables (e.g., `ZULIP_API_KEY`, `ZULIP_EMAIL`, `ZULIP_SITE`), or a `~/.zuliprc` file. The precedence order is command-line > environment variables > config file.
  Fix: Be aware of this precedence when troubleshooting configuration issues. For bots, using a specific `zuliprc` file via `config_file='path/to/zuliprc'` is recommended.

Install

• pip install zulip Install with pip

Imports

• Client

  import zulip
  client = zulip.Client(...)

  While `from zulip import Client` might work, the common and recommended pattern in official examples is `import zulip` followed by `zulip.Client` to avoid name collisions and for consistency with the overall package structure.

Quickstart

Initializes the Zulip client using either a configuration file (like `~/.zuliprc`) or direct credentials, and then sends a stream message. For production, `~/.zuliprc` or environment variables are recommended for securely managing API keys and other credentials. Direct credentials are shown for quick testing, but should be replaced with environment variables for security.

import os
import zulip

# Best practice: configure via ~/.zuliprc or environment variables
# For quick testing, you can pass credentials directly (less secure for production)
# Ensure ZULIP_EMAIL, ZULIP_API_KEY, and ZULIP_SITE environment variables are set
# or a ~/.zuliprc file exists.
# Example using environment variables:

# Initialize client from environment variables (or ~/.zuliprc)
client = zulip.Client(config_file=os.environ.get('ZULIP_CONFIG_FILE', '~/.zuliprc'))

# If using direct credentials for testing (replace with your actual bot/user details)
# client = zulip.Client(
#     email=os.environ.get('ZULIP_EMAIL', 'bot-email@example.com'),
#     api_key=os.environ.get('ZULIP_API_KEY', 'your_api_key'),
#     site=os.environ.get('ZULIP_SITE', 'https://your-domain.zulipchat.com')
# )

# Send a stream message
message = {
    "type": "stream",
    "to": "general",
    "topic": "API Test",
    "content": "Hello from the Zulip Python API!"
}

try:
    result = client.send_message(message)
    if result['result'] == 'success':
        print("Message sent successfully!")
    else:
        print(f"Failed to send message: {result['msg']}")
except Exception as e:
    print(f"An error occurred: {e}")