isbnlib

library3.10.14pypypi✓ verified 84d ago

ISBNlib is an active Python library (current version 3.10.14) providing a pure-Python solution for extracting, cleaning, transforming, hyphenating, and fetching metadata for ISBNs (International Standard Book Numbers). It offers a straightforward API for various ISBN-related tasks and receives frequent minor updates to its internal data ranges and service integrations.

serialization data

pip install isbnlib

github ↗package ↗

INSTALL

IMPORT

SIG · ISBNLIB

isbnlib

serializationpythonv3.10.14

Install

1.5s avg

Import

193ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.10.14 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.204s · 18.2MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.5s · import 0.182s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

canonical

✓ from isbnlib import canonical

✗ import isbnlib; isbnlib.canonical()

Importing specific functions directly is idiomatic and clearer than importing the entire library and prefixing all calls.

is_isbn13

✓ from isbnlib import is_isbn13

✗ import isbnlib; isbnlib.is_isbn13()

Importing specific functions directly is idiomatic and clearer.

meta

✓ from isbnlib import meta

✗ import isbnlib; isbnlib.meta()

Importing specific functions directly is idiomatic and clearer, especially for frequently used functions like `meta`.

mask

✓ from isbnlib import mask

info

✓ from isbnlib import info

This quickstart demonstrates how to clean (canonicalize), validate, retrieve metadata, and hyphenate an ISBN using `isbnlib`'s core functions. It uses a known ISBN-13 and prints the results.

from isbnlib import canonical, is_isbn13, meta, mask # An example ISBN-13 (striped, only digits and X) isbn_like = "978-0446310789" # 1. Canonicalize the ISBN canonical_isbn = canonical(isbn_like) print(f"Canonical ISBN: {canonical_isbn}") # 2. Validate the ISBN if is_isbn13(canonical_isbn): print(f"'{canonical_isbn}' is a valid ISBN-13 format.") else: print(f"'{canonical_isbn}' is not a valid ISBN-13 format.") # 3. Get metadata (default service is 'goob' - Google Books) try: book_metadata = meta(canonical_isbn) if book_metadata: print("\nBook Metadata:") for key, value in book_metadata.items(): print(f" {key}: {value}") else: print(f"\nNo metadata found for ISBN: {canonical_isbn}") except Exception as e: print(f"\nError fetching metadata: {e}") # 4. Mask (hyphenate) the ISBN hyphenated_isbn = mask(canonical_isbn) print(f"\nHyphenated ISBN: {hyphenated_isbn}")

isbnlib --version

Debug

Known issues

breakingThe helper function `to_utf8tex` was dropped in version 3.10.14. Code relying on this function will break upon upgrade.

fix

Remove or replace calls to `to_utf8tex`. Review release notes for alternative functionality if needed, though this function was internal/helper-level.

affects: >=3.10.14

gotchaThe quality and availability of metadata vary significantly between services (Google Books, Open Library, Wikipedia, etc.). Some ISBNs may return incomplete or no data from a default service.

fix

Explicitly try different services when fetching metadata, e.g., `meta(isbn, service='openl')` or `meta(isbn, service='wiki')`.

affects: All versions

gotcha`isbnlib` distinguishes between a *structurally valid* ISBN (e.g., `is_isbn13()`) and an *issued* (registered) ISBN. An ISBN can be structurally correct but not yet assigned or found in metadata services.

fix

Understand that `is_isbn13()` returning `True` does not guarantee an ISBN has been issued or that `meta()` will find data. Always handle cases where `meta()` returns an empty dictionary.

affects: All versions

gotchaSystem package manager versions of `isbnlib` (e.g., via `apt` or `yum`) are frequently outdated and may not work correctly or contain the latest ISBN data ranges. `pip` is the recommended installation method.

fix

Always install `isbnlib` using `pip` (`pip install isbnlib`) within a virtual environment. Avoid system-level package managers for Python libraries unless strictly necessary.

affects: All versions

gotchaConfiguration changes, such as setting default metadata services or API keys via `isbnlib.config` or `isbnlib.registry`, are session-specific and must be re-applied each time your application starts.

fix

Place configuration calls (e.g., `config.add_apikey()`, `registry.setdefaultservice()`) at the entry point of your application or whenever a new session starts.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'isbnlib'

The `isbnlib` library is not installed in the currently active Python environment, or there are permission issues (e.g., installing as a user, but running a script as root).

fix

Ensure `isbnlib` is installed in the correct environment using `pip install isbnlib`. If encountering issues on Linux with `sudo`, try `sudo pip install isbnlib` (though virtual environments are preferred).

isbnlib.exceptions.ISBNLibURLError: Service unavailable or network error during metadata fetch. (or similar KeyError during metadata retrieval, e.g., KeyError: '9781585109043default')

The chosen metadata service (default is Google Books, 'goob') is either temporarily down, unreachable due to network issues, or does not recognize the ISBN.

fix

Check your internet connection. Try explicitly requesting metadata from a different service, such as `meta(isbn, service='openl')` or `meta(isbn, service='wiki')`.

`meta(isbn)` returns an empty dictionary `{}` or very sparse data.

The metadata service could not find data for the provided ISBN, or the available data is minimal. Different services specialize in different types of books or regions.

fix

Experiment with various metadata services, for example, `meta(isbn, service='goob')`, `meta(isbn, service='openl')`, or `meta(isbn, service='wiki')`. Consider updating `isbnlib` to ensure you have the latest service configurations and data ranges.

`isbnlib.mask(isbn)` does not hyphenate a valid ISBN, or produces an unexpected output format.

The internal data ranges used by `isbnlib` to determine hyphenation points might be outdated for recently issued ISBNs.

fix

Update `isbnlib` to the latest version (`pip install --upgrade isbnlib`) to ensure the most current ISBN data ranges are available for correct hyphenation.

Upgrade

Version history

3.10.14latest on PyPI · released Apr 26, 2023

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/xlcnd/isbnlib ↗

packagehttps://pypi.org/project/isbnlib/ ↗