delphin.interfaces.ace

See also

See Using ACE from PyDelphin for a more user-friendly introduction.

An interface for the ACE processor.

This module provides classes and functions for managing interactive communication with an open ACE process.

Note

ACE is required for the functionality in this module, but it is not included with PyDelphin. Pre-compiled binaries are available for Linux and MacOS: http://sweaglesw.org/linguistics/ace/

For installation instructions, see: http://moin.delph-in.net/AceInstall

The AceParser, AceTransferer, and AceGenerator classes are used for parsing, transferring, and generating with ACE. All are subclasses of AceProcess, which connects to ACE in the background, sends it data via its stdin, and receives responses via its stdout. Responses from ACE are interpreted so the data is more accessible in Python.

Warning

Instantiating AceParser, AceTransferer, or AceGenerator opens ACE in a subprocess, so take care to close the process (AceProcess.close()) when finished or, alternatively, instantiate the class in a context manager.

Interpreted responses are stored in a dictionary-like ParseResponse object. When queried as a dictionary, these objects return the raw response strings. When queried via its methods, the PyDelphin models of the data are returned. The response objects may contain a number of ParseResult objects. These objects similarly provide raw-string access via dictionary keys and PyDelphin-model access via methods. Here is an example of parsing a sentence with AceParser:

>>> with AceParser('erg-1214-x86-64-0.9.24.dat') as parser:
...     response = parser.interact('Cats sleep.')
...     print(response.result(0)['mrs'])
...     print(response.result(0).mrs())
...
[ LTOP: h0 INDEX: e2 [ e SF: prop TENSE: pres MOOD: indicative PROG: - PERF: - ] RELS: < [ udef_q<0:4> LBL: h4 ARG0: x3 [ x PERS: 3 NUM: pl IND: + ] RSTR: h5 BODY: h6 ]  [ _cat_n_1<0:4> LBL: h7 ARG0: x3 ]  [ _sleep_v_1<5:11> LBL: h1 ARG0: e2 ARG1: x3 ] > HCONS: < h0 qeq h1 h5 qeq h7 > ]
<Xmrs object (udef cat sleep) at 139880862399696>

Functions exist for non-interactive communication with ACE: parse() and parse_from_iterable() open and close an AceParser instance; transfer() and transfer_from_iterable() open and close an AceTransferer instance; and generate() and generate_from_iterable() open and close an AceGenerator instance. Note that these functions open a new ACE subprocess every time they are called, so if you have many items to process, it is more efficient to use parse_from_iterable(), transfer_from_iterable(), or generate_from_iterable() than the single-item versions, or to interact with the AceProcess subclass instances directly.

Basic Usage

The following module funtions are the simplest way to interact with ACE, although for larger or more interactive jobs it is suggested to use an AceProcess subclass instance.

delphin.interfaces.ace.compile(cfg_path, out_path, executable=None, env=None, log=None)

Use ACE to compile a grammar.

Parameters:

• cfg_path (str) – the path to the ACE config file
• out_path (str) – the path where the compiled grammar will be written
• executable (str, optional) – the path to the ACE binary; if None, the ace command will be used
• env (dict, optional) – environment variables to pass to the ACE subprocess
• log (file, optional) – if given, the file, opened for writing, or stream to write ACE’s stdout and stderr compile messages

delphin.interfaces.ace.parse(grm, datum, **kwargs)

Parse sentence datum with ACE using grammar grm.

Parameters:

• grm (str) – path to a compiled grammar image
• datum (str) – the sentence to parse
• **kwargs – additional keyword arguments to pass to the AceParser

Returns:

ParseResponse

Example

>>> response = ace.parse('erg.dat', 'Dogs bark.')
NOTE: parsed 1 / 1 sentences, avg 797k, time 0.00707s

delphin.interfaces.ace.parse_from_iterable(grm, data, **kwargs)

Parse each sentence in data with ACE using grammar grm.

Parameters:

• grm (str) – path to a compiled grammar image
• data (iterable) – the sentences to parse
• **kwargs – additional keyword arguments to pass to the AceParser

Yields:

ParseResponse

Example

>>> sentences = ['Dogs bark.', 'It rained']
>>> responses = list(ace.parse_from_iterable('erg.dat', sentences))
NOTE: parsed 2 / 2 sentences, avg 723k, time 0.01026s

delphin.interfaces.ace.transfer(grm, datum, **kwargs)

Transfer from the MRS datum with ACE using grammar grm.

Parameters:

• grm (str) – path to a compiled grammar image
• datum – source MRS as a SimpleMRS string
• **kwargs – additional keyword arguments to pass to the AceTransferer

Returns:

ParseResponse

