How book-to-skill Parses Command-Line Arguments for Extraction

book-to-skill parses command-line arguments through the _parse_args() helper in scripts/extract.py, which configures an argparse.ArgumentParser instance to handle verbose logging, JSON output, file destinations, configuration files, and input sources before routing to format-specific parsers.

The virgiliojr94/book-to-skill repository implements a deterministic extraction pipeline for converting various document formats into structured text. Understanding how it parses command-line arguments for extraction requires examining the interface between the CLI entry point and the parser autodetection system.

The Argument Parser Architecture

In scripts/extract.py, the private function _parse_args() (lines 14-44) encapsulates all command-line interface logic. This function instantiates an argparse.ArgumentParser with the prog name "extract" and a description for extracting structured text from documents. It accepts an optional argv parameter of type list[str] | None, enabling both programmatic invocation and direct CLI usage.

The parser configuration follows a standard argparse pattern, defining boolean flags, path arguments, and positional inputs that control the extraction behavior.

Supported Command-Line Arguments

The extraction script recognizes six distinct argument categories defined in the _parse_args() implementation:

Version Flag (-V, --version)
Displays the current package version using the __version__ import from book_to_skill and immediately exits.

Verbose Logging (-v, --verbose)
Enables DEBUG-level logging when present, defaulting to INFO level otherwise.

JSON Output Format (-j, --json)
Emits one JSON line per extracted entry instead of raw text strings.

Output Destination (-o, --output)
Accepts a Path type argument specifying a file to receive output. When omitted, results print to STDOUT.

Configuration File (-c, --config)
Loads an optional JSON configuration file passed to the underlying parser as a dictionary.

Source Document (src)
A positional argument defaulting to "-" (STDIN). Accepts file paths or the hyphen character to read from standard input.

From Arguments to Execution

The main() function (line 46) consumes the argparse.Namespace returned by _parse_args() to orchestrate the extraction pipeline:

1. Logging Configuration: Sets logging.DEBUG if args.verbose is true, otherwise logging.INFO.
2. Config Loading: Opens and parses the JSON file specified by args.config if provided.
3. Stream Selection: Opens args.src in binary read mode unless the value is "-", in which case it uses sys.stdin.buffer.
4. Parser Selection: Calls autodetect.select_parser(args.src) to determine the appropriate parser based on file extension.

Parser Autodetection Integration

The src argument directly drives parser selection through book_to_skill/parsers/autodetect.py. The select_parser() function (lines 14-33) normalizes the file extension to lowercase and maps it to specific parser modules:

• .txt or empty extension → text parser
• .rtf → rtf parser
• .pdf → pdf parser
• .html, .htm → html parser
• .epub → epub parser
• .docx → docx parser
• .cbz, .cbr → calibre parser
• Unknown extensions fall back to the generic text parser

This mapping occurs before extraction begins, ensuring the correct parser class handles the input stream.

Practical Usage Examples

Extract text from a PDF with default settings:

python scripts/extract.py book.pdf

Enable verbose debugging and output structured JSON to a file:

python scripts/extract.py -v -j -o skills.json manual.pdf

Process an EPUB using a custom configuration file:

python scripts/extract.py -c parser_config.json ebook.epub

Read from STDIN and output plain text:

cat document.txt | python scripts/extract.py -v -

Summary

• Entry Point: scripts/extract.py contains the CLI logic in _parse_args() and main().
• Argument Parsing: Uses Python's argparse module to define flags for version, verbosity, JSON output, output files, and configuration.
• Input Handling: The src positional argument accepts file paths or "-" for STDIN, defaulting to standard input.
• Parser Routing: File extensions determine parser selection via book_to_skill/parsers/autodetect.py, with a fallback to the text parser.
• Output Flexibility: Supports both STDOUT and file-based output, with optional JSON serialization per extracted entry.

Frequently Asked Questions

What command-line arguments does book-to-skill extract accept?

The extract command accepts -V/--version for version info, -v/--verbose for debug logging, -j/--json for JSON line output, -o/--output for file destinations, -c/--config for JSON configuration files, and the positional src argument for input sources.

How does book-to-skill determine which parser to use?

After parsing arguments, main() calls autodetect.select_parser() in book_to_skill/parsers/autodetect.py, which inspects the file extension of the src argument (case-insensitive) and returns the corresponding parser module. Unknown extensions default to the generic text parser.

Can book-to-skill read input from STDIN instead of a file?

Yes, the src argument defaults to "-", which instructs the script to read from sys.stdin.buffer. You can explicitly specify the hyphen or simply pipe content into the command without providing a file path.

How do I enable detailed debugging output during extraction?

Pass the -v or --verbose flag when invoking the script. This sets the logging level to DEBUG in main(), causing thelogger to emit detailed information about config loading, parser selection, and extraction progress.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}