.. image:: https://github.com/xlcnd/isbnlib/workflows/tests/badge.svg :target: https://github.com/xlcnd/isbnlib/actions :alt: Built Status

.. image:: https://img.shields.io/github/issues/xlcnd/isbnlib/bug.svg?label=bugs&style=flat :target: https://github.com/xlcnd/isbnlib/labels/bug :alt: Bugs

.. image:: https://img.shields.io/pypi/dm/isbnlib.svg?style=flat :target: https://pypi.org/project/isbnlib/ :alt: PYPI Downloads

Info

isbnlib is a (pure) python library that provides several useful methods and functions to validate, clean, transform, hyphenate and get metadata for ISBN strings.

Install

From the command line, enter (in some cases you have to precede the command with sudo):

.. code-block:: bash

$ pip install isbnlib

If you use linux systems, you can install using your distribution package manager (all major distributions have packages python-isbnlib and python3-isbnlib), however these are (usually) very old and don't work well any more!

ISBN

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 'stripped' 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 'stripped' ISBN, whereas when the argument is an 'isbnlike', it is a string like ISBN 979-10-90636-07-1 or even something dirty like asdf 979-10-90636-07-1 bla bla.

Two important concepts: a valid ISBN should be an ISBN that was built according to the rules, which is distinct from an issued ISBN, which 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 for 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 ISBNs in the ISBN-13 format are issued). You can always convert ISBN-10 to ISBN-13, but not the reverse (read this_). Read more about ISBNs at isbn-international.org_ or wikipedia_.

Main Functions

is_isbn10(isbn10like) Validates as ISBN-10.

is_isbn13(isbn13like) Validates as ISBN-13.

to_isbn10(isbn13) Transforms ISBN-13 to ISBN-10.

to_isbn13(isbn10) Transforms ISBN-10 to ISBN-13.

canonical(isbnlike) Keeps only digits and X. You will get strings like 9780321534965 and 954430603X.

clean(isbnlike) Cleans ISBN (only legal characters).

notisbn(isbnlike, level='strict') Checks with the goal of invalidating ISBN-like.

get_isbnlike(text, level='normal') Extracts all substrings that seem like ISBNs (very useful for scraping).

get_canonical_isbn(isbnlike, output='bouth') Extracts ISBNs and transforms them to the canonical form.

ean13(isbnlike) Transforms an isbnlike string into an EAN13 number (validated canonical ISBN-13).

doi(isbn) Returns a DOI's ISBN-A from a ISBN-13.

mask(isbn, separator='-') Mask (hyphenate) a canonical ISBN.

info(isbn) Gets the language or country assigned to this ISBN.

meta(isbn, service='default') Gives you the main metadata associated with the ISBN. As the service parameter you can use: 'goob' uses the Google Books service (no key is needed) and is the default option, 'wiki' uses the wikipedia.org API (no key is needed), '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 bibtex, csl (CSL-JSON), msword, endnote, refworks, opf or json (BibJSON) bibliographic formats with registry.bibformatters. Now, you can extend the functionality of this function by adding plugins, more metadata providers or new bibliographic formatters (check_ for available plugins).

editions(isbn, service='merge') Returns the list of ISBNs of editions related with this ISBN. By default uses 'merge' (merges 'openl', 'thingl' and 'wiki'), but other providers are available: 'openl' (uses the search API from Open Library), 'thingl' (uses the service ThingISBN from LibraryThing), 'wiki' (uses the service Citation from Wikipedia) and 'any' (first tries 'wiki', if no data then 'openl').

isbn_from_words(words) Returns the most probable ISBN from a list of words (for your geographic area).

goom(words) Returns a list of references from Google Books multiple references.

classify(isbn) Returns a dictionary of classifiers for a canonical ISBN. For the meaning of these classifiers see OCLC_. Most of the data in the underlying service are for books in English. (See issue 138_).

desc(isbn) Returns a small description of the book. Almost all data available are for US books!

cover(isbn) Returns a dictionary with the url for cover. Almost all data available are for US books!

doi2tex(DOI) Returns metadata formatted as BibTeX for a given DOI.

ren(filename) Renames a file using metadata for an ISBN in the filename.

See files test_core_ and test_ext_ for a lot of examples.

Plugins

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 installing, your plugin will blend transparently in isbnlib (you will have more options in meta and bibformatters).

For Devs

API's Main Namespaces

In the namespace isbnlib you have access to the core functions: is_isbn10, is_isbn13, to_isbn10, to_isbn13, canonical, clean, notisbn, get_isbnlike, get_canonical_isbn, mask, info, check_digit10, check_digit13, doi and ean13.

In addition, you have access to metadata functions, namely: meta, editions, ren, desc, cover, goom, classify, doi2tex and isbn_from_words.

The exceptions raised by these methods can all be caught using ISBNLibException.

You can extend the lib by using the classes and functions exposed in the namespace isbnlib.dev, namely:

• WEBService a class that handles access to web services (just by passing a url) and supports gzip. You can subclass it to extend the functionality... but you probably 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. Its 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. The merge method allows implementing a simple merging procedure for records from different sources. The main features of this class can be implemented by calling the stdmeta function instead!

• vias exposes several functions to make calls to services simply by passing the name and a pointer to the service's query function. vias.parallel allows making 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 caught using ISBNLibDevException (or, more generally, ISBNLibException). You shouldn't raise this exception in your code, only raise the specific exceptions exposed in isbnlib.dev whose names end in Error.

