{"id":5852,"library":"apns2","title":"APNs2 Python Library","description":"apns2 is a Python library for interacting with the Apple Push Notification Service (APNs) using the HTTP/2 protocol. It supports both certificate-based and token-based authentication. The current version is 0.7.2, with development showing sporadic updates, often addressing dependency compatibility and APNs specification changes.","status":"active","version":"0.7.2","language":"en","source_language":"en","source_url":"https://github.com/Pr0Ger/PyAPNs2","tags":["APNs","Apple Push Notifications","iOS","push notifications","HTTP/2","JWT"],"install":[{"cmd":"pip install apns2","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for cryptographic operations, including handling APNs authentication keys.","package":"cryptography","optional":false},{"reason":"Required for token-based authentication (JWT). Must be less than version 2.0.0.","package":"PyJWT","optional":false}],"imports":[{"symbol":"APNsClient","correct":"from apns2.client import APNsClient"},{"symbol":"Payload","correct":"from apns2.payload import Payload"},{"symbol":"TokenCredentials","correct":"from apns2.credentials import TokenCredentials"}],"quickstart":{"code":"import os\nfrom apns2.client import APNsClient\nfrom apns2.payload import Payload\nfrom apns2.credentials import TokenCredentials\n\n# Environment variables for token-based authentication\n# Set these in your environment or replace with actual values for testing\nAUTH_KEY_PATH = os.environ.get('APNS_AUTH_KEY_PATH', 'path/to/AuthKey_ABCDEFG.p8')\nAUTH_KEY_ID = os.environ.get('APNS_AUTH_KEY_ID', 'ABCDEFG')\nTEAM_ID = os.environ.get('APNS_TEAM_ID', 'XXXXXXXXXX')\nDEVICE_TOKEN = os.environ.get('APNS_DEVICE_TOKEN', 'your_device_token_here')\nAPP_BUNDLE_ID = os.environ.get('APNS_APP_BUNDLE_ID', 'com.example.YourApp')\n\nif AUTH_KEY_PATH == 'path/to/AuthKey_ABCDEFG.p8' or \\\n   AUTH_KEY_ID == 'ABCDEFG' or \\\n   TEAM_ID == 'XXXXXXXXXX' or \\\n   DEVICE_TOKEN == 'your_device_token_here' or \\\n   APP_BUNDLE_ID == 'com.example.YourApp':\n    print(\"WARNING: Please configure APNS_AUTH_KEY_PATH, APNS_AUTH_KEY_ID, APNS_TEAM_ID, APNS_DEVICE_TOKEN, and APNS_APP_BUNDLE_ID environment variables or replace placeholders in the script.\")\n    # Exit or use dummy values for demonstration if actual push is not intended\n    # For a runnable example without valid credentials, one might comment out the actual send_notification call\n    # For this registry, we will print a warning and allow it to run potentially failing.\n\ntry:\n    # Initialize TokenCredentials\n    credentials = TokenCredentials(\n        auth_key_path=AUTH_KEY_PATH,\n        auth_key_id=AUTH_KEY_ID,\n        team_id=TEAM_ID\n    )\n\n    # Initialize APNsClient with token credentials\n    # For development (sandbox) environment, use_sandbox=True\n    client = APNsClient(credentials=credentials, use_sandbox=True) # Set to False for production\n\n    # Create a push notification payload\n    payload = Payload(alert=\"Hello from apns2!\", sound=\"default\", badge=1)\n\n    # Send the notification\n    response = client.send_notification(DEVICE_TOKEN, payload, APP_BUNDLE_ID)\n\n    print(f\"APNs Response Status: {response.status}\")\n    print(f\"APNs Response Reason: {response.reason}\")\n    if response.apns_id: # Optional, depending on library version/response structure\n        print(f\"APNs ID: {response.apns_id}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"This quickstart demonstrates sending a push notification using token-based authentication, which is recommended by Apple. Ensure you have your APNs authentication key (.p8 file), Key ID, Team ID, app bundle ID, and a target device token. These values are typically obtained from your Apple Developer account. It uses environment variables for sensitive credentials."},"warnings":[{"fix":"Ensure your environment or `requirements.txt` explicitly specifies `PyJWT<2.0.0`. If other libraries demand `PyJWT>=2.0.0`, consider using a dedicated virtual environment or finding an alternative for APNs if upgrading `apns2` is not an option.","message":"The library has a strict dependency on `PyJWT<2.0.0`. Installing or having other packages that require `PyJWT` version 2.0.0 or higher will lead to compatibility issues and runtime errors.","severity":"breaking","affected_versions":"0.7.2 and earlier"},{"fix":"Upgrade your Python interpreter to Python 3.5 or newer.","message":"As of version 0.6.0, `apns2` officially dropped support for Python 2.7 and Python 3.4. Users on these Python versions must either upgrade their Python environment or use an older version of `apns2`.","severity":"breaking","affected_versions":"<0.6.0"},{"fix":"Switch to token-based authentication using `TokenCredentials` as shown in the quickstart example. This requires an authentication key (.p8 file), Key ID, and Team ID from your Apple Developer account.","message":"Apple officially deprecated the legacy binary APNs protocol (certificate-based authentication) on March 31, 2021, in favor of the HTTP/2 API with token-based authentication. While `apns2` supports both, new implementations and existing ones should migrate to token-based authentication.","severity":"deprecated","affected_versions":"All versions supporting certificate-based auth"},{"fix":"Ensure your token generation logic and client configurations are aware of the shorter default lifetime. If you rely on custom JWT lifetimes, upgrade to 0.7.2 or newer to ensure they are respected.","message":"The default JWT token lifetime (`DEFAULT_TOKEN_LIFETIME`) was changed from 3600 seconds (1 hour) to 2700 seconds (45 minutes) in version 0.7.2. This aligns with Apple's recommendation to refresh tokens frequently (typically within one hour) to avoid `ExpiredProviderToken` errors. Additionally, in versions prior to 0.7.2, custom JWT lifetimes passed to `TokenCredentials` might have been ignored.","severity":"gotcha","affected_versions":"<0.7.2"},{"fix":"If precise control over the `apns-push-type` header is needed, explicitly set it in your `Payload` or `Notification` object when sending.","message":"Since version 0.7.0, `apns2` attempts to infer the `apns-push-type` header from the push topic or payload. While an option to override this header exists, automatic inference might lead to unexpected behavior if specific push types are required without explicit setting.","severity":"gotcha","affected_versions":"0.7.0 and later"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}