python-boxcar

NOTE: This is no longer being actively developed but feel free to submit pull requests.

A simple Python library for the Boxcar.io API.

Installation

$ pip install python-boxcar

Getting Started

This API is extremely simple:

from boxcar import Provider

p = Provider(key='vKLoSqB4vhQ4BPZ2TQ4z',
             secret='hPiCqQMuRCDXbkVXYsq4zOu5AGZEZ0bGye7dfl5b')
p.subscribe(email='test@example.com')
p.notify(emails=['test@example.com'],
         from_screen_name='test',
         message='This is a test message.',
         source_url='https://github.com/markcaudill/boxcar',
         icon_url='http://i.imgur.com/RC220wK.png')
p.broadcast(from_screen_name='test',
            message='This is a test message.',
            source_url='https://github.com/markcaudill/boxcar',
            icon_url='http://i.imgur.com/RC220wK.png')

When initializing a Provider object, the secret parameter is only necessary if you plan on using the broadcast method.

Utilities

Included are three command line utilites to allow for easy incorporation into shell scripts:

boxcar-subscribe.py --key='vKLoSqB4vhQ4BPZ2TQ4z' --email='test@example.com'

boxcar-notify.py --key='vKLoSqB4vhQ4BPZ2TQ4z' --from='test'\
    --message='Test Message' --source_url='https://python-boxcar.readthedocs.org/en/latest/'\
    --icon_url='http://i.imgur.com/RC220wK.png' --email test@example.com

boxcar-broadcast.py --key='vKLoSqB4vhQ4BPZ2TQ4z'\
    --secret='hPiCqQMuRCDXbkVXYsq4zOu5AGZEZ0bGye7dfl5b'\
    --from='test' --message='Test Message'\
    --source_url='https://python-boxcar.readthedocs.org/en/latest/'\
    --icon_url='http://i.imgur.com/RC220wK.png'

API

class boxcar.Provider(key=None, secret=None, base='https://boxcar.io/devices/providers/')

An API to Boxcar.io.

broadcast(from_screen_name=None, message=None, from_remote_service_id=None, source_url=None, icon_url=None)

Broadcast to all services.

Parameters:
  • from_screen_name (str) – the user or application sending the message
  • message (str) – the message to display to the user
  • from_remote_service_id (int) – a unique ID to help prevent duplicates
  • source_url (str) – optional URL for user to go to for more info
  • icon_url (str) – optional icon to display with message
notify(emails=None, from_screen_name=None, message=None, from_remote_service_id=None, source_url=None, icon_url=None)

Send a notification to one or more users.

Parameters:
  • emails (list of strs) – the list of email addresses for users to notify
  • from_screen_name (str) – the user or application sending the message
  • message (str) – the message to display to the user
  • from_remote_service_id (int) – a unique ID to help prevent duplicates will be randomly generated if not specified
  • source_url (str) – optional URL for user to go to for more info
  • icon_url (str) – optional icon to display with message
subscribe(email=None)

Subscribe a user to this service (actually sends them a request).

Parameters:email (str) – the user’s email address to add
exception boxcar.exc.BoxcarError(value=None)

Base Boxcar exception class.

exception boxcar.exc.UserAlreadySubscribed(value=None)

Raised when the user is already subscribed to this service.

exception boxcar.exc.UserDoesNotExist(value=None)

Raised when the user is not registerd on Boxcar.io.

exception boxcar.exc.UserNotSubscribed(value=None)

Raised when the user is not currently subscribed to this service.