fix(python): add collection close method

python/tests/detail/test_collection_create_and_open.py

@@ -586,7 +586,7 @@ def open_collection_thread(thread_id):
                     path=str(collection_path), option=collection_option
                 )
                 with lock:
-                    results.append((thread_id, reopened_coll))
+                    results.append((thread_id, reopened_coll.path))
                 # Clean up the collection if opened successfully
                 if hasattr(reopened_coll, "close") and reopened_coll is not None:
                     reopened_coll.close()
@@ -616,11 +616,11 @@ def open_collection_thread(thread_id):
         )
 
         # Additional verification: check that the successful open has a valid collection
-        successful_thread_id, successful_collection = results[0]
-        assert successful_collection is not None, (
+        successful_thread_id, successful_collection_path = results[0]
+        assert successful_collection_path is not None, (
             "Successful open should return a valid collection"
         )
-        assert successful_collection.path == str(collection_path), (
+        assert successful_collection_path == str(collection_path), (
             "Collection path mismatch"
         )
 

python/tests/detail/test_collection_open.py

@@ -108,6 +108,72 @@ def test_collection(
 
 
 class TestCollectionOpen:
+    def test_close_releases_collection_for_reopen(
+        self, tmp_path_factory, collection_schema, collection_option
+    ):
+        temp_dir = tmp_path_factory.mktemp("zvec")
+        collection_path = temp_dir / "test_collection"
+        collection_path_str = str(collection_path)
+
+        created_coll = zvec.create_and_open(
+            path=collection_path_str, schema=collection_schema, option=collection_option
+        )
+
+        created_coll.close()
+
+        opened_coll = zvec.open(path=collection_path_str, option=collection_option)
+        assert opened_coll.path == collection_path_str
+        opened_coll.destroy()
+
+    def test_close_releases_collection_with_outstanding_reference(
+        self, tmp_path_factory, collection_schema, collection_option
+    ):
+        temp_dir = tmp_path_factory.mktemp("zvec")
+        collection_path = temp_dir / "test_collection"
+        collection_path_str = str(collection_path)
+
+        created_coll = zvec.create_and_open(
+            path=collection_path_str, schema=collection_schema, option=collection_option
+        )
+
+        # Keep an extra reference to the native handle, as a shallow copy or a
+        # stale reference would. close() must release the file lock anyway.
+        native_ref = created_coll._obj
+
+        created_coll.close()
+
+        # The path can be reopened even though native_ref is still alive.
+        opened_coll = zvec.open(path=collection_path_str, option=collection_option)
+        assert opened_coll.path == collection_path_str
+
+        # Operations through the stale handle fail cleanly instead of touching
+        # released native state.
+        with pytest.raises(ValueError, match="already closed"):
+            native_ref.Stats()
+
+        opened_coll.destroy()
+
+    def test_close_is_idempotent(
+        self, tmp_path_factory, collection_schema, collection_option
+    ):
+        temp_dir = tmp_path_factory.mktemp("zvec")
+        collection_path = temp_dir / "test_collection"
+        collection_path_str = str(collection_path)
+
+        created_coll = zvec.create_and_open(
+            path=collection_path_str, schema=collection_schema, option=collection_option
+        )
+
+        native_ref = created_coll._obj
+        created_coll.close()
+        created_coll.close()
+        # Closing the native handle again is also a no-op.
+        native_ref.Close()
+
+        opened_coll = zvec.open(path=collection_path_str, option=collection_option)
+        assert opened_coll.path == collection_path_str
+        opened_coll.destroy()
+
     def test_open_basic_functionality(
         self, tmp_path_factory, collection_schema, collection_option
     ):
@@ -818,8 +884,9 @@ def test_open_concurrent_same_path(self, tmp_path_factory):
         def open_collection_thread(thread_id):
             try:
                 coll = zvec.open(path=str(collection_path), option=collection_option)
+                collection_path_result = coll.path
                 with lock:
-                    results.append((thread_id, coll))
+                    results.append((thread_id, collection_path_result))
                 # Close the collection if opened successfully
                 if hasattr(coll, "close") and coll is not None:
                     coll.close()
@@ -847,23 +914,17 @@ def open_collection_thread(thread_id):
         )
 
         # Additional verification: check that the successful open has a valid collection
-        successful_thread_id, successful_collection = results[0]
-        assert successful_collection is not None, (
+        _, successful_collection_path = results[0]
+        assert successful_collection_path is not None, (
             "Successful open should return a valid collection"
         )
-        assert successful_collection.path == str(collection_path), (
+        assert successful_collection_path == str(collection_path), (
             "Collection path mismatch"
         )
 
-        # Clean up the successfully opened collection
-        if (
-            hasattr(successful_collection, "destroy")
-            and successful_collection is not None
-        ):
-            try:
-                successful_collection.destroy()
-            except Exception as e:
-                print(f"Warning: failed to destroy collection: {e}")
+        # Clean up after the successful worker released its collection handle.
+        cleanup_coll = zvec.open(path=str(collection_path), option=collection_option)
+        cleanup_coll.destroy()
 
     def test_open_with_corrupted_files(self, tmp_path_factory):
         # First create a collection

python/zvec/__init__.pyi

@@ -117,6 +117,7 @@ class _Collection:
         arg2: schema._FieldSchema,
         arg3: param.AlterColumnOption,
     ) -> None: ...
+    def Close(self) -> None: ...
     def CreateIndex(
         self, arg0: str, arg1: param.IndexParam, arg2: param.IndexOption
     ) -> None: ...

python/zvec/model/collection.py

@@ -56,6 +56,20 @@ def __init__(self, obj: _Collection):
         self._schema = None
         self._querier = None
 
+    def close(self) -> None:
+        """Close the collection and release its native resources.
+
+        Flushes pending writes and releases the collection's file lock so the
+        path can be reopened or removed, even if other references to this
+        collection still exist. Closing an already-closed collection is a
+        no-op.
+        """
+        if self._obj is not None:
+            self._obj.Close()
+        self._obj = None
+        self._schema = None
+        self._querier = None
+
     @classmethod
     def _from_core(cls, core_collection: _Collection) -> Collection:
         if not core_collection:

src/binding/python/model/python_collection.cc

@@ -118,15 +118,24 @@ void ZVecPyCollection::bind_ddl_methods(
       });
 
   // bind collection ddl methods
-  col.def("Destroy",
+  col.def("Close",
           [](Collection &self) {
             Status status;
             {
               py::gil_scoped_release release;
-              status = self.Destroy();
+              status = self.Close();
             }
             throw_if_error(status);
           })
+      .def("Destroy",
+           [](Collection &self) {
+             Status status;
+             {
+               py::gil_scoped_release release;
+               status = self.Destroy();
+             }
+             throw_if_error(status);
+           })
       .def("Flush", [](Collection &self) {
         Status status;
         {