feat(reuse): do not change contract of stop method

Author: matthiasschaub

core/testcontainers/core/container.py

@@ -151,10 +151,7 @@ def _start(self, hash_):
 
     def stop(self, force=True, delete_volume=True) -> None:
         if self._container:
-            if self._reuse and c.tc_properties_testcontainers_reuse_enable:
-                self._container.stop()
-            else:
-                self._container.remove(force=force, v=delete_volume)
+            self._container.remove(force=force, v=delete_volume)
         self.get_docker_client().client.close()
 
     def __enter__(self) -> Self:

core/tests/test_reusable_containers.py

@@ -36,9 +36,9 @@ def test_docker_container_with_reuse_reuse_enabled_ryuk_enabled(monkeypatch):
     monkeypatch.setattr(testcontainers_config, "tc_properties", tc_properties_mock)
     monkeypatch.setattr(testcontainers_config, "ryuk_reconnection_timeout", "0.1s")
 
-    with DockerContainer("hello-world").with_reuse() as container:
-        id = container._container.id
-        wait_for_logs(container, "Hello from Docker!")
+    container = DockerContainer("hello-world").with_reuse().start()
+    id = container._container.id
+    wait_for_logs(container, "Hello from Docker!")
 
     Reaper._socket.close()
     # Sleep until Ryuk reaps all dangling containers
@@ -59,15 +59,15 @@ def test_docker_container_with_reuse_reuse_enabled_ryuk_disabled(monkeypatch):
     monkeypatch.setattr(testcontainers_config, "tc_properties", tc_properties_mock)
     monkeypatch.setattr(testcontainers_config, "ryuk_disabled", True)
 
-    with DockerContainer("hello-world").with_reuse() as container:
-        id = container._container.id
-        wait_for_logs(container, "Hello from Docker!")
+    container = DockerContainer("hello-world").with_reuse().start()
+    id = container._container.id
+    wait_for_logs(container, "Hello from Docker!")
 
     containers = DockerClient().client.containers.list(all=True)
     assert id in [container.id for container in containers]
 
     # Cleanup after keeping container alive (with_reuse)
-    container._container.remove(force=True)
+    container.stop()
 
 
 def test_docker_container_with_reuse_reuse_enabled_ryuk_disabled_same_id(monkeypatch):
@@ -78,13 +78,15 @@ def test_docker_container_with_reuse_reuse_enabled_ryuk_disabled_same_id(monkeyp
     monkeypatch.setattr(testcontainers_config, "tc_properties", tc_properties_mock)
     monkeypatch.setattr(testcontainers_config, "ryuk_disabled", True)
 
-    with DockerContainer("hello-world").with_reuse() as container:
-        id = container._container.id
-    with DockerContainer("hello-world").with_reuse() as container:
-        assert id == container._container.id
+    container_1 = DockerContainer("hello-world").with_reuse().start()
+    id_1 = container_1._container.id
+    container_2 = DockerContainer("hello-world").with_reuse().start()
+    id_2 = container_2._container.id
+    assert id_1 == id_2
 
     # Cleanup after keeping container alive (with_reuse)
-    container._container.remove(force=True)
+    container_1.stop()
+    # container_2.stop() is not needed since it is the same as container_1
 
 
 def test_docker_container_labels_hash():

index.rst

@@ -120,9 +120,13 @@ Fetching passwords from cloud providers:
 Reusable Containers (Experimental)
 ----------------------------------
 
-Containers can be reused across consecutive test runs. To reuse a container, the container configuration must be the same.
+.. warning::
+    Reusable Containers is still an experimental feature and the behavior can change.
+    Those containers won't stop after all tests are finished.
 
-Containers that are set up for reuse will not be automatically removed. Thus, those containers need to be removed manually.
+Containers can be reused across consecutive test runs. To reuse a container, the container has to be started manually by calling the `start()` method. Do not call the `stop()` method directly or indirectly via a `with` statement (context manager). To reuse a container, the container configuration must be the same.
+
+Containers that are set up for reuse will not be automatically removed. Thus, if they are not needed anymore, those containers must be removed manually.
 
 Containers should not be reused in a CI environment.
 
@@ -131,16 +135,16 @@ How to use?
 
 1. Add :code:`testcontainers.reuse.enable=true` to :code:`~/.testcontainers.properties`
 2. Disable ryuk by setting the environment variable :code:`TESTCONTAINERS_RYUK_DISABLED=true`
-3. Instantiate a container using :code:`with_reuse`
+3. Instantiate a container using :code:`with_reuse()` and :code:`start()`
 
 .. doctest::
 
     >>> from testcontainers.core.container import DockerContainer
 
-    >>> with DockerContainer("hello-world").with_reuse() as container:
-    ...     first_id = container._container.id
-    >>> with DockerContainer("hello-world").with_reuse() as container:
-    ...     second_id == container._container.id
+    >>> container = DockerContainer("hello-world").with_reuse().start()
+    >>> first_id = container._container.id
+    >>> container = DockerContainer("hello-world").with_reuse().start()
+    >>> second_id == container._container.id
     >>> print(first_id == second_id)
     True