Files added to session are inserted alongside other files from the same context, ordered by position

Author: chris-adam

CHANGES.rst

@@ -29,6 +29,8 @@ Changelog
   [chris-adam]
 - Added external watchers for esign sessions.
   [chris-adam, sgeulette]
+- Files added to session are inserted alongside other files from the same context, ordered by position.
+  [chris-adam]
 
 1.0a2 (2026-02-06)
 ------------------

src/imio/esign/tests/test_utils.py

@@ -350,10 +350,10 @@ def test_create_external_session(self):
         files_param = call_args[1]["files"]
         self.assertEqual(len(files_param), 3)
         self.assertEqual(files_param[0][0], "files")
-        self.assertEqual(files_param[0][1][0], u"annex4.pdf")
+        self.assertEqual(files_param[0][1][0], u"annex1-1.pdf")
         self.assertEqual(files_param[1][0], "files")
-        self.assertEqual(files_param[1][1][0], u"annex1.pdf")
-        self.assertEqual(files_param[2][1][0], u"annex1-1.pdf")
+        self.assertEqual(files_param[1][1][0], u"annex4.pdf")
+        self.assertEqual(files_param[2][1][0], u"annex1.pdf")
 
         # Case 6: session without files to send => returns "_no_files_", no HTTP call
         for i in range(len(session3["files"])):
@@ -422,6 +422,41 @@ def test_session_size_discrimination(self):
         self.assertIs(session3, session2)
         self.assertEqual(session3["size"], 7014 + 6968)
 
+    def test_add_files_ordering_by_context(self):
+        """Files added to a session are ordered by their position within their context."""
+        def reset_annotation():
+            annot = get_session_annotation()
+            annot["sessions"].clear()
+            annot["uids"].clear()
+            annot["c_uids"].clear()
+            annot["numbering"] = 0
+
+        signers = [("user1", "user1@sign.com", "User 1", "Position 1")]
+
+        # Case 1: uid[0] then uid[1] (different context) then uid[2] (same context as uid[0])
+        # uid[2] must land immediately after uid[0], not after uid[1]
+        reset_annotation()
+        sid, session = add_files_to_session(signers, (self.uids[0],))
+        sid, session = add_files_to_session(signers, (self.uids[1],), session_id=sid)
+        sid, session = add_files_to_session(signers, (self.uids[2],), session_id=sid)
+        self.assertEqual([f["uid"] for f in session["files"]], [self.uids[0], self.uids[2], self.uids[1]])
+
+        # Case 2: uid[4] (3rd in folder0) added before uid[0] (1st in folder0)
+        # uid[0] must land before uid[4]
+        reset_annotation()
+        sid, session = add_files_to_session(signers, (self.uids[4],))
+        sid, session = add_files_to_session(signers, (self.uids[0],), session_id=sid)
+        self.assertEqual([f["uid"] for f in session["files"]], [self.uids[0], self.uids[4]])
+
+        # Case 3: uid[0], uid[4] in session, then uid[1] (different context), then uid[2]
+        # uid[2] must be inserted between uid[0] and uid[4]
+        reset_annotation()
+        sid, session = add_files_to_session(signers, (self.uids[0],))
+        sid, session = add_files_to_session(signers, (self.uids[4],), session_id=sid)
+        sid, session = add_files_to_session(signers, (self.uids[1],), session_id=sid)
+        sid, session = add_files_to_session(signers, (self.uids[2],), session_id=sid)
+        self.assertEqual([f["uid"] for f in session["files"]], [self.uids[0], self.uids[2], self.uids[4], self.uids[1]])
+
     def test_add_files_with_duplicate_filenames(self):
         """Test that files with duplicate filenames are renamed with suffix."""
         annot = get_session_annotation()

src/imio/esign/utils.py

@@ -85,19 +85,42 @@ def add_files_to_session(
         context_uid = context_uid_provider.get_context_uid()
         filename, ext = path.splitext(annex.file.filename or "no_filename.pdf")
         new_filename = get_correct_id(existing_files, filename)
-        session["files"].append(
-            {
-                "scan_id": annex.scan_id,
-                "filename": new_filename + ext,
-                "title": annex.title or "no_title",
-                "uid": uid,
-                "context_uid": context_uid,
-                "status": "",
-            }
-        )
+        file_dict = {
+            "scan_id": annex.scan_id,
+            "filename": new_filename + ext,
+            "title": annex.title or "no_title",
+            "uid": uid,
+            "context_uid": context_uid,
+            "status": "",
+        }
+        # Find the range of files already belonging to this context (if any)
+        context_start_idx, context_end_idx = None, None
+        for i, f in enumerate(session["files"]):
+            if f["context_uid"] == context_uid:
+                if context_start_idx is None:
+                    context_start_idx = i
+                context_end_idx = i
+            elif context_start_idx is not None:
+                break
+        if context_start_idx is None:
+            # No files from this context yet, append at end
+            session["files"].append(file_dict)
+        else:
+            # Insert alongside other files from the same context, ordered by position
+            context = uuidToObject(context_uid)
+            if context is not None:
+                uid_order = {a.UID(): idx for idx, a in enumerate(context.values())}
+            else:
+                uid_order = {}
+            files = session["files"][context_start_idx:context_end_idx + 1]
+            files.append(file_dict)
+            session["files"][context_start_idx:context_end_idx + 1] = sorted(
+                files, key=lambda f: uid_order.get(f["uid"], -1)
+            )
         existing_files.append(new_filename)
         annot["uids"][uid] = session_id
         annot["c_uids"].setdefault(context_uid, PersistentList()).append(uid)
+
     if session["client_id"] is None:
         # FIXME what if scan_id is None ?
         session["client_id"] = session["files"][0]["scan_id"][0:7]