Breaking Change The service xISBN was decommissioned (see issue 51)!
isbnlib is a (pure) python library that provides several
useful methods and functions to validate, clean, transform, hyphenate and
get metadata for ISBN strings. Its origin was as the core of isbntools.
This short version, is suitable to be include as a dependency in other projects. Has a straightforward setup and a very easy programmatic api.
Runs on py27, py35, py36 and py37.
Typical usage (as library):
import isbnlib ...
The official form of an ISBN is something like
ISBN 979-10-90636-07-1. However for most applications only the numbers are important, you can always 'mask' them if you need (see below). This library works mainly with 'striped' ISBNs (only digits and X) like '0826497527'. You can strip an ISBN-like string by using
canonical(isbnlike). You can 'mask' the ISBN by using
mask(isbn). So in the examples below, when you see 'isbn' in the argument, it is a 'striped' ISBN, when the argument is an 'isbnlike' it is a string like
ISBN 979-10-90636-07-1or even something dirty like
asdf 979-10-90636-07-1 bla bla.
Two important concepts: valid ISBN should be an ISBN that was built according with the rules, this is distinct from issued ISBN that is an ISBN that was already issued to a publisher (this is the usage of the libraries and most of the web services). However isbn.org, probably by legal reasons, merges the two! So, according to isbn-international.org, '9786610326266' is not valid (because the block 978-66... has not been issued yet, however if you use
is_isbn13('9786610326266')you will get
True(because '9786610326266' follows the rules of an ISBN). But the situation is even murkier, try
meta('9786610326266')and you will see that this ISBN was already used!
If possible, work with ISBNs in the isbn-13 format (since 2007, only are issued ISBNs in the isbn-13 format). You can always convert isbn-10 to isbn-13, but not the reverse. Read more about ISBN at isbn-international.org or wikipedia.
- Validates as ISBN-10.
- Validates as ISBN-13.
- Transforms isbn-13 to isbn-10.
- Transforms isbn-10 to isbn-13.
- Keeps only digits and X. You will get strings like 9780321534965 and 954430603X.
- Cleans ISBN (only legal characters).
- Check with the goal to invalidate isbn-like.
- Extracts all substrings that seem like ISBNs (very useful for scraping).
- Extracts ISBNs and transform them to the canonical form.
- Transforms an isbnlike string into an EAN13 number (validated canonical ISBN-13).
- Gets the language or country assigned to this ISBN.
- Mask (hyphenate) a canonical ISBN.
meta(isbn, service='default', cache='default')
- Gives you the main metadata associated with the ISBN. As service parameter you can use:
'goob'uses the Google Books service (no key is needed) and is the default option,
'openl'uses the OpenLibrary.org api (no key is needed). You can enter API keys with
config.add_apikey(service, apikey)(see example below). The output can be formatted as
json(BibJSON) bibliographic formats with
cacheonly allows two values: 'default' or None. You can change the kind of cache by using
registry.set_cache(see below). Now, you can extend the functionality of this function by adding pluggins, more metadata providers or new bibliographic formatters (check for available pluggins).
- Returns the list of ISBNs of editions related with this ISBN. By default uses 'merge' (merges 'openl' and 'thingl'), but other providers are available: 'openl' users Open Library, 'thingl' (uses the service ThingISBN from LibraryThing) and 'any' (first tries 'openl', if no data, then 'thingl').
- Returns the most probable ISBN from a list of words (for your geographic area).
- Returns a list of references from Google Books multiple references.
- Returns a DOI's ISBN-A from a ISBN-13.
- Returns metadata formated as BibTeX for a given DOI.
- Renames a file using metadata from an ISBN in his filename.
- Returns a small description of the book. Almost all data available are for US books!
- Returns a dictionary with the url for cover. Almost all data available are for US books!
From the command line, enter (in some cases you have to preced the
$ pip install isbnlib
If you use linux systems, you can install using your distribution package
manager (all major distributions have packages
python3-isbnlib), however (usually) are very old and don't work well anymore!
API's Main Namespaces
In the namespace
isbnlib you have access to the core methods:
The exceptions raised by these methods can all be catched using
You can extend the lib by using the classes and functions exposed in
WEBServicea 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.
WEBQuerya class that uses
WEBServiceto 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 (
parser). It implements a throttling mechanism with a default rate of one call per second per service.
Metadataa class that structures, cleans and 'validates' records of metadata. His method
mergeallows 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
viasexposes several functions to put calls to services, just by passing the name and a pointer to the service's
vias.parallelallows to put threaded calls. You can use
vias.serialto make serial calls and
vias.multito use several cores. The default is
The exceptions raised by these methods can all be catched using
You should't raise this exception in your code, only raise the specific exceptions
isbnlib.dev whose name ends in Error.
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.config you can read and set configuration options:
change timeouts with
access api keys with
apikeys and add new one with
access and set generic and user-defined options with
isbnlib.registry you can change the metadata service to be used by default
add a new service (
add_service), access bibliographic formatters for metadata (
set the default formatter (
setdefaultbibformatter), add new formatters (
set a new cache (
set_cache) (e.g. to switch off the chache
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.
Let us concretize these points with a small example.
Suppose you want a small script to get metadata using
Open Library formated in BibTeX.
A minimal script would be:
from isbnlib import meta from isbnlib.registry import bibformatters SERVICE = 'openl' # now you can use the service isbn = '9780446310789' bibtex = bibformatters['bibtex'] print(bibtex(meta(isbn, SERVICE)))
You can extend the functionality of the library by adding plugins (for now, just new metadata providers or new bibliographic formatters).
For available plugins check here.
After install, your plugin will blend transparently in
isbnlib (you will have more options in
Remember that plugins must support python 2.7 and python 3.5+ (see python-future.org).
- These classes are optimized for one-call to services and not for batch calls.
- If you inspect the library, you will see that there are a lot of private modules (their name starts with '_'). These modules should not be accessed directly since, with high probability, your program will break with a further version of the library!
Projects using isbnlib
Open Library https://github.com/internetarchive/openlibrary
Comic Collector https://github.com/wengole/comiccollector