{"id":13814245,"url":"https://github.com/djacobs/PyAPNs","last_synced_at":"2025-05-15T03:33:16.328Z","repository":{"id":983276,"uuid":"786406","full_name":"djacobs/PyAPNs","owner":"djacobs","description":"Python library for interacting with the Apple Push Notification service (APNs)","archived":false,"fork":false,"pushed_at":"2021-02-10T23:30:03.000Z","size":117,"stargazers_count":1224,"open_issues_count":57,"forks_count":370,"subscribers_count":52,"default_branch":"master","last_synced_at":"2025-04-13T23:53:50.840Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://pypi.python.org/pypi/apns/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/djacobs.png","metadata":{"files":{"readme":"README.markdown","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2010-07-20T12:22:00.000Z","updated_at":"2025-03-29T20:17:32.000Z","dependencies_parsed_at":"2022-08-16T11:40:49.904Z","dependency_job_id":null,"html_url":"https://github.com/djacobs/PyAPNs","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djacobs%2FPyAPNs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djacobs%2FPyAPNs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djacobs%2FPyAPNs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djacobs%2FPyAPNs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/djacobs","download_url":"https://codeload.github.com/djacobs/PyAPNs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254254043,"owners_count":22039792,"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":"2024-08-04T04:01:48.626Z","updated_at":"2025-05-15T03:33:16.058Z","avatar_url":"https://github.com/djacobs.png","language":"Python","readme":"# PyAPNs \n\nA Python library for interacting with the Apple Push Notification service \n(APNs)\n\n## Installation\n\nEither download the source from GitHub or use easy_install:\n\n    $ easy_install apns\n\n## Sample usage\n\n```python\nimport time\nfrom apns import APNs, Frame, Payload\n\napns = APNs(use_sandbox=True, cert_file='cert.pem', key_file='key.pem')\n\n# Send a notification\ntoken_hex = 'b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b87'\npayload = Payload(alert=\"Hello World!\", sound=\"default\", badge=1)\napns.gateway_server.send_notification(token_hex, payload)\n\n# Send an iOS 10 compatible notification\ntoken_hex = 'b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b87'\npayload = Payload(alert=\"Hello World!\", sound=\"default\", badge=1, mutable_content=True)\napns.gateway_server.send_notification(token_hex, payload)\n\n# Send multiple notifications in a single transmission\nframe = Frame()\nidentifier = 1\nexpiry = time.time()+3600\npriority = 10\nframe.add_item('b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b87', payload, identifier, expiry, priority)\napns.gateway_server.send_notification_multiple(frame)\n```\n\nApple recommends to query the feedback service daily to get the list of device tokens. You need to create a new connection to APNS to see all the tokens that have failed since you only receive that information upon connection. Remember, once you have viewed the list of tokens, Apple will clear the list from their servers. Use the timestamp to verify that the device tokens haven’t been reregistered since the feedback entry was generated. For each device that has not been reregistered, stop sending notifications. By using this information to stop sending push notifications that will fail to be delivered, you reduce unnecessary message overhead and improve overall system performance.\n\n```\n#New APNS connection\nfeedback_connection = APNs(use_sandbox=True, cert_file='cert.pem', key_file='key.pem')\n\n# Get feedback messages.\nfor (token_hex, fail_time) in feedback_connection.feedback_server.items():\n    # do stuff with token_hex and fail_time\n```\n\n\nFor more complicated alerts including custom buttons etc, use the PayloadAlert \nclass. Example:\n\n```python\nalert = PayloadAlert(\"Hello world!\", action_loc_key=\"Click me\")\npayload = Payload(alert=alert, sound=\"default\")\n```\n\nTo send custom payload arguments, pass a dictionary to the custom kwarg\nof the Payload constructor.\n\n```python\npayload = Payload(alert=\"Hello World!\", custom={'sekrit_number':123})\n```\n\n### Enhanced Message with immediate error-response\n```python\napns_enhanced = APNs(use_sandbox=True, cert_file='apns.pem', enhanced=True)\n```\n\nSend a notification. note that `identifer` is the information to indicate which message has error in error-response payload, it should be **UNIQUE** since PyAPNs will also use it to determine the range of messages to be re-sent.\n```python\ntoken_hex = 'b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b87'\npayload = Payload(alert=\"Hello World!\", sound=\"default\", badge=1)\nidentifier = random.getrandbits(32)\napns_enhanced.gateway_server.send_notification(token_hex, payload, identifier=identifier)\n```\n\nCallback when error-response occur, with parameter `{'status': \u003cstatus code from APNS\u003e, 'identifier': \u003cthe identifier specified\u003e}`\n[Status code reference](https://developer.apple.com/library/ios/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/CommunicatingWIthAPS.html#//apple_ref/doc/uid/TP40008194-CH101-SW4)\n```python\ndef response_listener(error_response):\n    _logger.debug(\"client get error-response: \" + str(error_response))\n\napns_enhanced.gateway_server.register_response_listener(response_listener)\n```\n\nError response worker will be auto-close after 30 secs idle of connection operations.\nIf you want disable APNS connection and error-responses handler immediately, force_close it.\n```python\napns_enhanced.gateway_server.force_close()\n```\n\nExtra log messages when error-response occur, auto-resent afterwards.\n\n    got error-response from APNS:(8, 1)\n    rebuilding connection to APNS\n    resending 9 notifications to APNS\n    resending notification with id:2 to APNS\n    resending notification with id:3 to APNS\n    resending notification with id:4 to APNS\n\nCaveats:\n\n* Currently support single notification only\n\nProblem Addressed ([Reference to Redth](http://redth.codes/the-problem-with-apples-push-notification-ser/)):\n\n* Async response of error response and response time varies from 0.1 ~ 0.8 secs by observation\n* Sent success do not response, which means client cannot always expect for response.\n* Async close write stream connection after error-response.\n* All notification sent after failed notification are discarded, the responding error-response and closing client's write connection will be delayed\n* Sometimes APNS close socket connection arbitrary\n\nSolution:\n\n* Non-blocking ssl socket connection to send notification without waiting for response.\n* A separate thread for constantly checking error-response from read connection.\n* A sent notification buffer used for re-sending notification that were sent after failed notification, or arbitrary connection close by apns.\n* Reference to [non-blocking apns pull request by minorblend](https://github.com/djacobs/PyAPNs/pull/25), [enhanced message by hagino3000](https://github.com/voyagegroup/apns-proxy-server/blob/065775f87dbf25f6b06f24edc73dc5de4481ad36/apns_proxy_server/worker.py#l164-209)\n\nResult:\n\n* Send notification at throughput of 1000/secs\n* In worse case of when 1st notification sent failed, error-response respond after 1 secs and 999 notification sent are discarded by APNS at the mean time, all discarded 999 notifications will be resent without loosing any of them. With the same logic, if notification resent failed, it will resent rest of resent notification after the failed one.\n\n## Test ##\n* [Test Script](https://gist.github.com/jimhorng/594401f68ce48282ced5)\n\n## Travis Build Status\n\n[![Build Status](https://secure.travis-ci.org/djacobs/PyAPNs.png?branch=master)](http://travis-ci.org/djacobs/PyAPNs)\n\n## Further Info\n\n[iOS Reference Library: Local and Push Notification Programming Guide][a1]\n\n## License\n\nPyAPNs is distributed under the terms of the MIT license.\n\nSee [LICENSE](LICENSE) file for the complete license details.\n\n## Credits\n\nWritten and maintained by Simon Whitaker at [Goo Software Ltd][goo].\n\n[a1]:https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/index.html#//apple_ref/doc/uid/TP40008194-CH3-SW1\n[goo]:http://www.goosoftware.co.uk/\n","funding_links":[],"categories":["Python","etc"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjacobs%2FPyAPNs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdjacobs%2FPyAPNs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjacobs%2FPyAPNs/lists"}