delphin.interfaces.ace.transfer_from_iterable(grm, data, **kwargs)

Transfer from each MRS in data with ACE using grammar grm.

Parameters:

• grm (str) – path to a compiled grammar image
• data (iterable) – source MRSs as SimpleMRS strings
• **kwargs – additional keyword arguments to pass to the AceTransferer

Yields:

ParseResponse

delphin.interfaces.ace.generate(grm, datum, **kwargs)

Generate from the MRS datum with ACE using grm.

Parameters:

• grm (str) – path to a compiled grammar image
• datum – the SimpleMRS string to generate from
• **kwargs – additional keyword arguments to pass to the AceGenerator

Returns:

ParseResponse

delphin.interfaces.ace.generate_from_iterable(grm, data, **kwargs)

Generate from each MRS in data with ACE using grammar grm.

Parameters:

• grm (str) – path to a compiled grammar image
• data (iterable) – MRSs as SimpleMRS strings
• **kwargs – additional keyword arguments to pass to the AceGenerator

Yields:

ParseResponse

Classes for Managing ACE Processes

The functions described in Basic Usage are useful for small jobs as they handle the input and then close the ACE process, but for more complicated or interactive jobs, directly interacting with an instance of an AceProcess sublass is recommended or required (e.g., in the case of [incr tsdb()] testsuite processing). The AceProcess class is where most methods are defined, but in practice the AceParser, AceTransferer, or AceGenerator subclasses are directly used.

class delphin.interfaces.ace.AceProcess(grm, cmdargs=None, executable=None, env=None, tsdbinfo=True, **kwargs)

Bases: delphin.interfaces.base.Processor

The base class for interfacing ACE.

This manages most subprocess communication with ACE, but does not interpret the response returned via ACE’s stdout. Subclasses override the receive() method to interpret the task-specific response formats.

Parameters:

• grm (str) – path to a compiled grammar image
• cmdargs (list, optional) – a list of command-line arguments for ACE; note that arguments and their values should be separate entries, e.g. [‘-n’, ‘5’]
• executable (str, optional) – the path to the ACE binary; if None, ACE is assumed to be callable via ace
• env (dict) – environment variables to pass to the ACE subprocess
• tsdbinfo (bool) – if True and ACE’s version is compatible, all information ACE reports for [incr tsdb()] processing is gathered and returned in the response

ace_version

The version of the specified ACE binary.

close()

Close the ACE process and return the process’s exit code.

interact(datum)

Send datum to ACE and return the response.

This is the recommended method for sending and receiving data to/from an ACE process as it reduces the chances of over-filling or reading past the end of the buffer. It also performs a simple validation of the input to help ensure that one complete item is processed at a time.

If input item identifiers need to be tracked throughout processing, see process_item().

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

process_item(datum, keys=None)

Send datum to ACE and return the response with context.

The keys parameter can be used to track item identifiers through an ACE interaction. If the task member is set on the AceProcess instance (or one of its subclasses), it is kept in the response as well. :param datum: the input sentence or MRS :type datum: str :param keys: a mapping of item identifier names and values :type keys: dict

Returns:ParseResponse

receive()

Return the stdout response from ACE.

Warning

Reading beyond the last line of stdout from ACE can cause the process to hang while it waits for the next line. Use the interact() method for most data-processing tasks with ACE.

run_info

Contextual information about the the running process.

send(datum)

Send datum (e.g. a sentence or MRS) to ACE.

Warning

Sending data without reading (e.g., via receive()) can fill the buffer and cause data to be lost. Use the interact() method for most data-processing tasks with ACE.

task = None

The name of the task performed by the processor (‘parse’, ‘transfer’, or ‘generate’). This is useful when a function, such as delphin.itsdb.TestSuite.process(), accepts any AceProcess instance.

class delphin.interfaces.ace.AceParser(grm, cmdargs=None, executable=None, env=None, tsdbinfo=True, **kwargs)

Bases: delphin.interfaces.ace.AceProcess

A class for managing parse requests with ACE.

See AceProcess for initialization parameters.

class delphin.interfaces.ace.AceTransferer(grm, cmdargs=None, executable=None, env=None, tsdbinfo=False, **kwargs)

Bases: delphin.interfaces.ace.AceProcess

A class for managing transfer requests with ACE.

Note that currently the tsdbinfo parameter must be set to False as ACE is not yet able to provide detailed information for transfer results.

See AceProcess for initialization parameters.

class delphin.interfaces.ace.AceGenerator(grm, cmdargs=None, executable=None, env=None, tsdbinfo=True, **kwargs)

Bases: delphin.interfaces.ace.AceProcess

A class for managing realization requests with ACE.

See AceProcess for initialization parameters.