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¶
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
- ISSNsbn
- ISBN / ISMNisn
- ISBN / ISMN / ISSNob
- 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
-
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 errorno_entries (int): number of entries that can be fetch from alephno_records (int): no idea what is this, but it is always >= than no_entriesset_number (int): important - something like ID of your requestsession-id (str): used to count users for licensing purposesTyp návratové hodnoty: dictionary
Example
Returned dict:
{ 'session-id': 'YLI54HBQJESUTS678YYUNKEU4BNAUJDKA914GMF39J6K89VSCB', 'set_number': 36520, 'no_records': 1, 'no_entries': 1 }
Raises: AlephException
– if Aleph doesn’t return any informationInvalidAlephFieldException
– if specified field is not valid
-
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: Raises: AlephException
– If Aleph returns unknown format of data.Poznámka
Returned
DocumentID
can be used as parameters todownloadMARCXML()
.- aleph_search_result (dict) – returned from
-
aleph.aleph.
downloadMARCXML
(doc_id, library, base='nkc')[zdroj]¶ Download MARC XML document with given doc_id from given library.
Parametry: - doc_id (DocumentID) – You will get this from
getDocumentIDs()
. - library (str) – “
NKC01
” in our case, but don’t worry,getDocumentIDs()
adds library specification intoDocumentID
named tuple.
Vrací: MARC XML unicode string.
Typ návratové hodnoty: Raises: - doc_id (DocumentID) – You will get this from
-
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: Raises: - doc_id (str) – You will get this from
-
aleph.aleph.
getISBNsXML
(isbn, base='nkc')[zdroj]¶ Download full XML record for given isbn in base.
Parametry: - isbn (str) – ISBN of the books you want to get.
- base (str) – Base on which will be search performed. Default
aleph.settings.ALEPH_DEFAULT_BASE
.
Vrací: List of strings with full OAI XML representation of the record.
Typ návratové hodnoty:
-
aleph.aleph.
getISSNsXML
(issn, base='nkc')[zdroj]¶ Download full XML record for given issn in base.
Parametry: - issn (str) – ISSN of the books you want to get.
- base (str) – Base on which will be search performed. Default
aleph.settings.ALEPH_DEFAULT_BASE
.
Vrací: List of strings with full OAI XML representation of the record.
Typ návratové hodnoty:
-
aleph.aleph.
getAuthorsBooksXML
(author, base='nkc')[zdroj]¶ Download full XML record for given author in base.
Parametry: - author (str) – Name of the author of the books you want to get.
- base (str) – Base on which will be search performed. Default
aleph.settings.ALEPH_DEFAULT_BASE
.
Vrací: List of strings with full OAI XML representation of the record.
Typ návratové hodnoty:
-
aleph.aleph.
getPublishersBooksXML
(publisher, base='nkc')[zdroj]¶ Download full XML record for given publisher in base.
Parametry: - publisher (str) – Name of the publisher of the books you want to get.
- base (str) – Base on which will be search performed. Default
aleph.settings.ALEPH_DEFAULT_BASE
.
Vrací: List of strings with full OAI XML representation of the record.
Typ návratové hodnoty:
-
aleph.aleph.
getBooksTitleXML
(title, base='nkc')[zdroj]¶ Download full XML record for given title in base.
Parametry: - title (str) – title of the books you want to get.
- base (str) – Base on which will be search performed. Default
aleph.settings.ALEPH_DEFAULT_BASE
.
Vrací: List of strings with full OAI XML representation of the record.
Typ návratové hodnoty:
-
aleph.aleph.
getICZBooksXML
(icz, base='nkc')[zdroj]¶ Download full XML record for given icz (identification number) in base.
Parametry: - icz (str) – Identification number used to search Aleph.
- base (str) – Base on which will be search performed. Default
aleph.settings.ALEPH_DEFAULT_BASE
.
Vrací: List of strings with full OAI XML representation of the record.
Typ návratové hodnoty:
-
aleph.aleph.
getISBNsIDs
(isbn, base='nkc')[zdroj]¶ Get list of
DocumentID
objects of documents with given isbn.Parametry: - isbn (str) – ISBN string.
- base (str, optional) – Base on which will be search performed. Default
aleph.settings.ALEPH_DEFAULT_BASE
.
Vrací: of
DocumentID
objectsTyp návratové hodnoty:
-
aleph.aleph.
getAuthorsBooksIDs
(author, base='nkc')[zdroj]¶ Get list of
DocumentID
objects of documents with given author.Parametry: - author (str) – Authors name/lastname in UTF-8.
- base (str, optional) – base on which will be search performed. Default
aleph.settings.ALEPH_DEFAULT_BASE
.
Vrací: of
DocumentID
objectsTyp návratové hodnoty:
-
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
objectsTyp návratové hodnoty:
-
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
objectsTyp návratové hodnoty:
-
aleph.aleph.
getICZBooksIDs
(icz, base='nkc')[zdroj]¶ Get list of
DocumentID
objects of documents with given icz (identification number).Parametry: - icz (str) – Identification number used to search Aleph.
- base (str, optional) – base on which will be search performed. Default
aleph.settings.ALEPH_DEFAULT_BASE
.
Vrací: of
DocumentID
objectsTyp návratové hodnoty:
-
aleph.aleph.
getISBNCount
(isbn, base='nkc')[zdroj]¶ Get number of records in Aleph which match given isbn.
Parametry: - isbn (str) – ISBN string.
- 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:
-
aleph.aleph.
getAuthorsBooksCount
(author, base='nkc')[zdroj]¶ Get number of records in Aleph which match given author.
Parametry: - author (str) – Authors name/lastname in UTF-8.
- 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:
-
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:
-
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:
-
aleph.aleph.
getICZBooksCount
(icz, base='nkc')[zdroj]¶ Get number of records in Aleph which match given title.
Parametry: - icz (str) – Identification number 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: