{"id":28532593,"url":"https://github.com/web-push-libs/pywebpush","last_synced_at":"2025-07-07T16:31:16.432Z","repository":{"id":46231003,"uuid":"58676252","full_name":"web-push-libs/pywebpush","owner":"web-push-libs","description":"Python Webpush Data encryption library","archived":false,"fork":false,"pushed_at":"2024-11-19T21:21:21.000Z","size":203,"stargazers_count":340,"open_issues_count":26,"forks_count":56,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-06-20T07:02:33.640Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/web-push-libs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-12T20:56:31.000Z","updated_at":"2025-06-13T23:40:44.000Z","dependencies_parsed_at":"2024-06-18T12:42:21.267Z","dependency_job_id":"bb968365-6f56-4cc3-bd14-039deedbffa1","html_url":"https://github.com/web-push-libs/pywebpush","commit_stats":{"total_commits":110,"total_committers":28,"mean_commits":"3.9285714285714284","dds":0.7272727272727273,"last_synced_commit":"c99d0f7997f6796eff257083baf2a0ad77cfa518"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/web-push-libs/pywebpush","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web-push-libs%2Fpywebpush","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web-push-libs%2Fpywebpush/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web-push-libs%2Fpywebpush/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web-push-libs%2Fpywebpush/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/web-push-libs","download_url":"https://codeload.github.com/web-push-libs/pywebpush/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web-push-libs%2Fpywebpush/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261386873,"owners_count":23150876,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-09T16:09:02.264Z","updated_at":"2025-07-07T16:31:16.426Z","avatar_url":"https://github.com/web-push-libs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Webpush Data encryption library for Python\n\n[![Build Status](https://travis-ci.org/web-push-libs/pywebpush.svg?branch=main)](https://travis-ci.org/web-push-libs/pywebpush)\n[![Requirements Status](https://requires.io/github/web-push-libs/pywebpush/requirements.svg?branch=main)](https://requires.io/github/web-push-libs/pywebpush/requirements/?branch=main)\n\nThis library is available on [pypi as pywebpush](https://pypi.python.org/pypi/pywebpush).\nSource is available on [github](https://github.com/mozilla-services/pywebpush).\nPlease note: This library was designated as a `Critical Project` by PyPi, it is currently\nmaintained by [a single person](https://xkcd.com/2347/). I still accept PRs and Issues, but\nmake of that what you will.\n\n## Installation\n\nTo work with this repo locally, you'll need to run `python -m venv venv`.\nThen `venv/bin/pip install --editable .`\n\n\n## Usage\n\nIn the browser, the promise handler for\n[registration.pushManager.subscribe()](https://developer.mozilla.org/en-US/docs/Web/API/PushManager/subscribe)\nreturns a\n[PushSubscription](https://developer.mozilla.org/en-US/docs/Web/API/PushSubscription)\nobject. This object has a .toJSON() method that will return a JSON object that contains all the info we need to encrypt\nand push data.\n\nAs illustration, a `subscription_info` object may look like:\n\n```json\n{\n  \"endpoint\": \"https://updates.push.services.mozilla.com/push/v1/gAA...\",\n  \"keys\": { \"auth\": \"k8J...\", \"p256dh\": \"BOr...\" }\n}\n```\n\nHow you send the PushSubscription data to your backend, store it\nreferenced to the user who requested it, and recall it when there's\na new push subscription update is left as an exercise for the\nreader.\n\n### Sending Data using `webpush()` One Call\n\nIn many cases, your code will be sending a single message to many\nrecipients. There's a \"One Call\" function which will make things\neasier.\n\n```python\nfrom pywebpush import webpush\n\nwebpush(subscription_info,\n        data,\n        vapid_private_key=\"Private Key or File Path[1]\",\n        vapid_claims={\"sub\": \"mailto:YourEmailAddress\"})\n```\n\nThis will encode `data`, add the appropriate VAPID auth headers if required and send it to the push server identified\nin the `subscription_info` block.\n\n##### Parameters\n\n_subscription_info_ - The `dict` of the subscription info (described above).\n\n_data_ - can be any serial content (string, bit array, serialized JSON, etc), but be sure that your receiving\napplication is able to parse and understand it. (e.g. `data = \"Mary had a little lamb.\"`)\n\n_content_type_ - specifies the form of Encryption to use, either `'aes128gcm'` or the deprecated `'aesgcm'`. NOTE that\nnot all User Agents can decrypt `'aesgcm'`, so the library defaults to the RFC 8188 standard form.\n\n_vapid_claims_ - a `dict` containing the VAPID claims required for authorization (See\n[py_vapid](https://github.com/web-push-libs/vapid/tree/master/python) for more details). If `aud` is not specified,\npywebpush will attempt to auto-fill from the `endpoint`. If `exp` is not specified or set in the past, it will be set\nto 12 hours from now. In both cases, the passed `dict` **will be mutated** after the call.\n\n_vapid_private_key_ - Either a path to a VAPID EC2 private key PEM file, or a string containing the DER representation.\n(See [py_vapid](https://github.com/web-push-libs/vapid/tree/master/python) for more details.) The `private_key` may be\na base64 encoded DER formatted private key, or the path to an OpenSSL exported private key file.\n\ne.g. the output of:\n\n```bash\nopenssl ecparam -name prime256v1 -genkey -noout -out private_key.pem\n```\n\n##### Example\n\n```python\nfrom pywebpush import webpush, WebPushException\n\ntry:\n    webpush(\n        subscription_info={\n            \"endpoint\": \"https://push.example.com/v1/12345\",\n            \"keys\": {\n                \"p256dh\": \"0123abcde...\",\n                \"auth\": \"abc123...\"\n            }},\n        data=\"Mary had a little lamb, with a nice mint jelly\",\n        vapid_private_key=\"path/to/vapid_private.pem\",\n        vapid_claims={\n                \"sub\": \"mailto:YourNameHere@example.org\",\n            }\n    )\nexcept WebPushException as ex:\n    print(\"I'm sorry, Dave, but I can't do that: {}\", repr(ex))\n    # Mozilla returns additional information in the body of the response.\n    if ex.response is not None and ex.response.json():\n        extra = ex.response.json()\n        print(\"Remote service replied with a {}:{}, {}\",\n              extra.code,\n              extra.errno,\n              extra.message\n              )\n```\n\n### Methods\n\nIf you expect to resend to the same recipient, or have more needs than just sending data quickly, you\ncan pass just `wp = WebPusher(subscription_info)`. This will return a `WebPusher` object.\n\nThe following methods are available:\n\n#### `.send(data, headers={}, ttl=0, gcm_key=\"\", reg_id=\"\", content_encoding=\"aes128gcm\", curl=False, timeout=None)`\n\nSend the data using additional parameters. On error, returns a `WebPushException`\n\n##### Parameters\n\n_data_ Binary string of data to send\n\n_headers_ A `dict` containing any additional headers to send\n\n_ttl_ Message Time To Live on Push Server waiting for the client to reconnect (in seconds)\n\n_gcm_key_ Google Cloud Messaging key (if using the older GCM push system) This is the API key obtained from the Google\nDeveloper Console.\n\n_reg_id_ Google Cloud Messaging registration ID (will be extracted from endpoint if not specified)\n\n_content_encoding_ ECE content encoding type (defaults to \"aes128gcm\")\n\n_curl_ Do not execute the POST, but return as a `curl` command. This will write the encrypted content to a local file\nnamed `encrpypted.data`. This command is meant to be used for debugging purposes.\n\n_timeout_ timeout for requests POST query.\nSee [requests documentation](http://docs.python-requests.org/en/master/user/quickstart/#timeouts).\n\n##### Example\n\nto send from Chrome using the old GCM mode:\n\n```python\nWebPusher(subscription_info).send(data, headers, ttl, gcm_key)\n```\n\n#### `.encode(data, content_encoding=\"aes128gcm\")`\n\nEncode the `data` for future use. On error, returns a `WebPushException`\n\n##### Parameters\n\n_data_ Binary string of data to send\n\n_content_encoding_ ECE content encoding type (defaults to \"aes128gcm\")\n\n*Note* This will return a `NoData` exception if the data is not present or empty. It is completely\nvalid to send a WebPush notification with no data, but encoding is a no-op in that case. Best not\nto call it if you don't have data.\n\n##### Example\n\n```python\nencoded_data = WebPush(subscription_info).encode(data)\n```\n\n## Stand Alone Webpush\n\nIf you're not really into coding your own solution, there's also a \"stand-alone\" `pywebpush` command in the\n./bin directory.\n\nThis uses two files:\n\n- the _data_ file, which contains the message to send, in whatever form you like.\n- the _subscription info_ file, which contains the subscription information as JSON encoded data. This is usually returned by the Push `subscribe` method and looks something like:\n\n```json\n{\n  \"endpoint\": \"https://push...\",\n  \"keys\": {\n    \"auth\": \"ab01...\",\n    \"p256dh\": \"aa02...\"\n  }\n}\n```\n\nIf you're interested in just testing your applications WebPush interface, you could use the Command Line:\n\n```bash\n./bin/pywebpush --data stuff_to_send.data --info subscription.info\n```\n\nwhich will encrypt and send the contents of `stuff_to_send.data`.\n\nSee `./bin/pywebpush --help` for available commands and options.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweb-push-libs%2Fpywebpush","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fweb-push-libs%2Fpywebpush","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweb-push-libs%2Fpywebpush/lists"}