xmu.api

Defines tools to work with the EMu API

class xmu.api.EMuAPI(url: str = None, username: str = None, password: str = None, autopage: bool = None, config_path: str | Path = 'emurestapi.toml', parser: EMuAPIParser = None)[source]

Bases: object

Connects to and queries the EMu API

Parameters:

url (str, optional) – the url for the EMu API, including tenant
username (str, optional) – an EMu username. If omitted, defaults to the current OS username.
password (str, optional) – the password for the given username, If omitted, the user will be prompted for the password when the class is initiated.
autopage (bool = True) – whether to automatically page through results if the total number of results exceeds the limit of a given request
config_path (str | Path) – path to a TOML config file used to set url, username, password, and autopage
parser (EMuAPIParser, optional) – the parser object used to parse individual records. The default EMuAPIParser class returns a close approximation of the format used by EMuRecord. If None, records will be returned as formatted by the API.

module

the backend name of an EMu module, for example, ecatalogue or eparties

Type:: str

use_emu_syntax

specifies whether to use the EMu client syntax when parsing search terms. Clients searches escape control characters using a backslash.

Type:: bool

property parser: The parser object used to parse records returned by the API

property session: The session object to use for API queries

get_token(refresh=False, **kwargs)[source]

Retrieves a token from the server to authorize requests

Parameters:: kwargs – username and password if no config file is found
Returns:: the authorization token need to make API requests
Return type:: str

get(*args, select=None, **kwargs)[source]

Performs a GET operation with the proper authorization header

Most requests should use either retrieve or search instead of calling this method directly.

Parameters:

args – Any arg accepted by request.get()
select (list[str] | dict[dict], optional) –
A container with fields to include in the returned records. Fields from other modules can be included using a dict formatted as follows: {

”EMuField”: None, “EMuFieldRef”: {

”EMuFieldInAnotherModule”: None,

}

}
kwargs – Any kwarg accepted by request.get(). By default, the headers kwarg includes {“Prefer”: “representation=none”, “X-HTTP-Method-Override” = “GET”, “Content-Type”: “application/x-www-form-urlencoded”}. The latter two keys are used to implement the HTTP method override recommended by Axiell.

Returns:

the response returned for the request

Return type:

EMuAPIResponse

retrieve(module: str, irn: str | int, select: list[str] = None) → None[source]

Retrieves a single record from an irn

Parameters:

module (str) – the module to query
irn (str | int) – the IRN for the EMu record to retrieve
select (list[str], optional) – the list of EMu fields to return. If omitted, returns the record id.

Returns:

the query response

Return type:

EMuAPIResponse

search(module: str, *, select: list[str] = None, sort_: dict = None, filter_: dict = None, limit: int = 10, cursor_type: str = 'server')[source]

Searches EMu based on the provided filter

Parameters:

module (str) – the module to query
select (list[str], optional) – the list of EMu fields to return. If omitted, returns the record id.
sort (dict, optional) – criteria by which to order the results. Each key must have the value “asc” or “desc”.
filter (dict, optional) – search filter. Each key-value pair consists of a field name and value. Complex searches can be made using the helper functions included in this module (contains, phrase, etc.) Lists are expanded as OR searches. Values that have not been converted to the API syntax will be parsed using a set of rules modeled on EMu client searches.
limit (int, default=10) – the number of records to return per page
cursor_type (str, default="server") – whether the cursor is stored locally or on the server

Yields:

EMuAPIResponse – the query response

class xmu.api.EMuAPIResponse(response: Response, api: EMuAPI, select: list[str] | dict[dict] = None)[source]

Bases: object

Wraps a response from the EMu API response

property module: The EMu module queried to create the response

property params: The query parameters used to make the request

json()[source]: Parse JSON from response

records()[source]

Gets a mapping of all records in the result set by IRN

Returns:: dict that maps irns to records
Return type:: dict

first()[source]

Gets the first record from the result set

Returns:: the first record. If a rec_class is specified, the record will use that class.
Return type:: dict

next_page()[source]

Gets the next pages of results in the result set

Returns:: the result from the next page
Return type:: EMuAPIResponse

defer_attachments(rec)[source]

Defers attachments in record

Called automatically if resolve_attachments is True.

Parameters:: rec (dict) – a record returned by the EMu API
Returns:: record with attachments converted to DeferredAttachments
Return type:: dict

