How sleepysoong/booklistbuilder works
Project Type and Purpose
• BookListBuilder is an open-source CLI tool (with optional GUI builds via PyInstaller) that automates fetching book details (cover image, metadata, ratings, library holdings) and outputs a consolidated Excel file. It integrates with external services (Aladin OpenAPI and a school library web portal) to retrieve data.
Main Components
a. Input Layer
• config.yml – holds API key, library URL, desired output filename
• .xlsx – user’s list of ISBN13s, target sheet names, optional memos
b. Processing Core
• script.py – orchestrates workflow
– Config Loader
– ISBN List Reader (openpyxl)
– Data Fetchers
◦ AladinAPI Client (requests to Aladin OpenAPI)
◦ LibraryLookup Scraper (requests + HTML parsing of school library site)
– Data Merger & Transformer (combines metadata, ratings, library status)
– Excel Writer (openpyxl or pandas)
c. External Services
• Aladin OpenAPI – provides book metadata, ratings, sales points
• School Library Web Portal – indicates campus holdings
d. Output Layer
• output.xlsx – final Excel workbook with separate sheets per list entry
• (Optional) cover image downloads or embedded URLs
e. Packaging & Deployment
• PyInstaller build (GitHub Actions workflow) produces standalone executables for Windows/macOS
• GitHub Releases – distribution channel
Relationships and Data Flow
• User invokes script.py → config.yml & list.xlsx are read → for each ISBN:
1. Fetch metadata from Aladin API
2. Scrape library site to check holdings
3. Aggregate results → write rows into output.xlsx
• CI/CD (GitHub Actions) listens on push/tags → runs PyInstaller to produce binaries → publishes to Releases.
Architectural Patterns & Design Principles
• Modular layering: Input → Processing → Output
• Single-responsibility modules: separate fetchers, readers, writers
• External integration abstracted behind client interfaces
• CI/CD pipeline automates packaging