delphin.interfaces.rest

Client access to the HTTP (“RESTful”) API for DELPH-IN data.

This module provides classes and functions for making requests to servers that implement the DELPH-IN web API described here:

Note

Requires requests (https://pypi.python.org/pypi/requests)

Basic access is available via the parse() and parse_from_iterable() functions:

>>> from delphin.interfaces import rest
>>> url = 'http://erg.delph-in.net/rest/0.9/'
>>> rest.parse('Abrams slept.', server=url)
ParseResponse({'input': 'Abrams slept.', 'tcpu': 0.05, ...
>>> rest.parse_from_iterable(['Abrams slept.', 'It rained.'], server=url)
<generator object parse_from_iterable at 0x7f546661c258>

If the server parameter is not provided to parse(), the default ERG server (as used above) is used by default. Request parameters (described at http://moin.delph-in.net/ErgApi) can be provided via the params argument.

These functions both instantiate and use the DelphinRestClient class, which manages the connections to a server. It can also be used directly:

>>> client = rest.DelphinRestClient(server=url)
>>> client.parse('Dogs chase cats.')
ParseResponse({'input': 'Dogs chase cats.', ...

The server responds with JSON data, which PyDelphin parses to a dictionary. The responses from DelphinRestClient.parse() are then wrapped in ParseResponse objects, which provide two methods for inspecting the results. The ParseResponse.result() method takes a parameter i and returns the ith result (0-indexed), and the ParseResponse.results() method returns the list of all results. The benefit of using these methods is that they wrap the result dictionary in a ParseResult object, which provides methods for automatically deserializing derivations, EDS, MRS, or DMRS data. For example:

>>> r = client.parse('Dogs chase cats', params={'mrs':'json'})
>>> r.result(0)
ParseResult({'result-id': 0, 'score': 0.5938, ...
>>> r.result(0)['mrs']
{'variables': {'h1': {'type': 'h'}, 'x6': ...
>>> r.result(0).mrs()
<Xmrs object (udef dog chase udef cat) at 140000394933248>

If PyDelphin does not support deserialization for a format provided by the server (e.g. LaTeX output), the original string would be returned by these methods (i.e. the same as via dict-access).

Basic Usage

delphin.interfaces.rest.parse(input, server='http://erg.delph-in.net/rest/0.9/', params=None, headers=None)[source]

Request a parse of input on server and return the response.

Parameters:
  • input (str) – sentence to be parsed
  • server (str) – the url for the server (the default LOGON server is used by default)
  • params (dict) – a dictionary of request parameters
  • headers (dict) – a dictionary of additional request headers
Returns:

A ParseResponse containing the results, if the request was successful.
Raises:

requests.HTTPError – if the status code was not 200
delphin.interfaces.rest.parse_from_iterable(inputs, server='http://erg.delph-in.net/rest/0.9/', params=None, headers=None)[source]

Request parses for all inputs.

Parameters:
  • inputs (iterable) – sentences to parse
  • server (str) – the url for the server (the default LOGON server is used by default)
  • params (dict) – a dictionary of request parameters
  • headers (dict) – a dictionary of additional request headers
Yields:

ParseResponse objects for each successful response.
Raises:

requests.HTTPError – for the first response with a status code that is not 200

Client Class

class delphin.interfaces.rest.DelphinRestClient(server='http://erg.delph-in.net/rest/0.9/')[source]

Bases: delphin.interfaces.base.Processor

A class for managing requests to a DELPH-IN web API server.

parse(sentence, params=None, headers=None)[source]

Request a parse of sentence and return the response.

Parameters:
  • sentence (str) – sentence to be parsed
  • params (dict) – a dictionary of request parameters
  • headers (dict) – a dictionary of additional request headers
Returns:

A ParseResponse containing the results, if the request was successful.
Raises:

requests.HTTPError – if the status code was not 200
process_item(datum, keys=None, params=None, headers=None)[source]

Send datum to the processor and return the result.

This method is a generic wrapper around a processor-specific processing method that keeps track of additional item and processor information. Specifically, if keys is provided, it is copied into the keys key of the response object, and if the processor object’s task member is non-None, it is copied into the task key of the response. These help with keeping track of items when many are processed at once, and to help downstream functions identify what the process did.

Parameters:
  • datum – the item content to process
  • keys – a mapping of item identifiers which will be copied into the response