DOCSEARCHbyAlgolia
Submit Docs

isbntools Python Toolkit

repository·dev·Indexed 42 days ago

https://github.com/xlcnd/isbntools

A Python toolkit for validating, cleaning, transforming, and retrieving metadata for ISBN strings. It provides a programmatic API and a suite of CLI tools for bibliographic management, including metadata retrieval (isbntools meta), file renaming based on book data (isbn_ren), and configuration management via isbn_conf. Supported operations include resolving DOIs, retrieving book covers and descriptions, and listing book editions.

Tokens
5.6K
Snippets
33
Records
38
Agent score
53%

What's inside isbntools

  2. Install isbntools via pip

    dev

    Install the isbntools package using pip. On some systems, you may need to prefix the command with sudo.

    Note for Linux users: While distribution package managers may offer python-isbntools or python3-isbntools, these are often outdated and may not function correctly. It is recommended to use pip instead.

    $ pip install isbntools

  3. Configure isbntools via isbntools.conf

    dev

    You can manage API keys and preferences using a configuration file named isbntools.conf.

    File Locations:

    • UNIX: $HOME/.isbntools/isbntools.conf
    • Windows: %APPDATA%/isbntools/isbntools.conf
    • Virtual Environments: Inside the isbntools folder at the root of the environment.

    Management via isbn_conf: Instead of manual editing, use the isbn_conf script to manage settings:

    • isbn_conf make: Creates the configuration file and directory if they don't exist.
    • isbn_conf show: Displays the current configuration.
    • isbn_conf setopt cache no: Disables metadata caching.
    • isbn_conf delcache: Clears the metadata cache.

    Example Config Structure:

    [MISC]
REN_FORMAT={firstAuthorLastName}{year}_{title}_{isbn}
DEBUG=False

[SYS]
URLOPEN_TIMEOUT=10
THREADS_TIMEOUT=12
LOAD_METADATA_PLUGINS=True
LOAD_FORMATTER_PLUGINS=True

[SERVICES]
DEFAULT_SERVICE=goob
VIAS_MERGE=parallel
    $ isbn_conf make
$ isbn_conf show

  4. Use the isbn_ren CLI to rename files

    dev

    The isbn_ren command renames files based on book metadata retrieved via ISBN. It can either take an explicit ISBN as the first argument or attempt to extract an ISBN from the filename itself.

    Usage Patterns

    1. With explicit ISBN and pattern: isbn_ren [ISBN] [service] [apikey] [pattern] filename

    2. With glob patterns (searching for ISBN in filenames): If no ISBN is provided, you can use a glob pattern (e.g., *.pdf) to process multiple files. The tool will search each filename for a valid ISBN. isbn_ren [service] [apikey] [pattern] "*.pdf"

    Pattern Placeholders

    Patterns must be strings enclosed in quotes containing only ASCII letters, digits, and #-_.,() '. You can use the following placeholders:

    • {authorsFullNames}: Full names of the author(s), separated by commas.
    • {authorsLastNames}: Last names of the author(s).
    • {firstAuthorLastName}: Only the last name of the first author.
    • {year}: Publication year.
    • {publisher}: Publisher name.
    • {title}: Book title.
    • {isbn}: ISBN-13.
    • {language}: Language of the book.

    Default pattern: {firstAuthorLastName}{year}_{title}_{isbn}

    # Example: Rename a specific file using a custom pattern and a specific service
isbn_ren 9780140449136 google [YOUR_API_KEY] "{authorsLastNames}_{year}_{title}" my_book.pdf

# Example: Use a glob pattern to rename all PDFs in a directory
isbn_ren google [YOUR_API_KEY] "{title}_{isbn}" "*.pdf"

  5. Use the isbntools REPL

    dev

    The isbntools REPL (Read-Eval-Print Loop) provides an interactive environment to run various ISBN and DOI related commands.

    Key Features:

    • Fuzzy Matching: If you mistype a command, the REPL attempts to match it to the closest valid command.
    • Last ISBN Shortcut: Use # in place of an ISBN to repeat the last ISBN processed in the previous command.
    • Shell Integration: Prefix any command with ! to run it as a system shell command (e.g., !ls).
    • Help: Type help or ? to see available commands, or ?<command> to see documentation for a specific command.
    • Exit: Type exit to leave the REPL.
    # Start the REPL (assuming it is installed in your path)
