Aleph lowlevel API

Aleph X-Service wrapper.

This module allows you to query Aleph’s X-Services module (Aleph server is defined by aleph.settings.ALEPH_URL in settings.py).

There are two levels of abstraction.

Lowlevel

You can use this functions to access Aleph:

searchInAleph(base, phrase, considerSimilar, field)
downloadRecords(search_result, [from_doc])
getDocumentIDs(aleph_search_result, [number_of_docs])
downloadMARCXML(doc_id, library)
downloadMARCOAI(doc_id, base)

Workflow

Aleph works in strange way, that he won’t allow you to access desired information directly.

You have to create search request by calling searchInAleph() first, which will return dictionary with few important informations about session.

This dictionary can be later used as parameter to getDocumentIDs() function, which will give you list of DocumentID named tuples.

Poznámka

namedtuple() is used, because to access your document, you don’t need just document ID number, but also library ID string.

Depending on your system, there may be just only one accessible library, or multiple ones, and then you will be glad, that you get both of this informations together.

DocumentID can be used as parameter to downloadMARCXML().

Lets look at some code:

ids = getDocumentIDs(searchInAleph("nkc", "test", False, "wrd"))
for id_num, library in ids:
    XML = downloadMARCXML(id_num, library)

    # processDocument(XML)

High-level

XML wrappers

This wrappers returns full XML records from Aleph:

ID wrappers

There are wrappers, which returns ID’s of matching document in Aleph:

You can theh download them using downloadMARCXML() or downloadMARCOAI().

Count wrappers

Count wrappers returns just the number of records with given parameters are there in aleph.

Poznámka

Counting functions are by one request faster than just counting results from standard getters. It is preferred to use them to reduce load to Aleph.

Other noteworthy properties

List of valid bases can be obtained by calling getListOfBases(), which returns list of strings.

There is also defined exception tree - see AlephException doc-string for details.

aleph.aleph.VALID_ALEPH_FIELDS = ['wrd', 'wtl', 'wau', 'wkw', 'txt', 'wpb', 'wpp', 'wyr', 'ssn', 'sbn', 'isn', 'ob', 'wpf', 'wpv', 'wln', 'wlo', 'wtp', 'sg', 'bar', 'cnb', 'icz', 'sys', 'wpk']
  • wrd - Všechny údaje [All fields]
  • wtl - Název [Title/name of the book]
  • wau - Autor (osoba, korporace) [Author (person, corporation)]
  • wkw - Předmět (klíčová slova) [Subject (keywords)]
  • txt - Slova z obsahu (table of cont.) [Words from table of content]
  • wpb - Nakladatel [Publisher]
  • wpp - Místo vydání [Place of publication]
  • wyr - Rok vydání [Year of publication]
  • ssn - ISSN
  • sbn - ISBN / ISMN
  • isn - ISBN / ISMN / ISSN
  • ob - Obsazení (hudební díla) [Cast (musical works)]
  • wpf - Periodicita [Periodicity]
  • wpv - Kód země vydání [Country code]
  • wln - Kód jazyka dokumentu [Language code]
  • wlo - Kód jazyka originálu [Lanugage code of original]
  • wtp - Druh dokumentu [Type of document]
  • sg - Signatura [Signature]
  • bar - Čárový kód [Barcode]
  • cnb - Číslo národní bibl. [Number of national bibl.]
  • icz - Identifikační číslo [Identification number]
  • sys - Systémové číslo [System number]
  • wpk
exception aleph.aleph.AlephException(message)[zdroj]

Exception tree:

