Package: isbnlib
Infoisbnlibis a (pure) python library that provides several
useful methods and functions to validate, clean, transform, hyphenate and
get metadata for ISBN strings.InstallFrom the command line, enter (in some cases you have to precede the
command withsudo):$pipinstallisbnlibIf you use linux systems, you can install using your distribution package
manager (all major distributions have packagespython-isbnlibandpython3-isbnlib), however (usually) arevery old and don’t work well anymore!ISBNThe official form of an ISBN is something likeISBN979-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 usingcanonical(isbnlike). You can
‘mask’ the ISBN by usingmask(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
likeISBN979-10-90636-07-1or even something dirty likeasdf979-10-90636-07-1bla bla.Two important concepts:valid ISBNshould be an ISBN that was built according with the rules,
this is distinct fromissued ISBNthat is an ISBN that was already issued to a publisher
(this is the usage of the libraries and most of the web services).
Howeverisbn.org, probably by legal reasons, merges the two!
So, according toisbn-international.org, ‘9786610326266’ is not valid (because the block 978-66…
has not been issued yet, however if you useis_isbn13('9786610326266')you will getTrue(because ‘9786610326266’ follows the rules of an ISBN). But the situation is even murkier,
trymeta('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, butnotthe reverse (readthis).
Read more about ISBN atisbn-international.orgorwikipedia.Main Functionsis_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 like9780321534965and954430603X.clean(isbnlike)Cleans ISBN (only legal characters).notisbn(isbnlike,level='strict')Check with the goal to invalidate 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 transform them to the canonical form.ean13(isbnlike)Transforms anisbnlikestring 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. Asserviceparameter you can use:'goob'uses theGoogle Books service(no key is needed)  andis the default option,'wiki'uses thewikipedia.orgapi (no key is needed),'openl'uses theOpenLibrary.orgapi (no key is needed).
You can enter API keys
withconfig.add_apikey(service, apikey)(see example below).
The output can be formatted asbibtex,csl(CSL-JSON),msword,endnote,refworks,opforjson(BibJSON) bibliographic formats withregistry.bibformatters.
Now, you can extend the functionality of this function by adding plugins, more metadata
providers or new bibliographic formatters (checkfor 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 fromOpen Library),
‘thingl’ (uses the service ThingISBN fromLibraryThing),
‘wiki’ (uses the service Citation fromWikipedia)
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 fromGoogle Books multiple references.classify(isbn)Returns a dictionary ofclassifiersfor a canonical ISBN. For the meaning of these classifiers seeOCLC.
Most of the data in the underlying service are for books in english.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 from an ISBN in his filename.See filestest_coreandtest_extfora lot of examples.PluginsYou can extend the functionality of the library by adding plugins (for now, just
new metadata providers or new bibliographic formatters).For available pluginscheckhere.After install, your plugin will blend transparently inisbnlib(you will have more options inmetaandbibformatters).For DevsAPI’s Main NamespacesIn the namespaceisbnlibyou have access to thecore functions:is_isbn10,is_isbn13,to_isbn10,to_isbn13,canonical,clean,notisbn,get_isbnlike,get_canonical_isbn,mask,info,check_digit10,check_digit13,doiandean13.In addition, you have access tometadata functions, namely:meta,editions,ren,desc,cover,goom,classify,doi2texandisbn_from_words.The exceptions raised by these methods can all be caught usingISBNLibException.You can extend the lib by using the classes and functions exposed in
namespaceisbnlib.dev, namely:WEBServicea class that handles the access to web
services (just by passing an url) and supportsgzip.
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 usesWEBServiceto 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_checkerandparser). It implements athrottling mechanismwith a default rate of
one call per second per service.Metadataa class that structures, cleans and ‘validates’ records of
metadata. His methodmergeallows to implement a simple merging
procedure for records from different sources. The main features of this class, can be
implemented by a call to thestdmetafunction instead!viasexposes several functions to put calls to services, just by passing the name and
a pointer to the service’squeryfunction.vias.parallelallows to put threaded calls.
You can usevias.serialto make serial calls andvias.multito use several cores. The default isvias.serial.The exceptions raised by these methods can all be caught usingISBNLibDevException(or, more general,ISBNLibException).
Youshouldn’t raisethis exception in your code, only raise the specific exceptions
exposed inisbnlib.devwhose name ends in Error.Inisbnlib.dev.helpersyou can find several methods, that we found very useful, some of then
are only used inisbntools(an app and frameworkthat usesisbnlib).Withisbnlib.configyou can read and set configuration options:
change timeouts withseturlopentimeoutandsetthreadstimeout,
access api keys withapikeysand add new one withadd_apikey,
access and set generic and user-defined options withoptions.get('OPTION1')andset_option.Finally, fromisbnlib.registryyou 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 cacheset_cache(None)).
The cache only works for calls through metadata functions. 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 usingOpen Libraryformatted in BibTeX.A minimal script would be:fromisbnlibimportmetafromisbnlib.registryimportbibformattersSERVICE="openl"# now you can use the serviceisbn="9780446310789"bibtex=bibformatters["bibtex"]print(bibtex(meta(isbn,SERVICE)))Patterns of UsageThe library implements a very simple API with sensible defaults, but there are cases
that need your attention (see case 3 below).You only needcore functions:# import the core functions you needfromisbnlibimportcanonical,is_isbn10,is_isbn13isbn=canonical("978-0446310789")ifis_isbn13(isbn):......You need alsometadata functions, withdefault config:fromisbnlibimportcanonical,meta,descriptionisbn=canonical("978-0446310789")data=meta(isbn)...You need alsometadata functions, withspecial config:Lets suppose you need to add an api key for a metadata plugin
and change the cache too.frommyapp.utilsimportMyCache# import the functions you need, plus 'config' and 'registry'fromisbnlibimportcanonical,config,meta,registry# you should use 'config' firstconfig.add_apikey("isbndb","kjshdfkjahsdflkjh")# then 'registry'registry.set_cache(MyCache())# Only now you should use metadata functions# (there are no adaptions for core functions,#  so they can be used at any moment)isbn=canonical("978-0446310789")data=meta(isbn,service="isbndb")...You want to build apluginor useisbnlib.devin your code:You should study very carefully thepublicmethods indir(isbnlib.dev), start with thistemplateand follow the instructions there. For inspiration take a look atgoob.Most of the public bibliographic catalog services return data inSRUorUnimarcformat. It is very easy
to write a customerpluginfor these services, just useporbase(SRU) orsbn(Unimarc) as templates
and consult thisproject.CaveatsThese 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 modulesshould notbe accessed directly since,
with high probability, your program will break with a further version of the library!Projects usingisbnlibOpen Libraryhttps://github.com/internetarchive/openlibraryNYPL Library Simplifiedhttps://github.com/NYPL-SimplifiedRERO ILShttps://github.com/rero/rero-ilsCERN CDS RDMhttps://github.com/CERNDocumentServer/cds-rdmResearchHubhttps://github.com/ResearchHub/researchhub-backendManubothttps://github.com/manubotisbntoolshttps://github.com/xlcnd/isbntoolsisbnsrvhttps://github.com/xlcnd/isbnsrvSee the full listhere.HelpIf you need help, please take a look atgithubor post a question onstackoverflow.