$ isbntools

isbn> info 9780156001311
...

isbn> meta # opf
# (This uses the ISBN from the previous command)

  6. Register an API key via isbn_ren

    dev

    You can register an API key for a specific service directly through the isbn_ren command line. This uses the config.add_apikey mechanism to persist the key for future use.

    Command structure: isbn_ren [ISBN] [service] [apikey] [pattern] filename

    When you provide a service name and an API key in the arguments, the tool attempts to register that key for the service.

    isbn_ren 9780140449136 google MY_SECRET_API_KEY "{title}" book.pdf

  7. Use isbn_repl for an interactive REPL session

    dev

    The isbn_repl command launches an interactive Read-Eval-Print Loop with history, autocompletion, and fuzzy options. It is often faster for performing multiple operations in a single session.

    REPL Features:

    • Type ? or help to see available commands.
    • Use exit to quit.
    • Use !<shellcommand> to run a shell command.
    • Use # to refer to the last used ISBN.
    • Commands include meta, desc, cover, validate, to_isbn10, etc.
    $ isbn_repl

isbn> meta 9780156001311 tex
@book{9780156001311,
         title = {The Name Of The Rose},
        author = {Umberto Eco},
          isbn = {9780156001311},
          year = {1994},
     publisher = {Harcourt Brace}
}

  8. Use the meta command for metadata lookup

    dev

    The meta command retrieves metadata for a specific ISBN. You can optionally specify a provider, a bibliographic format, and an API key.

    Syntax: meta ISBN [PROVIDER] [BIBFORMAT] [apikey]

    Examples:

    • meta 9780156001311 openl endnote (Uses 'openl' provider and 'endnote' format)
    • meta 9780156001311 (Uses default provider and format)
    • meta 9780156001311 tex (Uses default provider and 'tex' format)
    • meta # opf (Uses the last ISBN with 'opf' format)
    isbn> meta 9780156001311 openl endnote
isbn> meta # opf

  11. Retrieve ISBN metadata with isbn_meta

    dev

    The isbn_meta command retrieves bibliographic metadata for a given ISBN.

    Usage: isbn_meta ISBN [goob|openl|wiki] [bibtex|csl|msword|endnote|refworks|opf|json] [YOUR_APIKEY]

    Arguments:

    • Service (Provider):
      • goob: Google Books service (default, no key required).
      • openl: OpenLibrary.org API (no key required).
      • wiki: Wikipedia API (no key required).
    • Format: Supports bibtex, csl (CSL-JSON), msword, endnote, refworks, opf, or json (BibJSON).
    • API Key: Optional key for the chosen service.

    Pro-tip: You can pipe multiple ISBNs into the command using POSIX pipes (e.g., type FILE.txt | isbn_meta).

    $ isbn_meta 9780321534965 goob bibtex

  12. Other useful isbntools CLI scripts

    dev

    Additional specialized scripts available via the command line:

    • isbn_from_words "string": Performs a fuzzy search to return the most probable ISBN from a title/author string.
    • isbn_goom "string" [format]: Returns multiple references from Google Books based on a string.
    • isbn_editions ISBN: Returns a collection of ISBNs representing the same book (uses Wikipedia and LibraryThing).
    • isbn_doi ISBN: Returns the DOI's ISBN-A code.
    • isbn_ean13 ISBN: Returns the EAN13 code.
    • isbn_classify ISBN: Returns OCLC classifiers.
    • isbn_ren FILENAME: Renames files in the current directory that contain ISBNs in their names (e.g., isbn_ren "*.pdf").