building: add deprecation warning to TOC class

And ignore it in the TOC class unit tests.

PyInstaller/building/datastruct.py

@@ -11,6 +11,7 @@
 
 import os
 import pathlib
+import warnings
 
 from PyInstaller import log as logging
 from PyInstaller.building.utils import _check_guts_eq
@@ -38,8 +39,9 @@ def unique_name(entry):
     return name
 
 
+# This class is deprecated and has been replaced by plain lists with explicit normalization (de-duplication) via
+# `normalize_toc` and `normalize_pyz_toc` helper functions.
 class TOC(list):
-    # TODO: simplify the representation and use directly Modulegraph objects.
     """
     TOC (Table of Contents) class is a list of tuples of the form (name, path, typecode).
 
@@ -59,6 +61,14 @@ class TOC(list):
     """
     def __init__(self, initlist=None):
         super().__init__()
+
+        # Deprecation warning
+        warnings.warn(
+            "TOC class is deprecated. Use a plain list of 3-element tuples instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
         self.filenames = set()
         if initlist:
             for entry in initlist:

news/7615.deprecation.rst

@@ -0,0 +1,5 @@
+The ``TOC`` class is now deprecated; use a plain ``list`` with the same
+three-element tuples instead. PyInstaller now performs explicit
+normalization (i.e., entry de-duplication) of the TOC lists passed
+to the build targets (e.g., ``PYZ``, ``EXE``, ``COLLECT``) during their
+instantiation.

tests/unit/test_TOC.py

@@ -29,18 +29,24 @@
 
 ELEMS3 = (('PIL.Image.py', '/usr/lib/python2.7/encodings/__init__.py', 'PYMODULE'),)
 
+# Ignore deprecation warnings for the TOC class
+ignore_deprecation = pytest.mark.filterwarnings("ignore:TOC class is deprecated.")
 
+
+@ignore_deprecation
 def test_init_empty():
     toc = TOC()
     assert len(toc) == 0
 
 
+@ignore_deprecation
 def test_init():
     toc = TOC(ELEMS1)
     assert len(toc) == 3
     assert toc == list(ELEMS1)
 
 
+@ignore_deprecation
 def test_append():
     toc = TOC(ELEMS1)
     toc.append(('li-la-lu', '/home/myself/li-la-su', 'SOMETHING'))
@@ -49,13 +55,15 @@ def test_append():
     assert toc == expected
 
 
+@ignore_deprecation
 def test_append_existing():
     toc = TOC(ELEMS1)
     toc.append(ELEMS1[-1])
     expected = list(ELEMS1)
     assert toc == expected
 
 
+@ignore_deprecation
 def test_append_keep_filename():
     # name in TOC should be the same as the one added
     toc = TOC()
@@ -64,6 +72,7 @@ def test_append_keep_filename():
     assert toc[0][0] == entry[0]
 
 
+@ignore_deprecation
 def test_insert():
     toc = TOC(ELEMS1)
     toc.insert(1, ('li-la-lu', '/home/myself/li-la-su', 'SOMETHING'))
@@ -72,6 +81,7 @@ def test_insert():
     assert toc == expected
 
 
+@ignore_deprecation
 def test_insert_existing():
     toc = TOC(ELEMS1)
     toc.insert(0, ELEMS1[-1])
@@ -80,6 +90,7 @@ def test_insert_existing():
     assert toc == expected
 
 
+@ignore_deprecation
 def test_insert_keep_filename():
     # name in TOC should be the same as the one added
     toc = TOC()
@@ -88,6 +99,7 @@ def test_insert_keep_filename():
     assert toc[0][0] == entry[0]
 
 
+@ignore_deprecation
 def test_extend():
     toc = TOC(ELEMS1)
     toc.extend(ELEMS2)
@@ -96,13 +108,15 @@ def test_extend():
     assert toc == expected
 
 
+@ignore_deprecation
 def test_extend_existing():
     toc = TOC(ELEMS1)
     toc.extend(ELEMS1)
     expected = list(ELEMS1)
     assert toc == expected
 
 
+@ignore_deprecation
 def test_add_list():
     toc = TOC(ELEMS1)
     other = list(ELEMS2)
@@ -114,6 +128,7 @@ def test_add_list():
     assert result == expected
 
 
+@ignore_deprecation
 def test_add_tuple():
     toc = TOC(ELEMS1)
     other = ELEMS2
@@ -125,6 +140,7 @@ def test_add_tuple():
     assert result == expected
 
 
+@ignore_deprecation
 def test_add_toc():
     toc = TOC(ELEMS1)
     other = TOC(ELEMS2)
@@ -136,6 +152,7 @@ def test_add_toc():
     assert result == expected
 
 
+@ignore_deprecation
 def test_radd_list():
     toc = TOC(ELEMS1)
     other = list(ELEMS2)
@@ -147,6 +164,7 @@ def test_radd_list():
     assert result == expected
 
 
+@ignore_deprecation
 def test_radd_tuple():
     toc = TOC(ELEMS1)
     other = ELEMS2
@@ -158,6 +176,7 @@ def test_radd_tuple():
     assert result == expected
 
 
+@ignore_deprecation
 def test_radd_toc():
     toc = TOC(ELEMS1)
     other = TOC(ELEMS2)
@@ -169,6 +188,7 @@ def test_radd_toc():
     assert result == expected
 
 
+@ignore_deprecation
 def test_sub_list():
     toc = TOC(ELEMS1) + ELEMS2
     other = list(ELEMS2)
@@ -180,6 +200,7 @@ def test_sub_list():
     assert result == expected
 
 
+@ignore_deprecation
 def test_sub_tuple():
     toc = TOC(ELEMS1) + ELEMS2
     other = ELEMS2
@@ -191,6 +212,7 @@ def test_sub_tuple():
     assert result == expected
 
 
+@ignore_deprecation
 def test_sub_toc():
     toc = TOC(ELEMS1) + ELEMS2
     other = TOC(ELEMS2)
@@ -202,6 +224,7 @@ def test_sub_toc():
     assert result == expected
 
 
+@ignore_deprecation
 def test_sub_non_existing():
     toc = TOC(ELEMS1)
     other = ELEMS3
@@ -213,6 +236,7 @@ def test_sub_non_existing():
     assert result == expected
 
 
+@ignore_deprecation
 def test_rsub_list():
     toc = TOC(ELEMS1)
     other = list(ELEMS1) + list(ELEMS2)
@@ -224,6 +248,7 @@ def test_rsub_list():
     assert result == expected
 
 
+@ignore_deprecation
 def test_rsub_tuple():
     toc = TOC(ELEMS1)
     other = tuple(list(ELEMS1) + list(ELEMS2))
@@ -235,6 +260,7 @@ def test_rsub_tuple():
     assert result == expected
 
 
+@ignore_deprecation
 def test_rsub_toc():
     toc = TOC(ELEMS1)
     other = TOC(ELEMS1) + ELEMS2
@@ -246,6 +272,7 @@ def test_rsub_toc():
     assert result == expected
 
 
+@ignore_deprecation
 def test_rsub_non_existing():
     toc = TOC(ELEMS3)
     other = ELEMS1
@@ -257,13 +284,15 @@ def test_rsub_non_existing():
     assert result == expected
 
 
+@ignore_deprecation
 def test_sub_after_setitem():
     toc = TOC(ELEMS1)
     toc[1] = ('lib-dynload/_random', '/usr/lib/python2.7/lib-dynload/_random.so', 'EXTENSION')
     toc -= []
     assert len(toc) == 3
 
 
+@ignore_deprecation
 def test_sub_after_sub():
     toc = TOC(ELEMS1)
     toc -= [ELEMS1[0]]
@@ -272,6 +301,7 @@ def test_sub_after_sub():
     assert toc == expected
 
 
+@ignore_deprecation
 def test_setitem_1():
     toc = TOC()
     toc[:] = ELEMS1
@@ -280,6 +310,7 @@ def test_setitem_1():
         assert e[0] in toc.filenames
 
 
+@ignore_deprecation
 def test_setitem_2():
     toc = TOC(ELEMS1)
     toc[1] = ELEMS3[0]
@@ -302,6 +333,7 @@ def test_setitem_2():
 
 
 @pytest.mark.win32
+@ignore_deprecation
 def test_append_other_case_mixed():
     # If a binary file is added with the same filename as an existing pymodule, it should not be added.
     toc = TOC(ELEMS1)
@@ -312,6 +344,7 @@ def test_append_other_case_mixed():
 
 
 @pytest.mark.win32
+@ignore_deprecation
 def test_append_other_case_pymodule():
     # Python modules should not use C-I comparisons. Both 'encodings' and 'EnCodIngs' should be added.
     toc = TOC(ELEMS1)
@@ -323,6 +356,7 @@ def test_append_other_case_pymodule():
 
 
 @pytest.mark.win32
+@ignore_deprecation
 def test_append_other_case_binary():
     # Binary files should use C-I comparisons. 'LiBrEADlInE.so.6' should not be added.
     toc = TOC(ELEMS1)
@@ -332,6 +366,7 @@ def test_append_other_case_binary():
 
 
 @pytest.mark.win32
+@ignore_deprecation
 def test_insert_other_case_mixed():
     # If a binary file is added with the same filename as an existing pymodule, it should not be added.
     toc = TOC(ELEMS1)
@@ -342,6 +377,7 @@ def test_insert_other_case_mixed():
 
 
 @pytest.mark.win32
+@ignore_deprecation
 def test_insert_other_case_pymodule():
     # Python modules should not use C-I comparisons. Both 'encodings' and 'EnCodIngs' should be added.
     toc = TOC(ELEMS1)
@@ -353,6 +389,7 @@ def test_insert_other_case_pymodule():
 
 
 @pytest.mark.win32
+@ignore_deprecation
 def test_insert_other_case_binary():
     # Binary files should use C-I comparisons. 'LiBrEADlInE.so.6' should not be added.
     toc = TOC(ELEMS1)