Better doc string for generate hash method

src/olympia/blocklist/mlbf.py

@@ -246,22 +246,32 @@ def generate_and_write_stash(self, previous_mlbf: 'MLBF' = None):
         """
         Generate and write the stash file representing
         changes between the previous and current MLBF Filters.
+
         In order to support older FX clients that only understood blocked and unblocked
-        The unblocked list is a union of deletions from blocked and soft_blocked.
+        unblocked is a union of deletions from blocked and additions to soft_blocked.
+
+        Versions that move from hard to soft blocked will be picked up by old clients
+        as no longer hard blocked by being in the unblocked list.
 
-        Items that have moved from hard to soft blocked are then interpreted as
-        unblocked from the hard blocked list in newer and older clients.
+        Newer clients will also see soft blocked items as unblocked
+        but then will check the soft blocked list and re-add them to soft blocked.
 
-        Newer clients will then see that the item is softblocked
-        and will apply the softblocked filter.
+        Versions that move from soft to hard blocked will be picked up by old clients
+        and new clients in the blocked list. However, we prevent these versions from
+        also being in the unblocked list as this would produce a contradiction
+        since unblocked is shared by hard and soft blocked filters.
         """
         diffs = self.generate_diffs(previous_mlbf)
         blocked_added, blocked_removed, _ = diffs[BlockType.BLOCKED]
         soft_blocked_added, soft_blocked_removed, _ = diffs[BlockType.SOFT_BLOCKED]
         stash_json = {
             'blocked': blocked_added,
             'softblocked': soft_blocked_added,
-            'unblocked': blocked_removed | soft_blocked_removed - blocked_added,
+            'unblocked': [
+                unblocked
+                for unblocked in (blocked_removed + soft_blocked_removed)
+                if unblocked not in blocked_added
+            ],
         }
         # write stash
         stash_path = self.stash_path

src/olympia/blocklist/tests/test_mlbf.py

@@ -525,8 +525,8 @@ def test_diff_all_possible_changes(self):
         first_mlbf = MLBF.generate_from_db('first')
 
         assert first_mlbf.generate_diffs() == {
-            BlockType.BLOCKED: (set([five_hash, six_hash]), set(), 2),
-            BlockType.SOFT_BLOCKED: (set([three_hash, four_hash]), set(), 2),
+            BlockType.BLOCKED: ([five_hash, six_hash], [], 2),
+            BlockType.SOFT_BLOCKED: ([three_hash, four_hash], [], 2),
         }
         assert first_mlbf.generate_and_write_stash() == {
             'blocked': [five_hash, six_hash],
@@ -546,23 +546,27 @@ def test_diff_all_possible_changes(self):
 
         second_mlbf = MLBF.generate_from_db('second')
 
+        # The order is based on the ID (i.e. creation time) of the block,
+        # not the version so we expect two after three
+        # since two was blocked after three
         assert second_mlbf.generate_diffs(previous_mlbf=first_mlbf) == {
             BlockType.BLOCKED: (
-                set([two_hash, three_hash]),
-                set([five_hash, six_hash]),
+                [three_hash, two_hash],
+                [five_hash, six_hash],
                 4,
             ),
+            # Same as above, one had a block created after five so it comes second
             BlockType.SOFT_BLOCKED: (
-                set([one_hash, five_hash]),
-                set([three_hash, four_hash]),
+                [five_hash, one_hash],
+                [three_hash, four_hash],
                 4,
             ),
         }
 
         assert second_mlbf.generate_and_write_stash(previous_mlbf=first_mlbf) == {
-            'blocked': [two_hash, three_hash],
-            'softblocked': [one_hash, five_hash],
-            'unblocked': [four_hash, five_hash, six_hash],
+            'blocked': [three_hash, two_hash],
+            'softblocked': [five_hash, one_hash],
+            'unblocked': [five_hash, six_hash, four_hash],
         }
 
     def test_generate_stash_returns_expected_stash(self):