Skip to main content

Python library for the API

Project description

This package provides python bindings to the Hypothesis API.

Low-level access

The api submodule is a low-level implementation of the Hypothesis API.

The contents of this module reflect the REST nature of the API:

  • API calls are made by functions.
  • Input and output data are uninterpreted data (e.g. JSON strings, not objects resulting from interpreting the JSON).
  • Argument checking is minimal and most exceptions will come when the API returns an error (APIError is raised if the server does not return 200).
  • The auth argument is always given first (except to root(), which does not take authorization). auth can currently be None or a string containing a developer token.


>>>, '53LMZGVCEemN4zOvm3oFEQ')
u'{"updated": "2019-04-22T21:09:23.352503+00:00", "group": "__world__", ...
>>>, 'bogusannotationid')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "h_annot/", line 39, in read
    raise APIError(r)
h_annot.exceptions.APIError: API call returned 404 (Not Found): not_found

High-level access

The Annotation class is an object abstraction of an annotation. Use the load() class method to get an annotation from its ID:

>>> annot = h_annot.Annotation.load('53LMZGVCEemN4zOvm3oFEQ')
>>> annot.text
u"I'm imagining!!!"

Exceptions are more pythonic:

>>> h_annot.Annotation.load('somebogusannotid')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "h_annot/", line 97, in load
    raise KeyError('annotation ID %s not found' % annot_id)
KeyError: 'annotation ID somebogusannotid not found'

The Annotation constructor should not be called directly.

Some attributes can be updated; to do so, set the authentication token using the h_annot.auth() context manager:

>>> with h_annot.auth(authentication_token):
...     annot.text = 'new text'

Annotations don’t have an inherent concept of authentication, so the previous way of declaring authentication to annotations:

>>> annot = h_annot.Annotation.load('someannotationid', 'somedevelkey')
>>> annot.text = 'new text'

is deprecated.

Tags are accessed and changed through the tags attribute. This attribute acts like a case-insensitive set (like Hypothesis itself treats tags).

>>> print annot.tags
TagSet(objectives, interwebs)
>>> for tag in annot.tags:
...     print tag
>>> with h_annot.auth(authentication_token):
...     annot.tags = ['all', 'new', 'tags']
...     annot.tags.add('and one more')
...     annot.tags.remove('new')

Searching via is deprecated. This search just wrapped the results of in Annotation constructors, so should now be used for searches that used For a high-level search interface, use This takes keyword arguments uri, user, tags, and text. Note that tags are joined by AND and separate words in text are joined by OR, which is the behavior of the Hypothesis search API. respects the authentication set by the h_annot.auth() context manager. returns a SearchResults instance. SearchResults instances respond properly to len(), and iteration will result in annotations:

>>> results =
>>> len(results)
>>> for annotation in results:
...     print(annotation)
...     break
<Hypothesis annotation WcxuNG0CEemcl4_d0fJoaw>

The SearchResults object will load more results as needed from Hypothesis, but with a one second delay before each subsequent query to avoid rapid repeated hits to Hypothesis if something easily done and seemingly innocuous like list( is done.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for python-hypothesis, version 0.4.2
Filename, size File type Python version Upload date Hashes
Filename, size python_hypothesis-0.4.2-py2-none-any.whl (9.0 kB) File type Wheel Python version py2 Upload date Hashes View
Filename, size python_hypothesis-0.4.2-py3-none-any.whl (9.1 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size python-hypothesis-0.4.2.tar.gz (10.3 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page