{"id":9050,"library":"isbnlib","title":"ISBNlib","description":"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.","status":"active","version":"3.10.14","language":"en","source_language":"en","source_url":"https://github.com/xlcnd/isbnlib","tags":["isbn","book","library","metadata","validation","parsing","bibliographic"],"install":[{"cmd":"pip install isbnlib","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"Importing specific functions directly is idiomatic and clearer than importing the entire library and prefixing all calls.","wrong":"import isbnlib; isbnlib.canonical()","symbol":"canonical","correct":"from isbnlib import canonical"},{"note":"Importing specific functions directly is idiomatic and clearer.","wrong":"import isbnlib; isbnlib.is_isbn13()","symbol":"is_isbn13","correct":"from isbnlib import is_isbn13"},{"note":"Importing specific functions directly is idiomatic and clearer, especially for frequently used functions like `meta`.","wrong":"import isbnlib; isbnlib.meta()","symbol":"meta","correct":"from isbnlib import meta"},{"symbol":"mask","correct":"from isbnlib import mask"},{"symbol":"info","correct":"from isbnlib import info"}],"quickstart":{"code":"from isbnlib import canonical, is_isbn13, meta, mask\n\n# An example ISBN-13 (striped, only digits and X)\nisbn_like = \"978-0446310789\"\n\n# 1. Canonicalize the ISBN\ncanonical_isbn = canonical(isbn_like)\nprint(f\"Canonical ISBN: {canonical_isbn}\")\n\n# 2. Validate the ISBN\nif is_isbn13(canonical_isbn):\n    print(f\"'{canonical_isbn}' is a valid ISBN-13 format.\")\nelse:\n    print(f\"'{canonical_isbn}' is not a valid ISBN-13 format.\")\n\n# 3. Get metadata (default service is 'goob' - Google Books)\ntry:\n    book_metadata = meta(canonical_isbn)\n    if book_metadata:\n        print(\"\\nBook Metadata:\")\n        for key, value in book_metadata.items():\n            print(f\"  {key}: {value}\")\n    else:\n        print(f\"\\nNo metadata found for ISBN: {canonical_isbn}\")\nexcept Exception as e:\n    print(f\"\\nError fetching metadata: {e}\")\n\n# 4. Mask (hyphenate) the ISBN\nhyphenated_isbn = mask(canonical_isbn)\nprint(f\"\\nHyphenated ISBN: {hyphenated_isbn}\")","lang":"python","description":"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."},"warnings":[{"fix":"Remove or replace calls to `to_utf8tex`. Review release notes for alternative functionality if needed, though this function was internal/helper-level.","message":"The helper function `to_utf8tex` was dropped in version 3.10.14. Code relying on this function will break upon upgrade.","severity":"breaking","affected_versions":">=3.10.14"},{"fix":"Explicitly try different services when fetching metadata, e.g., `meta(isbn, service='openl')` or `meta(isbn, service='wiki')`.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always install `isbnlib` using `pip` (`pip install isbnlib`) within a virtual environment. Avoid system-level package managers for Python libraries unless strictly necessary.","message":"System 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Place configuration calls (e.g., `config.add_apikey()`, `registry.setdefaultservice()`) at the entry point of your application or whenever a new session starts.","message":"Configuration 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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).","cause":"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).","error":"ModuleNotFoundError: No module named 'isbnlib'"},{"fix":"Check your internet connection. Try explicitly requesting metadata from a different service, such as `meta(isbn, service='openl')` or `meta(isbn, service='wiki')`.","cause":"The chosen metadata service (default is Google Books, 'goob') is either temporarily down, unreachable due to network issues, or does not recognize the ISBN.","error":"isbnlib.exceptions.ISBNLibURLError: Service unavailable or network error during metadata fetch. (or similar KeyError during metadata retrieval, e.g., KeyError: '9781585109043default')"},{"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.","cause":"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.","error":"`meta(isbn)` returns an empty dictionary `{}` or very sparse data."},{"fix":"Update `isbnlib` to the latest version (`pip install --upgrade isbnlib`) to ensure the most current ISBN data ranges are available for correct hyphenation.","cause":"The internal data ranges used by `isbnlib` to determine hyphenation points might be outdated for recently issued ISBNs.","error":"`isbnlib.mask(isbn)` does not hyphenate a valid ISBN, or produces an unexpected output format."}]}