gh-115256: Remove refcycles from tarfile writing (GH-115257)

3 files changed, 28 insertions, 2 deletions

diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index d08c63e..96c8aee 100644
--- a/Doc/whatsnew/3.13.rst
+++ b/Doc/whatsnew/3.13.rst
@@ -791,6 +791,9 @@ Deprecated
   coroutine.
   (Contributed by Irit Katriel in :gh:`81137`.)
 
+* The undocumented and unused ``tarfile`` attribute of :class:`tarfile.TarFile`
+  is deprecated and scheduled for removal in Python 3.16.
+
 
 Pending Removal in Python 3.14
 ------------------------------
diff --git a/Lib/tarfile.py b/Lib/tarfile.py
index f4dd0fd..6f315a6 100755
--- a/Lib/tarfile.py
+++ b/Lib/tarfile.py
@@ -872,7 +872,7 @@ class TarInfo(object):
         pax_headers = ('A dictionary containing key-value pairs of an '
                        'associated pax extended header.'),
         sparse = 'Sparse member information.',
-        tarfile = None,
+        _tarfile = None,
         _sparse_structs = None,
         _link_target = None,
         )
@@ -902,6 +902,24 @@ class TarInfo(object):
         self.pax_headers = {}   # pax header information
 
     @property
+    def tarfile(self):
+        import warnings
+        warnings.warn(
+            'The undocumented "tarfile" attribute of TarInfo objects '
+            + 'is deprecated and will be removed in Python 3.16',
+            DeprecationWarning, stacklevel=2)
+        return self._tarfile
+
+    @tarfile.setter
+    def tarfile(self, tarfile):
+        import warnings
+        warnings.warn(
+            'The undocumented "tarfile" attribute of TarInfo objects '
+            + 'is deprecated and will be removed in Python 3.16',
+            DeprecationWarning, stacklevel=2)
+        self._tarfile = tarfile
+
+    @property
     def path(self):
         'In pax headers, "name" is called "path".'
         return self.name
@@ -2030,7 +2048,7 @@ class TarFile(object):
         # Now, fill the TarInfo object with
         # information specific for the file.
         tarinfo = self.tarinfo()
-        tarinfo.tarfile = self  # Not needed
+        tarinfo._tarfile = self  # To be removed in 3.16.
 
         # Use os.stat or os.lstat, depending on if symlinks shall be resolved.
         if fileobj is None:
diff --git a/Misc/NEWS.d/next/Library/2024-02-10-17-18-49.gh-issue-115256.41Fy9P.rst b/Misc/NEWS.d/next/Library/2024-02-10-17-18-49.gh-issue-115256.41Fy9P.rst
new file mode 100644
index 0000000..8cde053
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2024-02-10-17-18-49.gh-issue-115256.41Fy9P.rst
@@ -0,0 +1,5 @@
+Added DeprecationWarning when accessing the tarfile attribute of TarInfo
+objects. The attribute is never used internally and is only attached to
+TarInfos when the tarfile is opened in write-mode, not read-mode. The
+attribute creates an unnecessary reference cycle which may cause
+corruption when not closing the handle after writing a tarfile.