feat: add sub-sheet selection for Excel files

[Utkarsh Verma (heyutkarshverma)]

This pull request enhances the Excel file conversion capabilities in the markitdown package by introducing new options for handling Excel sub-sheets. Users can now list available sheets, specify sheets to convert, or interactively select sheets. The changes also ensure that these options are integrated throughout the CLI, conversion logic, and tests.

Excel sub-sheet selection and listing enhancements:

• Added new CLI arguments in __main__.py to allow users to list available sheets (--list-sheets), specify sheets to convert (--sheet), or interactively select sheets (--interactive).
• Updated the call to markitdown.convert to pass the new arguments (list_sheets, sheet_selection, and interactive) from the CLI to the converter logic.

Conversion logic updates:

• Refactored both XLSX and XLS converters to:
  • Use pd.ExcelFile for improved sheet handling,
  • Print available sheets and exit if --list-sheets is used,
  • Prompt the user for sheet selection if --interactive is used,
  • Validate selected sheets and only convert those specified,
  • Handle both single and multiple sheet conversions robustly. [1] [2]

Testing updates:

• Updated tests to account for the new arguments passed to markitdown.convert, ensuring that the CLI wiring is correct.

Code cleanup:

• Removed an unused import from the test file.

[Copilot]

Pull request overview

This pull request adds Excel sub-sheet selection capabilities to markitdown, wiring new CLI options through to the Excel converters so users can list available sheets, select specific sheets, or choose sheets interactively.

Changes:

• Added CLI flags --list-sheets, --sheet (repeatable), and --interactive, and passed them through to MarkItDown.convert*().
• Refactored XLSX/XLS conversion to use pd.ExcelFile and support listing/selecting sheets.
• Updated CU CLI wiring test to assert the new kwargs are passed through.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
packages/markitdown/src/markitdown/main.py	Adds new CLI options and passes them into conversion calls.
packages/markitdown/src/markitdown/converters/_xlsx_converter.py	Implements sheet listing/selection/interactive sheet picking for XLSX and XLS.
packages/markitdown/tests/test_cu_converter.py	Updates test expectations for new conversion kwargs and removes unused import.

Suppressed comments (3)

packages/markitdown/src/markitdown/main.py:285

• --list-sheets currently relies on the Excel converter printing sheet names, but the CLI still calls _handle_output(args, result) afterwards. This adds an extra blank line to stdout and will create/overwrite an empty --output file, which is surprising for a “list and exit” mode. Consider short-circuiting output handling when --list-sheets is set.

    _handle_output(args, result)

packages/markitdown/src/markitdown/converters/_xlsx_converter.py:201

• Same as above: normalize sheet_selection when it is provided as a string to avoid iterating characters during validation and to ensure the single-DataFrame fallback uses the full sheet name as the dict key.

        # Handle --interactive
        sheet_selection = kwargs.get("sheet_selection") or []
        if kwargs.get("interactive"):

packages/markitdown/src/markitdown/converters/_xlsx_converter.py:227

• Same concern for .xls: sheet-selection validation exceptions may be swallowed by the conversion pipeline and a later converter may produce output anyway, despite the user explicitly selecting sheets. Making these errors fatal likely requires changes outside this file.

        for s in sheets_to_read:
            if s not in sheet_names:
                raise ValueError(f"Sheet not found: {s}")

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Utkarsh Verma (heyutkarshverma)]

Utkarsh Verma (Utkarsh Verma (@heyutkarshverma)) please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.

@microsoft-github-policy-service agree [company="{your company}"]

Options:

• (default - no company specified) I have sole ownership of intellectual property rights to my Submissions and I am not making Submissions in the course of work for my employer.

@microsoft-github-policy-service agree

• (when company given) I am making Submissions in the course of work for my employer (or my employer has intellectual property rights in my Submissions by contract or applicable law). I have permission from my employer to make Submissions and enter into this Agreement on behalf of my employer. By signing below, the defined term “You” includes me and my employer.

@microsoft-github-policy-service agree company="Microsoft"

Contributor License Agreement

@microsoft-github-policy-service agree