Python bracket notation protocol implementation

Python Bracket Notation Protocol Implementation

Summary

Implement the __getitem__() protocol in a custom Python class to enable random access to indexed data blocks (e.g., chapters in a compressed mzML file) using bracket notation. This allows seekable access to blockwise-indexed content without decompressing the entire file.

When to use

You have a blockwise-indexed compressed file (e.g., indexed gzip with chapter or spectrum identifiers) and need to retrieve individual logical blocks by key using Python bracket notation (e.g., handler['chapter_1'] or handler[0]) rather than sequential iteration. The data must already be partitioned into discrete, addressable units with corresponding index entries.

When NOT to use

• Data is stored in a sequential (non-indexed) format — use sequential read() instead.
• The index is not available or malformed — implement index reconstruction or fall back to linear scan.
• Access patterns are purely sequential — overhead of bracket-notation lookup may not justify the implementation.

Inputs

• indexed gzip file (.gz with internal or sidecar index)
• blockwise-indexed data (e.g., mzML with chapter or spectrum identifiers)
• integer or string key mapping (e.g., chapter names, spectrum IDs)

Outputs

• custom wrapper class implementing getitem() protocol
• retrieved data block (e.g., XML element string or binary chunk)
• random-access handler suitable for integration into FileInterface

How to apply

Define a custom wrapper class that implements the __getitem__(self, key) method to accept either integer or string identifiers and return the corresponding data block from the indexed file. The class must maintain an internal index mapping keys to byte offsets within the compressed file, using a GSGR (Generalized Seekable Gzip Reader) or similar seek-capable reader to retrieve the block at the correct file position. Populate the index during initialization by parsing the index structure embedded in or accompanying the compressed file. Test random access by calling the handler with bracket notation and verify that each key returns the correct block without iterating through preceding blocks.

Related tools

• pymzML (FileInterface host for custom handler; provides GSGR/GSGW classes and Spectrum/Run parsing infrastructure) — https://github.com/pymzml/pymzML
• Python (Language for implementing getitem() protocol and wrapper class)
• ElementTree (XML parsing of mzML spectrum and run elements retrieved via bracket notation)

Examples

class MzMLHandler:
    def __init__(self, filename):
        self.reader = gzip.open(filename)
        self.index = self._load_index()
    def __getitem__(self, key):
        offset = self.index[key]
        self.reader.seek(offset)
        return self.reader.read()

handler = MzMLHandler('file.mzML.gz')
spectrum = handler['scan=1234']

Evaluation signals

• Random access via bracket notation returns correct block for each key without sequential iteration (time complexity ≤ O(1) per access after index load).
• Sequential iteration via read() function traverses all blocks without data loss or corruption.
• Index mapping is consistent: all keys present in the compressed file are correctly addressable; no orphaned or duplicate entries.
• Retrieved XML or binary data matches expected schema (e.g., valid mzML spectrum elements with correct scan number or chapter boundary).
• Handler integrates into pymzML FileInterface via elif statement in _open() and transparently replaces native file access for detected file types.

Limitations

• Requires pre-existing index embedded in or alongside the compressed file; no dynamic re-indexing of non-indexed gzip files.
• Performance depends on index lookup speed and seek latency; large indices may cause initial overhead.
• String keys require case-sensitive or normalized matching; inconsistent key format may lead to KeyError.
• Handler must be registered in FileInterface._open() for automatic detection; manual instantiation required otherwise.

Evidence

• [intro] access the chapters conveniently by the python bracket notation ([]): "access the chapters conveniently by the python bracket notation ([])"
• [intro] a new class needs to be written, which implements a read and a __getitem__ function: "a new class needs to be written, which implements a read and a __getitem__ function"
• [other] we need to implement a class, which needs to implement the getitem function for random access: "we need to implement a class, which needs to implement the getitem function for random access"
• [intro] parse the data blockwise, so every piece of data, which should be accessible by indexing is written in one go: "parse the data blockwise, so every piece of data, which should be accessible by indexing is written in one go"
• [other] the filehandler needs to be able to detect when to use this class. The easiest way is, to add another elif statement: "the filehandler needs to be able to detect when to use this class. The easiest way is, to add another elif statement"