engine

This module contains the Emtellipro class and related classes for interacting with the engine.

Module Contents

Classes

Functions

Data

FEATURES CATEGORIES

API

emtellipro.engine.FEATURES

emtellipro.engine.FEATURES

These are the complete list of available features.

emtellipro.engine.CATEGORIES

emtellipro.engine.CATEGORIES

This is a mapping from category names to subcategories that are supported by this version of the emtelliPro SDK.

emtellipro.engine.ResultFutureStatus

class emtellipro.engine.ResultFutureStatus(status, prev_progress)

Bases: object

This class is returned by ResultFuture.done, and contains information about the processing status of the job.

Note: this class implements __bool__ with the same semantics as .done

Attributes:

• done: whether the job has completed processing (can either be a successful, failed, or cancelled job; both are considered “done”)
• success: whether the job has completed successfully; note if the job is not done, this will be false
• progress: a number in [0, 1] representing the percentage of completed documents
• state: The value of the “state” field in the status returned by emtelliPro.

ResultFutureStatus.__bool__

__bool__()

emtellipro.engine.Result

class emtellipro.engine.Result

Bases: object

This is the result from the engine containing parsed annotated docs, and other information about this processing run.

It is possible to iterate over this object, which will have the effect of iterating over the annotated docs.

Attributes:

• task_id: The task ID for the task that produced this result.
• engine_version: The engine version returned by the engine.
• annotated_docs: A list of AnnotatedDocument instances.
• raw: The unparsed original text that was returned by the engine.
• json: The parsed JSON for the result class.

Initialization

__init__(task_id, engine_version, raw, annotated_docs)

Result.task_id

task_id: str

Result.engine_version

engine_version: str

Result.raw

raw: str

Result.annotated_docs

annotated_docs: typing.List[emtellipro.data.AnnotatedDocument]

Type: typing.List[AnnotatedDocument]

Result.json

property json: dict

Return type: dict

Result.fail

fail(
    task_id: str,
    engine_version: str,
    input_docs: collections.abc.Iterable[emtellipro.data.InputDocument],
    raw: typing.Optional[str] = None
)

Create a Result instance where all the annotated documents are failed.

Parameters:

Result.__iter__

__iter__()

emtellipro.engine.ResultFuture

class emtellipro.engine.ResultFuture(task_id, api, num_docs=None)

Bases: object

This class mimics asyncio.Future and concurrent.futures.Future in terms of some of the available methods and semantics, but you cannot await or yield from any of its methods.

ResultFuture instances will be created by the Emtellipro and should not be created directly.

Note: ResultFuture objects are pickle-able.

Attributes:

• task_id: The task ID as returned by the emtelliPro API. This can be stored and then used with Emtellipro.check_task() to recreate a ResultFuture instance.

Initialization

Parameters:

• task_id: a string representing the ID of the task submitted to the server.
• api: instance of _api.Api used for retrieving results and checking status.
• num_docs: the number of documents this result future is handling, if known.

ResultFuture.num_docs

property num_docs

The total number of documents submitted for processing.

ResultFuture.cancel

cancel()

Cancel the task being represented by this ResultFuture.

ResultFuture.cancelled

cancelled()

Check if the task is cancelled.

Returns:

The cancellation status of the task (a boolean).

ResultFuture.done

done(timeout=None) -> emtellipro.engine.ResultFutureStatus

Check if task is done (i.e. cancelled, successful, failed).

Parameters:

Returns:

The processing status, which can be used in an if statement since it will evaluate to True if the task is done.

Return type: ResultFutureStatus

ResultFuture.result

result() -> emtellipro.engine.Result

Retrieve the results of the task.

The response from emtelliPro is cached, so calling this multiple times will not lead to multiple calls to emtelliPro.

If you’d like the unparsed raw API response, use .raw_result() instead.

Returns:

The result of processing the task.

Raises:

exc.TaskFailedError: The task has a status of ‘failure’. exc.TaskNotFoundError: The task is not found on the server.

Return type: Result

ResultFuture.engine_version

property engine_version

The engine version as returned in the result. This can only be accessed after calling .result(); accessing this attribute before will result in an AttributeError.

ResultFuture.raw_result

raw_result(result_format=data.AnnotatedDocument.supported_result_format)

Return the raw text result from the API, unparsed. The text is cached, so multiple calls to this method will not result in multiple API calls.

If you’d like the parsed result, use .result() instead.

Raises:

exc.TaskFailedError: The task has a status of ‘failure’. exc.TaskNotFoundError: The task is not found on the server.

emtellipro.engine.Emtellipro

class emtellipro.engine.Emtellipro(server, auth: typing.Union[tuple[str, str], str], *, max_retries=DEFAULT_MAX_RETRIES, extra_headers: typing.Optional[collections.abc.Mapping] = None)

Bases: object

This is the main way of interacting with the API. It handles all the necessary details for submitting documents for processing and retrieving results.

Example:

input_docs = ...
client = Emtellipro(...)
for batch in emtellipro.utils.batch_documents(input_docs):
    result_future = client.submit(batch)
    while not result_future.done():
        pass
    print(result_future.result)

Attributes:

• server: The emtelliPro server URL.

Initialization

Parameters:

• server: The URL of the server to connect to. If you wish to use the default global server, you should pass Emtellipro.DEFAULT_SERVER here.
• auth: The authentication keys; this must be a tuple of (access key, shared secret) for HMAC based authentication, or a single string for API-key based authentication.

New in version 6.10.

Support for API key authentication.

• max_retries (optional): the number of times to retry failed API requests; there may be failures due to network issues, so this should be a positive integer.
• extra_headers: Any extra headers to include in all requests.

Emtellipro.DEFAULT_MAX_RETRIES

DEFAULT_MAX_RETRIES

Value: 5

Emtellipro.DEFAULT_SERVER

DEFAULT_SERVER

The default global server that can be passed as the argument to server.

Value: https://nlp.emtelligent.com

Emtellipro.submit

submit(
    documents: typing.Iterable[emtellipro.data.InputDocument],
    features: typing.Optional[typing.Iterable[str]] = None,
    document_type: str = 'plain'
) -> emtellipro.engine.ResultFuture

Submit documents for annotating.

Parameters:

Returns:

A ResultFuture object representing the current status of the annotation process.

This will not check that the submitted batch of documents is too big. You should use batch_documents to split up a large number of documents into smaller batches that do not go over the maximum submission limit.

Return type: ResultFuture

Emtellipro.check_task

check_task(task_id) -> emtellipro.engine.ResultFuture

Create a ResultFuture instance from a task_id.

Parameters:

Returns:

A new future object that can be used to monitor processing status and retrieve results.

Raises:

exc.TaskNotFoundError: Raised if the task ID wasn’t found on the server.

Return type: ResultFuture

Emtellipro.user

property user: emtellipro.data.User

The user information as known by the Emtellipro server.

Return type: User