{"id":6490,"library":"zulip","title":"Zulip Python API Client","description":"The `zulip` Python library provides official client bindings for the Zulip message API, enabling Python applications to interact with a Zulip server. It handles authentication, request formatting, and offers convenient wrapper methods for various API endpoints. Maintained by the Zulip core team, it is considered the most complete and best-documented client library, actively developed to support features up to Zulip server versions. The current version is `0.9.1` on PyPI, with continuous development in line with the broader Zulip project.","status":"active","version":"0.9.1","language":"en","source_language":"en","source_url":"https://github.com/zulip/python-zulip-api/","tags":["api-client","messaging","chat","bot","collaboration"],"install":[{"cmd":"pip install zulip","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for the library to run.","package":"python","version":">=3.9"},{"reason":"HTTP client for making API requests.","package":"requests","version":">=0.12.1"}],"imports":[{"note":"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.","wrong":"from zulip import Client","symbol":"Client","correct":"import zulip\nclient = zulip.Client(...)"}],"quickstart":{"code":"import os\nimport zulip\n\n# Best practice: configure via ~/.zuliprc or environment variables\n# For quick testing, you can pass credentials directly (less secure for production)\n# Ensure ZULIP_EMAIL, ZULIP_API_KEY, and ZULIP_SITE environment variables are set\n# or a ~/.zuliprc file exists.\n# Example using environment variables:\n\n# Initialize client from environment variables (or ~/.zuliprc)\nclient = zulip.Client(config_file=os.environ.get('ZULIP_CONFIG_FILE', '~/.zuliprc'))\n\n# If using direct credentials for testing (replace with your actual bot/user details)\n# client = zulip.Client(\n#     email=os.environ.get('ZULIP_EMAIL', 'bot-email@example.com'),\n#     api_key=os.environ.get('ZULIP_API_KEY', 'your_api_key'),\n#     site=os.environ.get('ZULIP_SITE', 'https://your-domain.zulipchat.com')\n# )\n\n# Send a stream message\nmessage = {\n    \"type\": \"stream\",\n    \"to\": \"general\",\n    \"topic\": \"API Test\",\n    \"content\": \"Hello from the Zulip Python API!\"\n}\n\ntry:\n    result = client.send_message(message)\n    if result['result'] == 'success':\n        print(\"Message sent successfully!\")\n    else:\n        print(f\"Failed to send message: {result['msg']}\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Rename your local file/directory to something other than `zulip` to avoid conflicts with the installed `zulip` package.","message":"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'`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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).","severity":"breaking","affected_versions":"0.9.x"},{"fix":"Implement error handling logic that relies on the machine-readable `code` field in API responses.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Check for this array in responses and adjust your client code or ensure compatibility with the target Zulip server version.","message":"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.","severity":"gotcha","affected_versions":"Zulip Server 7.0 (feature level 167) and later."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Run `pip install zulip` to install the library.","cause":"The `zulip` library has not been installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'zulip'"},{"fix":"Create a `~/.zuliprc` file with your Zulip server URL, email, and API key, or provide the correct path using `zulip.Client(config_file='path/to/your/zuliprc')`.","cause":"The Zulip client could not locate the `zuliprc` configuration file, which contains your authentication credentials, at its default or specified path.","error":"FileNotFoundError: [Errno 2] No such file or directory: '~/.zuliprc'"},{"fix":"Ensure your `~/.zuliprc` file (or the specified config file) has a `[api]` section containing valid `site`, `email`, and `key` entries.","cause":"The `zuliprc` configuration file is missing one or more required authentication parameters, such as 'site', 'email', or 'key'.","error":"KeyError: 'site'"},{"fix":"Verify that the `email` and `key` in your `zuliprc` file are correct, up-to-date, and belong to a user with the required permissions on your Zulip server.","cause":"The API key or email provided in the `zuliprc` file is incorrect, expired, or the user lacks the necessary permissions for the requested action.","error":"zulip.APIError: {'msg': 'Not authorized for this operation', 'code': 'UNAUTHORIZED', 'result': 'error'}"},{"fix":"Consult the `zulip` library's documentation for the correct method names and usage, for example, `client.send_message()` for sending messages.","cause":"An attempt was made to call a method on the `zulip` Client object that either does not exist or has been misspelled.","error":"AttributeError: 'Client' object has no attribute 'send_message'"}]}