{"id":2672,"library":"pusher","title":"Pusher Python Library","description":"The `pusher` Python library (current version 3.3.4) provides an interface to interact with the Pusher Channels HTTP API. It enables developers to trigger events to clients, query channel states, validate webhooks, and authenticate private or presence channels. The library is actively maintained with regular updates.","status":"active","version":"3.3.4","language":"en","source_language":"en","source_url":"https://github.com/pusher/pusher-http-python","tags":["web","realtime","websocket","channels","api-client","notifications"],"install":[{"cmd":"pip install pusher","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Default HTTP backend for API calls.","package":"requests"},{"reason":"Optional HTTP backend for AsyncIO.","package":"aiohttp","optional":true},{"reason":"Core dependency for secure communication, updated in v3.3.4.","package":"cryptography"},{"reason":"Core dependency for HTTP requests, updated in v3.3.4.","package":"urllib3"},{"reason":"Core dependency, likely for encryption features, updated in v3.3.4.","package":"pynacl"}],"imports":[{"symbol":"Pusher","correct":"from pusher import Pusher"},{"note":"PusherClient is an internal class; the user-facing client is `Pusher` imported directly from the top-level `pusher` package.","wrong":"from pusher.pusher_client import PusherClient","symbol":"PusherClient","correct":"from pusher import Pusher"}],"quickstart":{"code":"import os\nfrom pusher import Pusher\n\n# Configure Pusher client with environment variables\npusher_client = Pusher(\n    app_id=os.environ.get('PUSHER_APP_ID', 'YOUR_APP_ID'),\n    key=os.environ.get('PUSHER_APP_KEY', 'YOUR_APP_KEY'),\n    secret=os.environ.get('PUSHER_APP_SECRET', 'YOUR_APP_SECRET'),\n    cluster=os.environ.get('PUSHER_APP_CLUSTER', 'us2'), # e.g., 'us2', 'eu', 'ap2'\n    ssl=True\n)\n\n# --- Example 1: Triggering an event ---\ntry:\n    response = pusher_client.trigger(\n        'my-channel',\n        'my-event',\n        {'message': 'hello world'}\n    )\n    print(f\"Event triggered successfully: {response}\")\nexcept Exception as e:\n    print(f\"Error triggering event: {e}\")\n\n# --- Example 2: Authenticating a channel subscription (server-side) ---\n# This typically happens in a web endpoint receiving a POST request\n# from a client, containing socket_id and channel_name.\n\nsocket_id = \"123.456\" # Example socket_id from client\nchannel_name = \"private-my-channel\" # Example channel name\nuser_id = \"user-123\" # Required for presence channels\nuser_info = {\"name\": \"John Doe\"} # Optional, for presence channels\n\ntry:\n    auth_response = pusher_client.authenticate(\n        channel=channel_name,\n        socket_id=socket_id,\n        custom_data={'user_id': user_id, 'user_info': user_info} # Use custom_data for user-specific info\n    )\n    print(f\"Authentication response for {channel_name}: {auth_response}\")\nexcept Exception as e:\n    print(f\"Error authenticating {channel_name}: {e}\")","lang":"python","description":"Initializes the Pusher client using application credentials (preferably from environment variables) and demonstrates how to trigger an event to a channel and how to authenticate a private or presence channel subscription for a client."},"warnings":[{"fix":"Migrate your project to Python 3.6+ or pin to a `pusher` version <3.3.3.","message":"Python 2.x support has been removed, starting from v3.3.3 (tests removed) and implicitly earlier with Python 3.6+ requirement. Users on Python 2.x should use an older version of the library or migrate to Python 3.","severity":"breaking","affected_versions":">=3.3.3"},{"fix":"Install `pip install pusher-push-notifications` and use that library for push notification functionality. Do not use `pusher` for this purpose.","message":"The library no longer supports Push Notifications directly. Support for this feature was removed in v3.0.0. For Push Notifications (Pusher Beams), use the separate `pusher-push-notifications` library.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update your client initialization to use `encryption_master_key_base64` instead of `encryption_master_key`.","message":"The `encryption_master_key` option in the `Pusher` constructor has been deprecated in favor of `encryption_master_key_base64`.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Ensure your event data, after JSON serialization, does not exceed 10KB. Break larger messages into multiple smaller events if necessary.","message":"While the library's internal event payload size limit was increased in v3.3.1, the Pusher Channels API still enforces a 10KB size limit per event payload. Exceeding this will result in an API error.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use the `pusher` library on your server-side application to trigger events. For client-side event reception in Python, consider libraries like `pysher`.","message":"The `pusher` library is for server-side interaction (triggering events, authenticating channels). For client-side WebSocket connections to receive events, you typically need a client-side JavaScript library or a separate Python WebSocket client library like `pysher` (or `pusherclient` for older Python client implementations).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}