How ekam02/wordweave works
Project type and purpose
• WordWeave is a Python-based command-line application whose goal is to generate Anki flashcards from lists of English words by scraping definitions/examples from various online dictionaries (Cambridge, Oxford, and a site called “Inglés”).
• It reads word lists, fetches data from external dictionary pages, transforms that data into card “notes” (by part of speech), and outputs a deck file that can be imported into Anki.
File structure
• Top-level files:
• main.py – orchestration entry point
• requirements.txt – external dependencies
• README.md, LICENSE
• Directories:
• pages/ – scraper modules for each dictionary
• notes/ – note-factory modules (adjective, noun, verb, general vocabulary)
• utils/ – shared helpers (configuration, ID generation, word-list reading)
• tests/ – unit tests for each scraper module
• No database; output is an Anki deck file (likely created in main.py or a notes module).
README for additional insights
• README is minimal, but its title (“Maker Anki Flashcards (English)”) confirms that the core use case is automated flashcard generation.
Main components and their relationships
a. CLI Orchestrator (main.py)
• Reads CLI arguments or configuration
• Invokes utils.read_words to load a list of target words
• Iterates through each word, dispatching it to the scrapers and note generators
• Aggregates all Note objects into an Anki deck
• Writes out the deck file
b. Configuration Layer (utils/config.py)
• Central place for API endpoints, output paths, scraping parameters
• Injected into pages scrapers and main process
c. Word Input Layer (utils/read_words.py)
• Loads word lists from files or other sources
• Returns a normalized list for processing
d. Scraping Layer (pages/*.py)
• Three separate modules (cambridge, oxford, ingles)
• Each module:
• Accepts a word
• Fetches HTML from the corresponding dictionary website
• Parses out definitions, examples, pronunciations
• Returns raw data structures to the orchestrator
e. -Factory Layer (notes/*.py)
• Four modules: adjective, noun, verb, vocabulary
• Each module knows how to format scraped data into the correct Anki note template
• Provides a uniform Note object interface (fields: front, back, tags, etc.)
f. Output Layer (inside main.py or a notes utility)
• Aggregates Note objects into a deck
• Uses a library (e.g., genanki) to serialize into .apkg
g. Testing Layer (tests/*.py)
• Each scraper has its own test to verify parsing logic
• Ensures robustness against HTML changes
Architectural patterns and design principles
• Layered architecture (CLI → utilities → scrapers → note generators → output)
• Single responsibility per module (one dictionary scraper per file)
• Dependency injection of config into scrapers
• Test-driven approach for scraping logic
• Factory pattern for Note creation