galerts

exception galerts.SignInError

Raised when Google sign in fails.

exception galerts.UnexpectedResponseError(status, headers, body)

Raised when Google’s response to a request is unrecognized.

class galerts.Alert(email, s, query, type, freq, vol, deliver, feedurl=None)

Models a Google Alert.

You should not create Alert objects explicitly; the GAlertsManager will create them for you. You can then access alert objects via GAlertsManager.alerts to e.g. update their attributes and pass them back to the manager for saving. To create a new alert, use GAlertsManager.create, and when you next access GAlertsManager.alerts you’ll find an Alert object there for the alert you just created.

deliver

The delivery method for this alert.

Raises ValueError:  if value is not in DELIVER_TYPES

email

Returns the email address of the manager that created this alert.

feedurl

For feed alerts, returns the url of the feed results are delivered to. For email alerts, returns None.

Note: If you change an Alert object from a feed alert to an email alert (or vice versa) via Alert.deliver, the value of Alert.feedurl is not updated. You must pass the alert to GAlertsManager.update to save the changes and then get a fresh Alert object from GAlertsManager.alerts to get the up-to-date feed url.

freq

The frequency with which results are delivered for this alert.

Raises ValueError:  if value is not in ALERT_FREQS

query

The search terms this alert will match.

Raises ValueError:  if value is not unicode or unicode(value) fails, or if its length exceeds QUERY_MAXLEN

type

The type of the results this alert delivers.

Raises ValueError:  if value is not in ALERT_TYPES

vol

The volume of results delivered for this alert.

Raises ValueError:  if value is not in ALERT_VOLS

class galerts.GAlertsManager(email, password)

Manages creation, modification, and deletion of Google Alerts for the Google account associated with email.

Resorts to html scraping because no public API has been released.

Note: multiple email addresses can be associated with a single Google account, and if a user with multiple email addresses associated with her Google account signs into the web interface, it will allow her to set the delivery of email alerts to any of her associated email addresses. However, for now, GAlertsManager always uses the email address it’s instantiated with when creating new email alerts or changing feed alerts to email alerts.

Parameters:

• email – sign in using this email address. If there is no @ symbol in the value, “@gmail.com” will be appended.
• password – plaintext password, used only to get a session cookie. Sent over a secure connection and then discarded.

Raises:

• SignInError – if Google responds with “403 Forbidden” to our request to sign in
• UnexpectedResponseError – if the status code of Google’s response is unrecognized (neither 403 nor 200)
• socket.error – e.g. if there is no network connection

create(query, type, feed=True, freq='once a day', vol='Only the best results')

Creates a new alert.

Parameters:

• query – the search terms the alert will match
• type – a value in ALERT_TYPES
• feed – whether to deliver results via feed or email
• freq – a value in ALERT_FREQS indicating how often results should be delivered; used only for email alerts (feed alerts are updated in real time). Defaults to FREQ_ONCE_A_DAY.
• vol – a value in ALERT_VOLS indicating volume of results to be delivered. Defaults to VOL_ONLY_BEST.

delete(alert)

Deletes an existing alert.

update(alert)

Updates an existing alert which has been modified.

alerts

Queries Google on every access for the alerts associated with this account, wraps them in Alert objects, and returns a generator you can use to iterate over them.

galerts.ALERT_FREQS

maps available alert frequencies to the values Google uses for them

galerts.ALERT_TYPES

maps available alert types to the values Google uses for them

galerts.ALERT_VOLS

maps available alert volumes to the values Google uses for them

galerts.DELIVER_EMAIL

Use this value to indicate delivery via email

galerts.DELIVER_FEED

Use this value to indicate delivery via feed

galerts.DELIVER_TYPES

maps available delivery types to the values Google uses for them

galerts.FREQ_AS_IT_HAPPENS

Use this value for Alert.freq to indicate delivery in real time

galerts.FREQ_ONCE_A_DAY

Use this value for Alert.freq to indicate delivery once a day

galerts.FREQ_ONCE_A_WEEK

Use this value for Alert.freq to indicate delivery once a week

galerts.QUERY_MAXLEN

The maximum length of an alert query

galerts.TYPE_BLOGS

Use this value for Alert.type to indicate blog results

galerts.TYPE_DISCUSSIONS

Use this value for Alert.type to indicate discussion results

galerts.TYPE_EVERYTHING

Use this value for Alert.type to indicate all results

galerts.TYPE_NEWS

Use this value for Alert.type to indicate news results

galerts.TYPE_REALTIME

Use this value for Alert.type to indicate realtime results

galerts.TYPE_VIDEO

Use this value for Alert.type to indicate video results

galerts.VOL_ALL

Use this value for an alert volume of all results

galerts.VOL_ONLY_BEST

Use this value for an alert volume of only the best results