class xmu.api.EMuAPIParser[source]

Bases: object

Parses responses from the EMu API

parse(module: str, rec: dict, select: list | dict[dict] = None)[source]

Parses a record returned by the EMu API

Only attachments mapped in the original select parameter are resolved.

Parameters:

rec (dict) – a record retrieved from the EMu API
module (str) – the backend name of the EMu module
select (list | dict) – the fields to return

Returns:

the record with all attachments resolved

Return type:

dict

class xmu.api.DeferredAttachment(val, api, select=None)[source]

Bases: object

An attached record defined by a module and IRN

The record itself is loaded when (1) a key is accessed or (2) it is loaded manually using the resolve() method. New instances should be created using the attach() function to allow caching.

Parameters:

val (str) – the EMu attachment string
api (EMuAPI) – the instance of the EMu API that created the parent record
select (list | dict) – the fields to retrieve. If omitted, all fields are returned.

verbatim

the EMu attachment string

Type:: str

module

the backend name of the EMu module

Type:: str

irn

the IRN of the attached record

Type:: int

select

the fields to retrieve

Type:: list | dict

property data: The EMu record for the given IRN and select statement

resolve()[source]

Resolves all deferred records with the same IRN and select statement

Returns:: attachment with data attribute populated
Return type:: DeferredAttachment

xmu.api.attach(val, api, select=None)[source]

Creates a DeferredAttachment for the given value

This is the preferred way to create a DeferredAttachment.

Parameters:

val (str) – the EMu attachment string
api (EMuAPI) – the instance of the EMu API that created the parent record
select (str) – a JSON-encoded string of the fields to retrieve. If omitted, all fields are returned.

Return type:

DeferredAttachment

xmu.api.and_(conds: list[dict]) → dict[source]

Combines a list of conditions with AND

Parameters:: conds (list[dict]) – list of conditions
Returns:: {“AND”: conds}
Return type:: dict

xmu.api.or_(conds: list[dict]) → dict[source]

Combines a list of conditions with OR

Parameters:: conds (list[dict]) – list of conditions
Returns:: {“OR”: conds}
Return type:: dict

xmu.api.not_(conds: dict) → dict[source]

Negates a condition

Parameters:: conds (list[dict] | dict) – list of conditions
Returns:: {“NOT”: conds}
Return type:: dict

xmu.api.contains(val: str | list[str], col: str = None) → dict[source]

Builds a condition to match fields containing a value

Equivalent to the basic, text-only search in the EMu client.

Paramters

valstr | list[str]: the text to search for or a list of such strings
colstr: the name of the column. Typically ommitted.

returns:: an EMu API contains condition
rtype:: dict

xmu.api.range_(gt: str | int | float = None, lt: str | int | float = None, gte: str | int | float = None, lte: str | int | float = None, mode: str = None, col: str = None) → dict[source]

Builds a condition to match a range of values

At least one of gt, lt, gte, and lte must be provided. Only one of gt and gte can be provided, and only one of lt and lte can be provided.

Parameters:

gt (str | float | int) – the lower bound of the search, not inclusive
lt (str | float | int) – the upper bound of the search, not inclusive
gte (str | float | int) – the lower bound of the search, inclusive
lte (str | float | int) – the upper bound of the search, inclusive
mode (str) – one of date, time, latitude, or longitude. If omitted, will try to guess based on the column or value.
col (str) – the name of the column. Typically ommitted.

Returns:

an EMu API range condition

Return type:

dict

xmu.api.gt(val: str | int | float, mode: str = None, col: str = None)[source]

Builds a condition to match values greater than a given value

This is a helper function based on range_().

Paramters

val: str | float | int: the lower bound of the search, not inclusive
modestr: one of date, time, latitude, or longitude. If omitted, will try to guess based on the column or value.
colstr: the name of the column. Typically ommitted.

returns:: an EMu API range condition
rtype:: dict

xmu.api.gte(val: str | int | float, mode: str = None, col: str = None)[source]

Builds a condition to match values greater than or equal to a given value

This is a helper function based on range_().

Paramters

val: str | float | int: the lower bound of the search, inclusive
modestr: one of date, time, latitude, or longitude. If omitted, will try to guess based on the column or value.
colstr: the name of the column. Typically ommitted.

returns:: an EMu API range condition
rtype:: dict

xmu.api.lt(val: str | int | float, mode: str = None, col: str = None)[source]