- AlephException
  |- InvalidAlephBaseException
  |- InvalidAlephFieldException
  |- LibraryNotFoundException
  `- DocumentNotFoundException
exception aleph.aleph.InvalidAlephBaseException(message)[zdroj]
exception aleph.aleph.InvalidAlephFieldException(message)[zdroj]
exception aleph.aleph.LibraryNotFoundException(message)[zdroj]
exception aleph.aleph.DocumentNotFoundException(message)[zdroj]
class aleph.aleph.DocumentID[zdroj]

This structure is used to store “pointer” to document in aleph.

id

int – ID of document.

library

str – This can be different for each document, depend on your system.

base

str – Default “nkc”, but really depends on what bases you have defined in your Aleph server.

aleph.aleph.getListOfBases()[zdroj]

This function is here mainly for purposes of unittest

Vrací:Valid bases as they are used as URL parameters in links at Aleph main page.
Typ návratové hodnoty:
 list of str
aleph.aleph.searchInAleph(base, phrase, considerSimilar, field)[zdroj]

Send request to the aleph search engine.

Request itself is pretty useless, but it can be later used as parameter for getDocumentIDs(), which can fetch records from Aleph.

Parametry:
  • base (str) – which database you want to use
  • phrase (str) – what do you want to search
  • considerSimilar (bool) – fuzzy search, which is not working at all, so don’t use it
  • field (str) – where you want to look (see: VALID_ALEPH_FIELDS)
Vrací:

consisting from following fields:

error (optional): present if there was some form of error
no_entries (int): number of entries that can be fetch from aleph
no_records (int): no idea what is this, but it is always >= than no_entries
set_number (int): important - something like ID of your request
session-id (str): used to count users for licensing purposes
Typ návratové hodnoty:
 

dictionary

Example

Returned dict:

{
 'session-id': 'YLI54HBQJESUTS678YYUNKEU4BNAUJDKA914GMF39J6K89VSCB',
 'set_number': 36520,
 'no_records': 1,
 'no_entries': 1
}
Raises:
aleph.aleph.downloadRecords(search_result, from_doc=1)[zdroj]

Download MAX_RECORDS documents from search_result starting from from_doc.

Attr:
search_result (dict): returned from searchInAleph(). from_doc (int, default 1): Start from document number from_doc.
Vrací:List of XML strings with documents in MARC OAI.
Typ návratové hodnoty:
 list
aleph.aleph.getDocumentIDs(aleph_search_result, number_of_docs=-1)[zdroj]

Get IDs, which can be used as parameters for other functions.

Parametry:
  • aleph_search_result (dict) – returned from searchInAleph()
  • number_of_docs (int, optional) – how many DocumentID from set given by aleph_search_result should be returned. Default -1 for all of them.
Vrací:

DocumentID named tuples to given aleph_search_result.
Typ návratové hodnoty:
 

list
Raises:

AlephException – If Aleph returns unknown format of data.

Poznámka

Returned DocumentID can be used as parameters to downloadMARCXML().

aleph.aleph.downloadMARCXML(doc_id, library, base='nkc')[zdroj]

Download MARC XML document with given doc_id from given library.

Parametry:
Vrací:

MARC XML unicode string.
Typ návratové hodnoty:
 

str
Raises:
aleph.aleph.downloadMARCOAI(doc_id, base)[zdroj]

Download MARC OAI document with given doc_id from given (logical) base.

Funny part is, that some documents can be obtained only with this function in their full text.

Parametry:
  • doc_id (str) – You will get this from getDocumentIDs().
  • base (str, optional) – Base from which you want to download Aleph document. This seems to be duplicite with searchInAleph() parameters, but it’s just something Aleph’s X-Services wants, so ..
Vrací:

MARC XML Unicode string.
Typ návratové hodnoty:
 

str
Raises:
aleph.aleph.getISBNsXML(isbn, base='nkc')[zdroj]

Download full XML record for given isbn in base.

Parametry:
Vrací:

List of strings with full OAI XML representation of the record.
Typ návratové hodnoty:
 

list
aleph.aleph.getISSNsXML(issn, base='nkc')[zdroj]

Download full XML record for given issn in base.

Parametry:
Vrací:

List of strings with full OAI XML representation of the record.
Typ návratové hodnoty:
 

list
aleph.aleph.getAuthorsBooksXML(author, base='nkc')[zdroj]

Download full XML record for given author in base.

Parametry:
Vrací:

List of strings with full OAI XML representation of the record.
Typ návratové hodnoty:
 

list
aleph.aleph.getPublishersBooksXML(publisher, base='nkc')[zdroj]

Download full XML record for given publisher in base.

Parametry:
Vrací:

List of strings with full OAI XML representation of the record.
Typ návratové hodnoty:
 

list
aleph.aleph.getBooksTitleXML(title, base='nkc')[zdroj]

Download full XML record for given title in base.

Parametry:
Vrací:

List of strings with full OAI XML representation of the record.
Typ návratové hodnoty:
 

list
aleph.aleph.getICZBooksXML(icz, base='nkc')[zdroj]

Download full XML record for given icz (identification number) in base.

Parametry:
Vrací:

List of strings with full OAI XML representation of the record.
Typ návratové hodnoty:
 

list
aleph.aleph.getISBNsIDs(isbn, base='nkc')[zdroj]

Get list of DocumentID objects of documents with given isbn.

Parametry:
Vrací:

of DocumentID objects
Typ návratové hodnoty:
 

list
aleph.aleph.getAuthorsBooksIDs(author, base='nkc')[zdroj]

Get list of DocumentID objects of documents with given author.

Parametry:
Vrací:

of DocumentID objects
Typ návratové hodnoty:
 

list
aleph.aleph.getPublishersBooksIDs(publisher, base='nkc')[zdroj]

Get list of DocumentID objects of documents with given publisher.

Parametry:
  • publisher (str) – Name of publisher which will be used to search Aleph.
  • base (str, optional) – base on which will be search performed. Default aleph.settings.ALEPH_DEFAULT_BASE.
Vrací:

of DocumentID objects
Typ návratové hodnoty:
 

list
aleph.aleph.getBooksTitleIDs(title, base='nkc')[zdroj]

Get list of DocumentID objects of documents with given title.

Parametry:
  • title (str) – Title (name) of the book which will be used to search in Aleph.
  • base (str, optional) – base on which will be search performed. Default aleph.settings.ALEPH_DEFAULT_BASE.
Vrací:

of DocumentID objects
Typ návratové hodnoty:
 

list
aleph.aleph.getICZBooksIDs(icz, base='nkc')[zdroj]

Get list of DocumentID objects of documents with given icz (identification number).

Parametry:
Vrací:

of DocumentID objects
Typ návratové hodnoty:
 

list
aleph.aleph.getISBNCount(isbn, base='nkc')[zdroj]

Get number of records in Aleph which match given isbn.

Parametry:
Vrací:

Number of matching documents in Aleph.
Typ návratové hodnoty:
 

int
aleph.aleph.getAuthorsBooksCount(author, base='nkc')[zdroj]

Get number of records in Aleph which match given author.

Parametry:
Vrací:

Number of matching documents in Aleph.
Typ návratové hodnoty:
 

int
aleph.aleph.getPublishersBooksCount(publisher, base='nkc')[zdroj]

Get number of records in Aleph which match given publisher.

Parametry:
  • publisher (str) – Name of publisher which will be used to search Aleph.
  • base (str, optional) – base on which will be search performed. Default aleph.settings.ALEPH_DEFAULT_BASE.
Vrací:

Number of matching documents in Aleph.
Typ návratové hodnoty:
 

int
aleph.aleph.getBooksTitleCount(title, base='nkc')[zdroj]

Get number of records in Aleph which match given title.

Parametry:
  • title (str) – Title (name) of book which will be used to search Aleph.
  • base (str, optional) – base on which will be search performed. Default aleph.settings.ALEPH_DEFAULT_BASE.
Vrací:

Number of matching documents in Aleph.
Typ návratové hodnoty:
 

int
aleph.aleph.getICZBooksCount(icz, base='nkc')[zdroj]

Get number of records in Aleph which match given title.

Parametry:
Vrací:

Number of matching documents in Aleph.
Typ návratové hodnoty:
 

int