wallet-py3k (Apple Passbook Generator)

0.0.4 · abandoned · verified Thu Apr 16

wallet-py3k is a Python 3 library designed to generate Apple Wallet (.pkpass) files. It is a fork of the `devartis/passbook` library, specifically updated to support Python 3. The library enables programmatic creation of various pass types by assembling content, signing with required Apple certificates, and packaging them into the `.pkpass` format. The last release (0.0.4) was in December 2018, indicating the library is no longer actively maintained.

Common errors

```
Error creating pass: Command '['/usr/bin/zip', '--version']' returned non-zero exit status 1.
```
cause This error usually indicates that the `zip` command-line utility, which `wallet-py3k` uses internally, is not found or not executable in the environment where the Python script is run.

fix Ensure that the `zip` utility is installed and available in your system's PATH. On Debian/Ubuntu: `sudo apt-get install zip`. On macOS: `zip` is usually pre-installed. For Windows, you might need to install a `zip` utility or a WSL environment.
```
Error creating pass: [SSL: BAD_DECRYPT] bad decrypt (_ssl.c:2722)
```
cause This error typically means the password provided for the `key.pem` file is incorrect or the `key.pem` itself is corrupted/invalid. This is a common issue during the `passfile.create` step.

fix Double-check the password passed to `passfile.create`. Verify that `key.pem` was generated with the correct `openssl` command and that you provided a password when it was created. Regenerate `key.pem` and `certificate.pem` if necessary, ensuring to set a password for the key.
```
Error creating pass: [Errno 2] No such file or directory: 'icon.png'
```
cause The `addFile` method for `icon.png` or `logo.png` failed because the specified image file could not be found at the given path.

fix Ensure that the `icon.png` and `logo.png` files exist in the location specified in your `passfile.addFile` calls. If they are in a subdirectory (e.g., 'images/'), make sure that subdirectory exists and contains the files.
```
AttributeError: module 'wallet' has no attribute 'models'
```
cause This happens when you try to import `wallet` directly and then access `wallet.models`. The `models` submodule is not directly exposed this way.

fix Always import specific classes from `wallet.models` using `from wallet.models import Pass, Barcode, StoreCard`.

Warnings

breaking The library has not been updated since December 2018 and is effectively abandoned. Apple's PassKit requirements and APIs may have evolved, potentially rendering passes generated by this library invalid or incompatible with modern Apple Wallet versions or iOS versions.
Fix: Thoroughly test generated passes on current iOS devices. Consider alternative, actively maintained libraries or direct Apple PassKit API interaction if full compatibility is critical.
gotcha Generating valid `.pem` certificate files from your Apple Developer account `.p12` file is a complex and error-prone process involving `openssl` commands. Incorrectly formatted or expired certificates will lead to pass creation failures.
Fix: Carefully follow the `openssl` commands provided in the quickstart or similar documentation to generate `certificate.pem`, `key.pem`, and `wwdr.pem`. Ensure the `key.pem` is generated with a password, and this password is correctly supplied to the `passfile.create` method.
gotcha The `key.pem` file, generated from your `.p12` certificate, *must* be secured with a password during its creation via `openssl`. Failing to provide a password when prompted by `openssl` will result in an unusable key and subsequent errors during pass signing.
Fix: When running `openssl pkcs12 -in "Certificates.p12" -nocerts -out key.pem`, ensure you set a strong password. Then, pass this exact password to the `passfile.create` method via the `key_password` argument.
gotcha Apple Wallet passes strictly require `icon.png` and `logo.png` files to be included within the pass bundle to be considered valid. Omission of these files will cause the pass to fail validation or display correctly.
Fix: Always include `icon.png` (29x29pt @1x, @2x, @3x) and `logo.png` (160x50pt @1x, @2x, @3x) using `passfile.addFile('icon.png', open('path/to/icon.png', 'rb'))` and similarly for `logo.png`.

Install

pip install wallet-py3k Install with pip

Imports

Pass, Barcode, StoreCard
wrong:
```
import wallet
```
correct:
```
from wallet.models import Pass, Barcode, StoreCard
```
Directly importing 'wallet' does not expose the necessary models. Always import specific classes from `wallet.models`.

Quickstart

This quickstart demonstrates how to create a simple StoreCard pass. It requires pre-generated `.pem` certificate files and `wwdr.pem`, along with `icon.png` and `logo.png` image assets. The `create` method then generates the `.pkpass` file.

import os
from wallet.models import Pass, Barcode, StoreCard

# --- Prerequisites: Generate .pem files from your Apple Pass Type ID certificate ---
# 1. Obtain a Pass Type ID certificate from Apple's developer portal (.p12).
# 2. Convert it to .pem files using OpenSSL (replace "Certificates.p12" with your file):
#    openssl pkcs12 -in "Certificates.p12" -clcerts -nokeys -out certificate.pem
#    openssl pkcs12 -in "Certificates.p12" -nocerts -out key.pem -passout pass:YOUR_KEY_PASSWORD
# 3. Download the Apple Worldwide Developer Relations Certification Authority (WWDR) certificate
#    from Apple's website (http://developer.apple.com/certificationauthority/AppleWWDRCA.cer)
#    and convert it to .pem (e.g., wwdr.pem).

# Ensure these files exist in your working directory or provide full paths.
certificate_path = 'certificate.pem'
key_path = 'key.pem'
wwdr_path = 'wwdr.pem'
key_password = os.environ.get('WALLET_KEY_PASSWORD', 'YOUR_KEY_PASSWORD') # Replace with your actual key password or use env var

# Define pass details
organization_name = 'Your Organization'
pass_type_identifier = 'pass.com.your.organization'
team_identifier = 'AGK5BZEN3E' # Replace with your Apple Team ID

# Create card information
card_info = StoreCard()
card_info.addPrimaryField('name', 'John Doe', 'Name')
card_info.addAuxiliaryField('member_id', '12345', 'Member ID')

# Create the Pass object
passfile = Pass(card_info,
                passTypeIdentifier=pass_type_identifier,
                organizationName=organization_name,
                teamIdentifier=team_identifier)

passfile.serialNumber = '1234567'
passfile.barcode = Barcode(message='Barcode message content', format='PKBarcodeFormatQR')

# Add required assets (icon and logo are mandatory for a valid pass)
# Ensure 'images/icon.png' and 'images/logo.png' exist relative to your script
try:
    with open('images/icon.png', 'rb') as f_icon:
        passfile.addFile('icon.png', f_icon)
    with open('images/logo.png', 'rb') as f_logo:
        passfile.addFile('logo.png', f_logo)
except FileNotFoundError:
    print("Error: icon.png or logo.png not found. Please create 'images/' directory and place the files.")
    exit(1)

output_filename = 'test.pkpass'

# Create and output the Passbook file
try:
    passfile.create(
        certificate_path, 
        key_path, 
        wwdr_path, 
        key_password, 
        output_filename
    )
    print(f"Successfully created {output_filename}")
except Exception as e:
    print(f"Error creating pass: {e}")
    print("Ensure your .pem files are correct and the key_password is accurate.")

view raw JSON →