File format dispatch and handler routing

file-format-dispatch-and-handler-routing

Summary

Route file I/O operations to format-specific handler classes by detecting file extension or metadata in a central FileInterface dispatcher. This skill enables a parser library to support multiple data formats (mzML, .db, indexed gzip) without duplicating parsing logic, by instantiating the appropriate connector class at open time.

When to use

You have a parser library that must support multiple file formats (e.g., mzML, SQLite, compressed gzip) and want to avoid conditional logic scattered throughout the parsing code. Use this skill when you need to detect file type at I/O time and route to a custom handler class that implements a standard interface (getitem, read, get_count methods).

When NOT to use

• File format is already determined and a single handler is sufficient — skip dispatch overhead and instantiate directly.
• Parser receives a file handle (already open) rather than a path — dispatch typically occurs at the path/filename stage.
• All supported formats share identical binary structure — use a single polymorphic handler with format-aware logic instead of routing.

Inputs

• file path or URI (string)
• file extension or metadata indicating storage format
• optional: file size or header bytes for format detection

Outputs

• file handler instance (custom class inheriting FileInterface or implementing getitem and read)
• Spectrum or Chromatogram objects (via handler's getitem and read methods)

How to apply

In the central FileInterface._open() method, add a chain of elif statements that detect file extension or path properties (e.g., path.endswith('.db'), path.endswith('.mzML.gz')). For each format, instantiate the appropriate custom handler class (e.g., SQLiteDatabase, IndexedGzipReader) that implements the required read() and getitem() methods. Assign the instantiated handler to file_handler and return it to the caller. Each handler class must parse its format into the same output type (Spectrum or Chromatogram objects) so the downstream Reader sees a unified interface regardless of the storage format.

Related tools

• pymzML (Parser library providing FileInterface base class and Reader; route file handlers through FileInterface._open() to enable format-agnostic spectrum access) — https://github.com/pymzml/pymzML
• sqlite3 (Query and retrieve spectrum XML elements from .db files in the SQLiteDatabase handler's getitem implementation)
• ElementTree (Parse XML string elements retrieved from database or gzip into Spectrum objects via pymzML's spec module)
• black (Code formatter applied to handler implementations to ensure consistent style across format-specific classes) — https://github.com/psf/black

Examples

from pymzml import Reader; reader = Reader('spectra.db'); spectrum = reader[0]; print(spectrum.mz, spectrum.intensity)

Evaluation signals

• FileInterface._open() correctly detects file extension and instantiates the appropriate handler class without raising KeyError or AttributeError.
• Handler.getitem(key) returns valid Spectrum or Chromatogram objects for integer or string keys; verify object type and that required fields (mz, intensity, ID) are populated.
• Handler.read() yields sequential spectrum XML strings or parsed objects; verify iteration count matches get_spectrum_count().
• Round-trip test: open a .db file via FileInterface, iterate over spectra via Reader, and confirm spectrum IDs and m/z arrays match the original mzML source.
• No performance regression: dispatch overhead (extension check, handler instantiation) is <1% of total parse time for typical mzML files.

Limitations

• File extension detection is brittle if files lack standard extensions (e.g., renamed .mzML.gz to .gz); consider adding magic-byte detection as a fallback.
• Each new format requires a custom handler class implementing getitem and read; no automatic schema inference — handler logic is format-specific and must be written by hand.
• Handler must produce identical output types (Spectrum, Chromatogram) to maintain Reader compatibility; if a format stores fundamentally different metadata (e.g., only precursor m/z, no fragments), mapping to standard Spectrum may lose information.
• Sequential read() via iteration does not support random-access seeking in all formats; indexed gzip and SQLite support getitem random access, but naive text parsers may need refactoring to enable both access patterns.

Evidence

• [other] dispatch_via_extension: "Add an elif clause to FileInterface._open() that detects '.db' file extensions and instantiates SQLiteDatabase, routing the file_handler assignment to the new connector class."
• [other] handler_interface_contract: "Implement a class, which needs to implement the getitem function for random access, and a read function used to sequentially read in data for iterating the database."
• [other] unified_output_type: "getitem(key) to execute SQL queries and return Spectrum or Chromatogram objects parsed from XML elements"
• [intro] extensibility_rationale: "In order to make pymzML accept other kinds of mzML data (e.g databases), one can implement an own wrapper"
• [intro] multiple_format_support: "Module to parse mzML data in Python based on cElementTree... ability to write and read indexed gzip files"