Builds a condition to match values less than a given value

This is a helper function based on range_().

Paramters

val: str | float | int: the upper bound of the search, not inclusive
modestr: one of date, time, latitude, or longitude. If omitted, will try to guess based on the column or value.
colstr: the name of the column. Typically ommitted.

returns:: an EMu API range condition
rtype:: dict

xmu.api.lte(val: str | int | float, mode: str = None, col: str = None)[source]

Builds a condition to match values less than or equal to a given value

This is a helper function based on range_().

Paramters

val: str | float | int: the upper bound of the search, inclusive
modestr: one of date, time, latitude, or longitude. If omitted, will try to guess based on the column or value.
colstr: the name of the column. Typically ommitted.

returns:: an EMu API range condition
rtype:: dict

xmu.api.exact(val: str | float | int, col: str = None, mode: str = None) → dict[source]

Builds a condition to match the complete contents of a column exactly

Equivalent to ^"hello world"$ in the EMu client. Case insensitive.

Paramters

valstr | float | int | list[str] | list[float] | list[int]: the value or list of values to match
modestr: one of date, time, latitude, or longitude. If omitted, will try to guess based on the column or value.

returns:: an EMu API exact condition
rtype:: dict

xmu.api.exists(val: bool, col: str = None) → dict[source]

Builds a condition to test whether a field is populated

Equivalent to * + in the EMu client if True. Equivalent to !* or !+ if False or None.

Paramters

valbool: whether the field is populated. True returns records where the specified field is populated, False returns records where it is empty.

returns:: an EMu API exists condition
rtype:: dict

xmu.api.phonetic(val: str | list[str], col: str = None) → dict[source]

Builds a condition to perform a phonetic search

Equivalent to @smythe in the EMu client.

Paramters

valstr | list[str]: the text to search for or a list of such strings

returns:: an EMu API phonetic condition
rtype:: dict

xmu.api.phrase(val: str | list[str], col: str = None) → dict[source]

Builds a condition to search for a phrase

Equvalent to "the black cat”” in the EMu client.

Paramters

valstr | list[str]: a multiword phrase or a list of such phrases

returns:: an EMu API phrase condition
rtype:: dict

xmu.api.proximity(val: str | list[str], col: str = None, distance: int = 3) → dict[source]

Builds a condition to search for words within a certain distance of each other

Equivalent to '(the "black cat") <= 5 words' in the EMu client. The client supports more complex operations (for example, searching in order) that do not appear to be supported by the API.

Paramters

valstr | list[str]: a string of two or more words or a list of such strings
distanceint: the maximum distance between words

returns:: an EMu API phrase condition
rtype:: dict

xmu.api.regex(val: str | list[str], col: str = None) → dict[source]

Builds a condition to perform a regular expression search

Paramters

valstr | list[str]: the pattern to search for

returns:: an EMu API regex condition
rtype:: dict

xmu.api.stemmed(val: str | list[str], col: str = None) → dict[source]

Builds a condition to search for words matching the same root

Equivalent to ~locate in the EMu client

Paramters

valstr | list[str]: the root word to search for. For example, elect would match election, elected, electioneering, elects but would not match electricity

returns:: an EMu API stemmed condition
rtype:: dict

xmu.api.is_not_null(col: str = None) → dict[source]

Builds a condition that matches a non-empty field in the EMu API

Alias for exists(True).

Returns:: an EMu API exists=True condition
Return type:: dict

xmu.api.is_null(col: str = None) → dict[source]

Builds a condition that matches an empty field in the EMu API

Returns:: an EMu API exists=False condition
Return type:: dict

xmu.api.order(val: str = 'asc', col: str = None) → dict[source]

Builds a condition to sort in the given direction

Paramters

valstr: sort direction. Must be either “asc” or “desc”.

returns:: an EMu API order condition
rtype:: dict

xmu.api.emu_escape(val: str) → str[source]

Escapes a string according to EMu escape syntax

For example, the regular expression ^Hello world$ will be escaped as ^Hello world$.

Paramters

valstr: the text to escape

returns:: the escaped text
rtype:: str

xmu.api.emu_unescape(val: str) → str[source]

Unescapes a string that uses the EMu escape syntax

For example, the regular expression ^Hello world$ will be escaped as ^Hello world$.

Paramters

valstr: the text to unescape

returns:: the unescaped text
rtype:: str