tarfile: Cannot open TAR for both reading and writing

[spbnick]

Bug report

Bug description:

Presumably the "a" TarFile mode was implemented to support both reading and writing, e.g. as evidenced by this line in its __init__() method, if not exactly by its documentation:

        modes = {"r": "rb", "a": "r+b", "w": "wb", "x": "xb"}

However, when you try an extractfile() in this mode, you would get an OSError: bad operation for mode 'a' due to the use of self._check("r"). Other extraction functions seem to be doing the same. As such, there seems to be no way to open a TAR file for both reading and writing.

Reproducer

from io import BytesIO
from tarfile import TarFile, TarInfo

with TarFile("test.tar", mode="w") as tar:
    contents = b"CONTENTS1"
    tarinfo = TarInfo("file1.txt")
    tarinfo.size = len(contents)
    tar.addfile(tarinfo, BytesIO(contents))

with TarFile("test.tar", mode="r") as tar:
    tar.extractfile("file1.txt").read()

with TarFile("test.tar", mode="a") as tar:
    contents = b"CONTENTS2"
    tarinfo = TarInfo("file2.txt")
    tarinfo.size = len(contents)
    tar.addfile(tarinfo, BytesIO(contents))
    tar.extractfile("file1.txt").read()

Expecting no output from executing this, but getting:

Traceback (most recent call last):
  File "<python-input-0>", line 18, in <module>
    tar.extractfile("file1.txt").read()
    ~~~~~~~~~~~~~~~^^^^^^^^^^^^^
  File "/usr/local/lib/python3.15/tarfile.py", line 2580, in extractfile
    self._check("r")
    ~~~~~~~~~~~^^^^^
  File "/usr/local/lib/python3.15/tarfile.py", line 2969, in _check
    raise OSError("bad operation for mode %r" % self.mode)
OSError: bad operation for mode 'a'

CPython versions tested on:

3.15

Operating systems tested on:

Linux

[picnixz]

In the docs, a is for

Open for appending with no compression. The file is created if it does not exist.

So there is no notion of reading here AFAICT.

[spbnick]

Yes, there is no mention of reading in"a" mode, I'm hinting at that in the report. However, the "a" mode maps to "r+b" TAR file mode, which is not strictly necessary just for appending (OK, you gotta check for EOF block, but mostly not), implying wider intent. And even if so, there would still be no read-write mode available, which I would say is at least a pretty important feature, if not strictly-speaking a contradiction with documentation required for a bug.

[spbnick]

FWIW, I overrode the _check method to allow this, as a workaround, and it seems to be working (but proper testing is TBD).

[picnixz]

What I meant is that the correct meaning of "a" should be the documented one, not what you expect from the regular open() function.

[picnixz]

What you think is a bug is a deliberate design choice I think. Having a bidirectional mode does not seem common for archives though. If you want to support this feature you must build consensus on discuss.python.org first.

I am closing this until this is addressed as a community idea and that we agreed on having bidirectional mode. To me, it does not seem relevant (I fail to see a common use case)

[spbnick]

Agreed. Thank you for the quick and well-argued responses, @picnixz.