clarin.sru.server.result

class clarin.sru.server.result.SRUAbstractResult(diagnostics: SRUDiagnosticList)[source]

Bases: object

Base class for SRU responses.

add_diagnostic(uri: str, details: str | None = None, message: str | None = None) → None[source]

Add a non surrogate diagnostic to the response.

Parameters:

  • uri – the diagnostic’s identifying URI

  • details – supplementary information available, often in a format specified by the diagnostic or None

  • message – human readable message to display to the end user or None

property has_extra_response_data: bool

Check, if extra response data should be serialized for this request. Default implementation is provided for convince and always returns False.

Returns:

bool – True if extra response data should be serialized

write_extra_response_data(writer: SRUXMLStreamWriter) → None[source]

Serialize extra response data for this request. A no-op default implementation is provided for convince.

Parameters:

writer – Writer to serialize extra response data

close() → None[source]

Release this result and free any associated resources.

This method must not throw any exceptions.

Calling the method close on a result object that is already closed is a no-op.

class clarin.sru.server.result.SRUExplainResult(diagnostics: SRUDiagnosticList)[source]

Bases: ABC, SRUAbstractResult

A result set of an explain operation. A database implementation may use it implement extensions to the SRU protocol, i.e. providing extraResponseData.

This class needs to be implemented for the target data source.

See also

SRU Explain Operation: http://www.loc.gov/standards/sru/explain/

class clarin.sru.server.result.SRUScanResultSet(diagnostics: SRUDiagnosticList)[source]

Bases: ABC, SRUAbstractResult

A result set of a scan operation. It is used to iterate over the term set and provides a method to serialize the terms.

A SRUScanResultSet object maintains a cursor pointing to its current term. Initially the cursor is positioned before the first term. The next method moves the cursor to the next term, and because it returns False when there are no more terms in the SRUScanResultSet object, it can be used in a while loop to iterate through the term set.

This class needs to be implemented for the target search engine.

See also

SRU Scan Operation: http://www.loc.gov/standards/sru/companionSpecs/scan.html

class WhereInList(value)[source]

Bases: str, Enum

A flag to indicate the position of the term within the complete term list.

FIRST = 'first'

The first term (first)

LAST = 'last'

The last term (last)

ONLY = 'only'

The only term (only)

INNER = 'inner'

Any other term (inner)

abstract next_term() → bool[source]

Moves the cursor forward one term from its current position. A result set cursor is initially positioned before the first record; the first call to the method next makes the first term the current term; the second call makes the second term the current term, and so on.

When a call to the next method returns False, the cursor is positioned after the last term.

Returns:

bool –

True if the new current term is valid;

False if there are no more terms

Raises:

SRUException – if an error occurred while fetching the next term

abstract get_value() → str[source]

Get the current term exactly as it appears in the index.

Returns:

str – current term

abstract get_number_of_records() → int[source]

Get the number of records for the current term which would be matched if the index in the request’s scanClause was searched with the term in the value field.

Returns:

int –

a non-negative number of records or -1, if the

number is unknown.

abstract get_display_term() → str | None[source]

Get the string for the current term to display to the end user in place of the term itself.

Returns:

str – display string or None

abstract get_WhereInList() → WhereInList | None[source]

Get the flag to indicate the position of the term within the complete term list.

Returns:

WhereInList – position within term list or None

has_extra_term_data() → bool[source]

Check, if extra term data should be serialized for the current term. A default implementation is provided for convince and always returns False.

Returns:

bool – True if the term has extra term data

Raises:

StopIteration – term set is already advanced past all past terms

See also

write_extra_term_data

abstract write_extra_term_data(writer: SRUXMLStreamWriter)[source]

Serialize extra term data for the current term. A no-op default implementation is provided for convince.

Parameters:

writer – Writer to serialize extra term data for current term

Raises:

StopIteration – term set already advanced past all terms

class clarin.sru.server.result.SRUSearchResultSet(diagnostics: SRUDiagnosticList)[source]

Bases: ABC, SRUAbstractResult

A result set of a searchRetrieve operation. It it used to iterate over the result set and provides a method to serialize the record in the requested format.

A SRUSearchResultSet object maintains a cursor pointing to its current record. Initially the cursor is positioned before the first record. The next method moves the cursor to the next record, and because it returns False when there are no more records in the SRUSearchResultSet object, it can be used in a while loop to iterate through the result set.

This class needs to be implemented for the target search engine.

See also

abstract get_total_record_count() → int[source]

The number of records matched by the query. If the query fails this must be 0. If the search engine cannot determine the total number of matched by a query, it must return -1.

Returns:

int –

the total number of results or 0 if the query

failed or -1 if the search engine cannot determine the total number of results

abstract get_record_count() → int[source]

The number of records matched by the query but at most as the number of records requested to be returned (maximumRecords parameter). If the query fails this must be 0.

Returns:

int – the number of results or 0 if the query failed

get_resultSet_id() → str | None[source]

The result set id of this result. The default implementation returns None.

Returns:

str –

the result set id or None if not applicable for

this result

get_resultSet_TTL() → int[source]

The result set time to live. In SRU 2.0 it will be serialized as <resultSetTTL> element; in SRU 1.2 as <resultSetIdleTime> element.The default implementation returns -1.

Returns:

int –

the result set time to live or -1 if not

applicable for this result

get_result_count_precision() → SRUResultCountPrecision | None[source]

(SRU 2.0) Indicate the accuracy of the result count reported by total number of records that matched the query. Default implementation returns None.

Returns:

Optional[SRUResultCountPrecision] –

the result count

precision or None if not applicable for this result

See also

SRUResultCountPrecision

abstract get_record_schema_identifier() → str[source]

The record schema identifier in which the records are returned (recordSchema parameter).

Returns:

str – the record schema identifier

abstract next_record() → bool[source]

Moves the cursor forward one record from its current position. A SRUSearchResultSet cursor is initially positioned before the first record; the first call to the method next makes the first record the current record; the second call makes the second record the current record, and so on.

When a call to the next method returns False, the cursor is positioned after the last record.

Returns:

bool –

True if the new current record is valid;

False if there are no more records

Raises:

SRUException – if an error occurred while fetching the next record

abstract get_record_identifier() → str | None[source]

An identifier for the current record by which it can unambiguously be retrieved in a subsequent operation.

Returns:

str –

identifier for the record or None of none is

available

Raises:

StopIteration – result set is past all records

get_surrogate_diagnostic() → SRUDiagnostic | None[source]

Get surrogate diagnostic for current record. If this method returns a diagnostic, the write_record method will not be called. The default implementation returns ``None`.

Returns:

Optional[SRUDiagnostic] –

a surrogate diagnostic or

None

abstract write_record(writer: SRUXMLStreamWriter) → None[source]

Serialize the current record in the requested format.

Parameters:

writer – Writer to serialize current record

Raises:

StopIteration – result set is past all records

property has_extra_record_data: bool

Check, if extra record data should be serialized for the current record. The default implementation returns False.

Returns:

bool – True if the record has extra record data

Raises:

StopIteration – result set is past all records

See also

write_extra_record_data

write_extra_record_data(writer: SRUXMLStreamWriter) → None[source]

Serialize extra record data for the current record. A no-op default implementation is provided for convince.

Parameters:

writer – Writer to serialize extra record data for current record

Raises:

StopIteration – result set past already advanced past all records