In isbnlib.dev.helpers you can find several methods that we found very useful, some of which are only used in isbntools (an app and framework that uses isbnlib).

With isbnlib.config you can read and set configuration options: change timeouts with seturlopentimeout and setthreadstimeout, access API keys with apikeys and add new ones with add_apikey, access and set generic and user-defined options with options.get('OPTION1') and set_option.

Finally, from 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 cache set_cache(None)). The cache only works for calls through metadata functions. These changes only work for the 'current session', so should always be done 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 formatted in BibTeX.

A minimal script would be:

.. code-block:: python

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)))

Patterns of Usage

The library implements a very simple API with sensible defaults, but there are cases that need your attention (see case 3 below).

A. You only need core functions:

.. code-block:: python

# import the core functions you need
from isbnlib import canonical, is_isbn10, is_isbn13

isbn = canonical("978-0446310789")
if is_isbn13(isbn):
    ...
...

B. You also need metadata functions with the default config:

.. code-block:: python

from isbnlib import canonical, meta, description

isbn = canonical("978-0446310789")
data = meta(isbn)
...

C. You also need metadata functions with a special config:

Let's suppose you need to add an API key for a metadata plugin and change the cache too.

.. code-block:: python

from myapp.utils import MyCache

# import the functions you need, plus 'config' and 'registry'
from isbnlib import canonical, config, meta, registry

# you should use 'config' first
config.add_apikey("isbndb", "kjshdfkjahsdflkjh")

# then 'registry'
registry.set_cache(MyCache())

# Only now should you use metadata functions
# (there are no adaptions for core functions,
# so they can be used at any time)
isbn = canonical("978-0446310789")
data = meta(isbn, service="isbndb")
...

D. You want to build a plugin or use isbnlib.dev in your code:

You should study the public methods in dir(isbnlib.dev) very carefully, starting with this template_ and following the instructions there. For inspiration take a look at goob_.

Most of the public bibliographic catalog services return data in SRU or Unimarc format. It is very easy to write a customer plugin for these services, just use porbase_ (SRU) or sbn_ (Unimarc) as templates and consult this project_.

Caveats

1. These classes are optimized for single calls to services and not for batch calls.

2. If you inspect the library, you will see that there are a lot of private modules (their names start with '_'). These modules should not be accessed directly since there's a high probability your program will break with a future version of the library!

Projects using isbnlib

Open Library https://github.com/internetarchive/openlibrary

NYPL Library Simplified https://github.com/NYPL-Simplified

RERO ILS https://github.com/rero/rero-ils

CERN CDS RDM https://github.com/CERNDocumentServer/cds-rdm

ResearchHub https://github.com/ResearchHub/researchhub-backend

Manubot https://github.com/manubot

isbntools https://github.com/xlcnd/isbntools

isbnsrv https://github.com/xlcnd/isbnsrv

See the full list here_.

Help

If you need help, please take a look at github_ or post a question on stackoverflow_.

.. _github: https://github.com/xlcnd/isbnlib/discussions

.. _range: https://www.isbn-international.org/range_file_generation

.. _isbntools: https://pypi.python.org/pypi/isbntools

.. _sourcegraph: http://bit.ly/ISBNLib_srcgraph

.. _readthedocs: http://bit.ly/ISBNLib_rtd

.. _stackoverflow: http://stackoverflow.com/search?tab=newest&q=isbnlib

.. _test_core: https://github.com/xlcnd/isbnlib/blob/master/isbnlib/test/test_core.py

.. _test_ext: https://github.com/xlcnd/isbnlib/blob/master/isbnlib/test/test_ext.py

.. _isbn-international.org: https://www.isbn-international.org/content/what-isbn

.. _wikipedia: http://en.wikipedia.org/wiki/International_Standard_Book_Number

.. _python-future.org: http://python-future.org/compatible_idioms.html

.. _issue: https://github.com/xlcnd/isbnlib/issues/28

.. _check: https://pypi.python.org/pypi?%3Aaction=search&term=isbnlib_&submit=search

.. _template: https://github.com/xlcnd/isbnlib/blob/dev/PLUGIN.zip

.. _goob: https://github.com/xlcnd/isbnlib/blob/dev/isbnlib/_goob.py

.. _search: https://pypi.python.org/pypi?%3Aaction=search&term=isbnlib&submit=search

.. _51: https://github.com/xlcnd/isbnlib/issues/51

.. _here: https://github.com/xlcnd/isbnlib/network/dependents?package_id=UGFja2FnZS01MjIyODAxMQ%3D%3D

.. _OCLC: http://classify.oclc.org/classify2/

.. _this: http://web.archive.org/web/20211024015637/https://bisg.org/news/479346/New-979-ISBN-Prefixes-Expected-in-2020.htm

.. _sbn: https://github.com/arangb/isbnlib-sbn/blob/main/isbnlib_sbn/_sbn.py

.. _porbase: https://github.com/xlcnd/isbnlib-porbase/blob/dev/isbnlib_porbase/_porbase.py

.. _project: https://github.com/xlcnd/isbnlib/issues?q=is%3Aissue+is%3Aopen+label%3Aproject

.. _138: https://github.com/xlcnd/isbnlib/issues/138