Reference¶

Interface¶

Note that all methods can raise RequestError if the server somehow becomes unavailable. They can also raise ServerError if there’s a bug in the server, but that’s fairly unpredictable and in a perfect world would never be able to happen.

class pushjet.Service(secret_key=None, public_key=None)¶

A Pushjet service to send messages through. To receive messages, devices subscribe to these.

Parameters:	secret_key – The service’s API key for write access. If provided, `send()`, `edit()`, and `delete()` become available. Either this or the public key parameter must be present. public_key – The service’s public API key for read access only. Either this or the secret key parameter must be present.
Variables:	name – The name of the service. icon_url – The URL to the service’s icon. May be `None`. created – When the service was created, as seconds from epoch. secret_key – The service’s secret API key, or `None` if the service is read-only. public_key – The service’s public API key, to be used when subscribing to the service.

classmethod create(name, icon_url=None)¶

Create a new service.

Parameters:	name – The name of the new service. icon_url – (optional) An URL to an image to be used as the service’s icon.
Returns:	The newly-created `Service`.

delete()¶: Delete the service. Irreversible.

edit(name=None, icon_url=None)¶

Edit the service’s attributes.

Parameters:	name – (optional) A new name to give the service. icon_url – (optional) A new URL to use as the service’s icon URL. Set to an empty string to remove the service’s icon entirely.

refresh()¶

Refresh the server’s information, in case it could be edited from elsewhere.

Raises:	`NonexistentError` if the service was deleted before refreshing.

send(message, title=None, link=None, importance=None)¶

Send a message to the service’s subscribers.

Parameters:	message – The message body to be sent. title – (optional) The message’s title. Messages can be without title. link – (optional) An URL to be sent with the message. importance – (optional) The priority level of the message. May be a number between 1 and 5, where 1 is least important and 5 is most.

class pushjet.Device(uuid)¶

The “receiver” for messages. Subscribes to services and receives any messages they send.

Parameters:	uuid – The device’s unique ID as a UUID. Does not need to be registered before using it. A UUID can be generated with `uuid.uuid4()`, for example.
Variables:	uuid – The UUID the device was initialized with.

get_messages()¶

Get all new (that is, as of yet unretrieved) messages.

Returns:	A list of `Message`s.

get_subscriptions()¶

Get all the subscriptions the device has.

Returns:	A list of `Subscription`s.

subscribe(service)¶

Subscribe the device to a service.

Parameters:	service – The service to subscribe to. May be a public key or a `Service`.
Returns:	The `Service` subscribed to.
Raises:	`NonexistentError` if the provided service does not exist.
Raises:	`SubscriptionError` if the provided service is already subscribed to.

unsubscribe(service)¶

Unsubscribe the device from a service.

Parameters:	service – The service to unsubscribe from. May be a public key or a `Service`.
Raises:	`NonexistentError` if the provided service does not exist.
Raises:	`SubscriptionError` if the provided service isn’t subscribed to.

class pushjet.Subscription¶

A subscription to a service, with the metadata that entails.

Variables:	service – The service the subscription is to, as a `Service`. time_subscribed – When the subscription was made, as seconds from epoch. last_checked – When the device last retrieved messages from the subscription, as seconds from epoch. device_uuid – The UUID of the device that owns the subscription.

class pushjet.Message¶

A message received from a service.

Variables:	message – The message body. title – The message title. May be `None`. link – The URL the message links to. May be `None`. time_sent – When the message was sent, as seconds from epoch. importance – The message’s priority level between 1 and 5, where 1 is least important and 5 is most. service – The `Service` that sent the message.

Custom API instances¶

class pushjet.Api(url)¶

An API with a custom URL. Use this if you’re connecting to a self-hosted Pushjet API instance, or a non-standard one in general.

Parameters:	url – The URL to the API instance.
Variables:	url – The URL to the API instance, as supplied.

class Device(uuid)¶: Create a Device bound to the API. See pushjet.Device for documentation.

class Api.Service(secret_key=None, public_key=None)¶: Create a Service bound to the API. See pushjet.Service for documentation.

Exceptions¶

exception pushjet.PushjetError¶: All the errors inherit from this. Therefore, except PushjetError catches all errors.

exception pushjet.AccessError¶: Raised when a secret key is missing for a service method that needs one.

exception pushjet.NonexistentError¶: Raised when an attempt to access a nonexistent service is made.

exception pushjet.SubscriptionError¶: Raised when an attempt to subscribe to a service that’s already subscribed to, or to unsubscribe from a service that isn’t subscribed to, is made.

exception pushjet.RequestError¶

Raised if something goes wrong in the connection to the API server. Inherits from ConnectionError on Python 3, and can therefore be caught with except ConnectionError there.

Variables:	requests_exception – The underlying requests exception. Access this if you want to handle different HTTP request errors in different ways.

exception pushjet.ServerError¶: Raised if the API server has an error while processing your request. This getting raised means there’s a bug in the server! If you manage to track down what caused it, you can open an issue on Pushjet’s GitHub page.