Skip to main content

​
Overview

The books module provides functions for managing the library catalog, including local database operations and automatic metadata fetching from the Open Library API.

​
Get Book

async def get_book(isbn: str) -> Optional[dict]:
    """Fetch a single book by ISBN.
    
    Checks local DB first, then Open Library.
    """

​
Parameters

​
isbn
string
required
ISBN-10 or ISBN-13 identifier. Leading/trailing whitespace is stripped automatically.

​
Returns

​
book
dict | None
Returns book object if found (locally or via API), None if not found

​
Lookup Flow

  1. Local Database Check: Queries local SQLite database first
  2. Cache Hit: Returns immediately if book found locally
  3. API Fallback: If not found and USE_LIVE_API = True, queries Open Library
  4. Auto-Cache: Successful API results are automatically saved to local DB
  5. Offline Mode: Returns None if not found locally and USE_LIVE_API = False

​
Get Catalog

async def get_catalog() -> list:
    """Return all books ordered by title."""

​
Returns

​
books
list[dict]
List of all books in the catalog, sorted alphabetically by title

​
Use Cases

  • Browse Catalog: Display all books in the library
  • Search Implementation: Client-side filtering by title/author
  • Availability Check: Filter by status to show only available books
  • Pagination: Split large catalogs across multiple pages

​
Add Book

async def add_book(
    isbn: str,
    title: str,
    author: str,
    cover: str = ""
) -> bool:
    """Insert a new book.
    
    Returns True on success, False if the ISBN already exists.
    """

​
Parameters

​
isbn
string
required
Unique ISBN identifier for the book
​
title
string
required
Book title
​
author
string
required
Primary author name
​
cover
string
default:""
URL to book cover image. Defaults to empty string if not provided.

​
Returns

​
success
bool
  • True: Book was successfully added to the catalog
  • False: ISBN already exists in the database (duplicate)

​
Default Values

When a book is added, the following defaults are set automatically:
  • status: “Available”
  • shelf: "" (empty string)
  • cover: "" if not provided

​
Fetch from Open Library

async def _fetch_from_open_library(isbn: str) -> Optional[dict]:
    """Fetch book metadata from Open Library and cache it locally."""

​
Parameters

​
isbn
string
required
ISBN to lookup in the Open Library API

​
Returns

​
book
dict | None
Returns book object with fetched metadata, or None on failure

​
API Details

Endpoint: https://openlibrary.org/api/books Request Format: 
GET https://openlibrary.org/api/books?bibkeys=ISBN:{isbn}&format=json&jscmd=data
Headers:
  User-Agent: SCSU_CS_Library_Kiosk/1.0 ([email protected])
Timeout: 8 seconds Auto-Cache: Successful API responses are automatically saved to the local database using INSERT OR IGNORE

​
Error Handling

Returns None in the following cases:
  • HTTP response code is not 200
  • ISBN not found in Open Library database
  • Network timeout (8 seconds)
  • Any other exception during API call or database insert

​
Configuration

Toggle API usage with: 
USE_LIVE_API = False  # Disable for offline/testing mode
When disabled, get_book() only searches the local database.

Build docs developers (and LLMs) love

Get started for freeTalk to us