delphin.web.client

DELPH-IN Web API Client

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). This dependency is satisfied if you install PyDelphin with the [web] extra (see Requirements, Installation, and Testing).

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

>>> from delphin.web import client
>>> url = 'http://erg.delph-in.net/rest/0.9/'
>>> client.parse('Abrams slept.', server=url)
Response({'input': 'Abrams slept.', 'readings': 1, 'results': [{'result-id': 0}], 'tcpu': 7, 'pedges': 17})
>>> client.parse_from_iterable(['Abrams slept.', 'It rained.'], server=url)
<generator object parse_from_iterable at 0x7f546661c258>
>>> client.generate('[ LTOP: h0 INDEX: e2 [ e SF: prop TENSE: past MOOD: indicative PROG: - PERF: - ] RELS: < [ proper_q<0:6> LBL: h4 ARG0: x3 [ x PERS: 3 NUM: sg IND: + ] RSTR: h5 BODY: h6 ]  [ named<0:6> LBL: h7 CARG: "Abrams" ARG0: x3 ]  [ _sleep_v_1<7:13> LBL: h1 ARG0: e2 ARG1: x3 ] > HCONS: < h0 qeq h1 h5 qeq h7 > ICONS: < > ]')
Response({'input': '[ LTOP: h0 INDEX: e2 [ e SF: prop TENSE: past MOOD: indicative PROG: - PERF: - ] RELS: < [ proper_q<0:6> LBL: h4 ARG0: x3 [ x PERS: 3 NUM: sg IND: + ] RSTR: h5 BODY: h6 ]  [ named<0:6> LBL: h7 CARG: "Abrams" ARG0: x3 ]  [ _sleep_v_1<7:13> LBL: h1 ARG0: e2 ARG1: x3 ] > HCONS: < h0 qeq h1 h5 qeq h7 > ICONS: < > ]', 'readings': 1, 'results': [{'result-id': 0, 'surface': 'Abrams slept.'}], 'tcpu': 8, 'pedges': 59})

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

These functions instantiate and use subclasses of Client, which manages the connections to a server. They can also be used directly:

>>> parser = web.Parser(server=url)
>>> parser.interact('Dogs chase cats.')
Response({'input': 'Dogs chase cats.', ...
>>> generator = web.Generator(server=url)
>>> generator.interact('[ LTOP: h0 INDEX: e2 ...')
Response({'input': '[ LTOP: h0 INDEX: e2 ...', ...)

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

>>> r = parser.interact('Dogs chase cats', params={'mrs':'json'})
>>> r.result(0)
Result({'result-id': 0, 'score': 0.5938, ...
>>> r.result(0)['mrs']
{'variables': {'h1': {'type': 'h'}, 'x6': ...
>>> r.result(0).mrs()
<MRS object (udef_q dog_n_1 chase_v_1 udef_q cat_n_1) at 140000394933248>

If PyDelphin does not support deserialization for a format provided by the server (e.g. LaTeX output), the Result object raises a TypeError.

Client Functions

delphin.web.client.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 (LOGON’s ERG server is used by default)

  • params (dict) – a dictionary of request parameters

  • headers (dict) – a dictionary of additional request headers

Returns:

A Response containing the results, if the request was successful.

Raises:

requests.HTTPError – if the status code was not 200

delphin.web.client.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 (LOGON’s ERG server is used by default)

  • params (dict) – a dictionary of request parameters

  • headers (dict) – a dictionary of additional request headers

Yields:

Response objects for each successful response.

Raises:

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

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

Request realizations for input.

Parameters:
  • input (str) – SimpleMRS to be realized

  • server (str) – the url for the server (LOGON’s ERG server is used by default)

  • params (dict) – a dictionary of request parameters

  • headers (dict) – a dictionary of additional request headers

Returns:

A Response containing the results, if the request was successful.

Raises:

requests.HTTPError – if the status code was not 200

delphin.web.client.generate_from_iterable(inputs, server='http://erg.delph-in.net/rest/0.9/', params=None, headers=None)[source]

Request realizations for all inputs.

Parameters:
  • inputs (iterable) – SimpleMRS strings to realize

  • server (str) – the url for the server (LOGON’s ERG server is used by default)

  • params (dict) – a dictionary of request parameters

  • headers (dict) – a dictionary of additional request headers

Yields:

Response objects for each successful response.

Raises:

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

Client Classes

class delphin.web.client.Client(server)[source]

Bases: Processor

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

Note

This class is not meant to be used directly. Use a subclass instead.

interact(datum, params=None, headers=None)[source]

Request the server to process datum return the response.

Parameters:
  • datum (str) – datum to be processed

  • params (dict) – a dictionary of request parameters

  • headers (dict) – a dictionary of additional request headers

Returns:

A Response 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 server and return the response with context.

The keys parameter can be used to track item identifiers through a Web API interaction. If the task member is set on the Client instance (or one of its subclasses), it is kept in the response as well.

Parameters:
  • datum (str) – the input sentence or MRS

  • keys (dict) – a mapping of item identifier names and values

  • params (dict) – a dictionary of request parameters

  • headers (dict) – a dictionary of additional request headers

Returns:

Response

class delphin.web.client.Parser(server)[source]

Bases: Client

A class for managing parse requests to a Web API server.

class delphin.web.client.Generator(server)[source]

Bases: Client

A class for managing generate requests to a Web API server.