`qpy.dump` fails with gzip files in QPY v16 due to unsupported backward seek

[Siddharthgolecha]

Environment

• Qiskit version: 2.2
• Python version: 2.2.0 (QPY 16)
• Operating system: Any (Linux/macOS/Windows)

What is happening?

In QPY version 16 (Qiskit ≥ 2.2.0), qpy.dump() introduces a circuit offset table that requires seeking back to fill offsets after writing the circuit data. This causes an OSError: Negative seek in write mode when the output stream is a gzip.GzipFile opened in write mode, because gzip only supports forward seeks.

This is probably caused by #14953 .

How can we reproduce the issue?

import gzip
from qiskit import QuantumCircuit, qpy

qc = QuantumCircuit(2)
qc.h(0); qc.h(1)

with gzip.open("circuit.qpy.gz", "wb") as f:
    qpy.dump(qc, f)

Error:
OSError: Negative seek in write mode

The qpy.dump() checks only file_obj.seekable() to decide whether to use the “fast path” that performs in-place offset table writing. However, gzip.GzipFile reports seekable() == True yet does not support backward seeks, triggering the exception.

What should happen?

qpy.dump() should successfully write QPY v16 data to any binary writable file-like object, including compressed streams like gzip.GzipFile, without requiring random-access seeking.

Specifically:

• The function should automatically detect when a stream cannot perform backward seeks (e.g., gzip write mode) and transparently fall back to a buffered approach.

• Users should be able to do:

  import gzip
  from qiskit import QuantumCircuit, qpy
  
  qc = QuantumCircuit(2)
  qc.h(0)
  qc.h(1)
  
  with gzip.open("circuit.qpy.gz", "wb") as f:
      qpy.dump(qc, f)

  …and expect it to complete without error and produce a valid .qpy.gz file readable by:

  with gzip.open("circuit.qpy.gz", "rb") as f:
      qpy.load(f)

In short, QPY serialization should be stream-agnostic, working seamlessly with both seekable files (e.g., disk files) and non-seekable or partially seekable streams (e.g., gzip, sockets, pipes).

Any suggestions?

I added a small runtime probe to detect if the stream truly supports backward seeks. If not, fall back to the buffered write path (BytesIO) used for non-seekable streams.

[jakelishman]

imo this is a clear bug in the Python standard-library implementation of Gzip. A stream should not be reporting that it supports random access if it does not actually support random access. I assume it supports forwards seeks, and this is the motivation for inclusion, but imo this breaks the interface since negative seeks are a first-class part of seeking.

I don't want to add a "trial balloon" seek into the code and penalise all users of QPY for one badly behaved object (if nothing else, IO errors can appear at any time even if it worked once), but given this is a standard-library object, I think it would be acceptable to have a single runtime-type check against it, or to have a kwarg that allows users to force the seeking behaviour to on or off regardless of what the stream reports.

[Siddharthgolecha]

Hey @jakelishman , I agree that this originates from gzip.GzipFile incorrectly reporting seekable() == True despite not supporting full random access. I implemented a probe as a pragmatic safeguard to prevent regressions for users writing qpy to gzip or other non-seekable streams, but I understand the concern about adding runtime I/O overhead for all cases. I’m happy to adjust the approach based on your preference, a direct type check for gzip file type or a kwarg would both work fine.

This issue was reported by one of our clients, so it would be great if we could prioritise a fix for it soon. Thanks a lot btw!!

[jakelishman]

I'm happy enough to set principles aside in favour of pragmatics because GzipFile is a standard-library object, and some very cursory searching of the CPython repo suggests that the Python project are treating trouble with GzipFile.seek as "wontfix" because there are existing valid use cases (see python/cpython#77354 (comment)). If it had been a third-party library, I'd have been more prepared to say "this is a bug - get upstream to fix it", but even if we said that here, the minimum lead time on getting it all supported Python versions for Qiskit is on the order of years.

If you can pivot #15158 to do some sort of if stream.seekable and not isinstance(stream, KNOWN_BAD_SEEKERS) check (or something like that), we can backport to 2.2.2.

If it would be useful to clients, as a separate PR (because it's not eligible for backport), we could add a use_seeking: bool | None = None kwarg to qpy.dump, where None means "defer to seekable and the blocklist" and a bool overrides to that value entirely. That would be eligible for release in 2.3.

[Siddharthgolecha]

I did the change in #15158 just like you requested and I'll open another PR for the kwarg.

[Siddharthgolecha]

I also added the PR #15161 for Qiskit 2.3's release.