API’s Main Namespaces
In the namespace isbnlib you have access to the core methods:
is_isbn10, is_isbn13, to_isbn10, to_isbn13, canonical,
clean, notisbn, get_isbnlike, get_canonical_isbn, mask,
meta, info, editions, goom, ren, doi, EAN13,
isbn_from_words, desc and cover.
The exceptions raised by these methods can all be catched using ISBNLibException.
You can extend the lib by using the classes and functions exposed in
namespace isbnlib.dev, namely:
- WEBService a class that handles the access to web
services (just by passing an url) and supports gzip.
You can subclass it to extend the functionality… but
probably you don’t need to use it! It is used in the next class.
- WEBQuery a class that uses WEBService to retrieve and parse
data from a web service. You can build a new provider of metadata
by subclassing this class.
His main methods allow passing custom
functions (handlers) that specialize them to specific needs (data_checker and
parser). It implements a throttling mechanism with a default rate of
one call per second per service.
- Metadata a class that structures, cleans and ‘validates’ records of
metadata. His method merge allows to implement a simple merging
procedure for records from different sources. The main features of this class, can be
implemented by a call to the stdmeta function instead!
- vias exposes several functions to put calls to services, just by passing the name and
a pointer to the service’s query function.
vias.parallel allows to put threaded calls.
You can use vias.serial to make serial calls and
vias.multi to use several cores. The default is vias.serial.
The exceptions raised by these methods can all be catched using ISBNLibDevException.
You should’t raise this exception in your code, only raise the specific exceptions
exposed in isbnlib.dev whose name end in Error.
In isbnlib.dev.helpers you can find several methods, that we found very useful, some of then
are only used in isbntools (an app and framework that uses isbnlib).
With isbnlib.registry you can change the metadata service to be used by default (setdefaultservice),
add a new service (add_service), access bibliographic formatters for metadata (bibformatters),
set the default formatter (setdefaultbibformatter), add new formatters (add_bibformatter) and
set a new cache (set_cache) (e.g. to switch off the chache set_cache(None)).
The cache only works for calls through isbnlib.meta. These changes only work for the ‘current session’,
so should be done always before calling other methods.
Finally, from isbnlib.config you can read and set configuration options:
change timeouts with seturlopentimeout and setthreadstimeout,
access api keys with apikeys and add new one with add_apikey and
access and set generic and user-defined options with options and set_option.
Let us concretize the last point with a small example.
Suppose you want a small script to get metadata using isbndb.org formated in BibTeX.
To use this service you need an api-key (get it here). A minimal script would be:
from isbnlib import meta
from isbnlib.config import add_apikey
from isbnlib.registry import bibformatters
SERVICE = 'isbndb'
APIKEY = 'THiSIsfAKe' # <-- replace with YOUR key
# register your key
# now you can use the service
isbn = '9780446310789'
bibtex = bibformatters['bibtex']