judell / h_notify

hypothesis notification prototype

Overview

This tool watches Hypothesis URLs, groups, tags, or users, and alerts on new annotation activity to Slack, email, or RSS. It runs as a standalone Python program, ideally on a server, but alternatively on an always-connected desktop computer. It periodically queries the Hypothesis API along one or more axes -- url (or wildcard_uri), user, group, tag -- and sends notifications by way of Slack, email, or RSS.

See examples.py for recipes. To run a modified version of it, copy hypothesis.py (from https://github.com/judell/Hypothesis), h_notify.py, and examples.py into a directory, adjust examples.py as needed, and run python examples.py.

The pickle argument to methods like notify_slack_url_activity, notify_slack_group_activity, notify_email_tag_activity, and notify_rss_group_activity names a file that's created, then updated, to remember the IDs of annotations already seen. So, for example, this call ...

notify_slack_url_activity(url='https://web.hypothes.is/*', token=default_token, pickle='urls', channel='test', hook=default_hook)

... remembers IDs in urls.pickle.

Slack

Web hook

You'll need an "incoming web hook" which you create in Slack: https://api.slack.com/incoming-webhooks

@-mentions

To enable Slack @-mentions, create a file called slack_namemap.json like so:

{
  "https://hooks.slack.com/services/T03Q...gyzy" :
    {
    "@dave": "UC...DG",
    "@dwhly": "U0...CT",
    "@hmstepanek": "U8...2W",
    "@judell": "U0...AV",
    "@nateangell": "U3...U9",
    "@katelyn": "U8...72",
    }
}

The values are internal Slack IDs which you can find at https://api.slack.com/methods/users.list/test

Note that Slack usernames may be, but are not necessarily, the same as Hypothesis usernames. If I want to notify Dave Wolfe, whose Hypothesis username is dwolfe, I'll need to write his Slack handle, @dave, in the body of an annotation that's posted to a page monitored by this service.

RSS

RSS feeds are inherently unauthenticated, but access to Hypothesis private annotations requires authentication, so you can't use https://hypothes.is/stream.rss or https://hypothes.is/stream.atom to receive feeds of private annotation activity.

This tool authenticates to the Hypothesis API and produces XML files that you can then serve to RSS readers at unauthenticated-but-secret URLs. You will, however, need to host those files where RSS readers can get them.

The pickle argument in this case also names an XML file that contains an RSS feed. So, for example, given this call ...

notify_rss_group_activity(group='8gk9i7VV', groupname='Anyone Can Join', token=default_token, pickle='8gk9i7VV')

... the IDs are remembered in 8gk9i7VV.pickle and the feed is generated into 8gk9i7VV.xml.

email

You'll need to set up credentials like so:

default_smtp_server = 'smtp.example.com' 
default_email_sender = '[email protected]'
default_email_password = 'q1...Nm'

h_notify's Issues

ImportError: cannot import name 'Hypothesis'

I'm getting an error with both Python 2.7.5 and Python 3.6.9:

ImportError: cannot import name 'Hypothesis'

I didn't see any information in the README about installing requirements (maybe I missed something?) but here's what I tried:

Install hypothesis:

~$ pip install hypothesis
Defaulting to user installation because normal site-packages is not writeable
Requirement already satisfied: hypothesis in ./.local/lib/python3.6/site-packages (5.6.0)
Requirement already satisfied: sortedcontainers<3.0.0,>=2.1.0 in ./.local/lib/python3.6/site-packages (from hypothesis) (2.1.0)
Requirement already satisfied: attrs>=19.2.0 in ./.local/lib/python3.6/site-packages (from hypothesis) (19.3.0)

Run the program:

~$ python3 h_notify.py
Traceback (most recent call last):
  File "h_notify.py", line 2, in <module>
    from hypothesis import Hypothesis, HypothesisAnnotation
ImportError: cannot import name 'Hypothesis'

pip install problems

Hello,

I just tried to use your python script and before running it, I just tried to install dependencies this way:

pip install dateutil json markdown pickle re requests smtplib
Defaulting to user installation because normal site-packages is not writeable
ERROR: Could not find a version that satisfies the requirement dateutil (from versions: none)
ERROR: No matching distribution found for dateutil

Do you have any idea why it occurs?

Default to using notified_ids=[]

From: https://hypothesis.zendesk.com/agent/tickets/6010
Not entirely sure I have this right, so feel free to give me feedback:

User is trying to add Slack to the tools they're using, and wasn't adding "notified_ids=[]". You decided it should default to that.

Finally, you wrote:
"The error is just a traceback that's unnecessarily printed if namemap.json doesn't exist. But you should really try it, it's very cool to be able to @mention somebody's Slack name in an annotation and have them be tagged in Slack."

Full annotation content via email or RSS

Would it be possible to send the whole annotation content over email/RSS rather than a notification that there’s a new annotation?

I’m basically trying to create a system to replicate every Hypothesis annotation I write (so private ones) to another system (let’s say Wordpress) via Zapier or IFTTT.

Is RSS from wildcard URL supported?

Do you support getting RSS from a wildcard URL (domain), i.e., something like this?

notify_rss_url_activity(url='https://theatlantic.com/*', token=default_token, pickle='akVkkdfu')

When I tried the above I got NameError: name 'notify_rss_url_activity' is not defined.
I was able to run the RSS recipe in examples.py without errors.

On a fresh Ubuntu 18.04 VM, I had to install the following pip packages first:

sudo apt install python3-pip
pip3 install feedgen markdown python-dateutil pytz wheel