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:
- 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:
- 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:
- 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:
- 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:
- 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.