feat: DockerContainer initializer to accept its private members as kwargs (#809)

Re submitting what is the end result of the iterations in
#238
submitted originally by @vikhal.

Simply enabling the initializer of `DockerContainer` to accept its
private members as kwargs.

---------

Co-authored-by: David Ankin <[email protected]>

Author: terry-docker

.github/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "4.10.0"
+    ".": "4.11.0"
 }

.github/workflows/ci-core.yml

@@ -1,4 +1,4 @@
-# Contrinuous Integration for the core package
+# Continuous Integration for the core package
 
 name: core
 
@@ -25,6 +25,8 @@ jobs:
         run: poetry install --all-extras
       - name: Run twine check
         run: poetry build && poetry run twine check dist/*.tar.gz
+      - name: Set up Docker
+        uses: docker/setup-docker-action@v4
       - name: Run tests
         run: make core/tests
       - name: Rename coverage file

CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [4.11.0](https://github.com/testcontainers/testcontainers-python/compare/testcontainers-v4.10.0...testcontainers-v4.11.0) (2025-06-15)
+
+
+### Features
+
+* **core:** Protocol support for container port bind and expose ([#690](https://github.com/testcontainers/testcontainers-python/issues/690)) ([a0d4317](https://github.com/testcontainers/testcontainers-python/commit/a0d4317643005dde4f344eccbfc56c062e83bf05))
+* DockerContainer initializer to accept its private members as kwargs ([#809](https://github.com/testcontainers/testcontainers-python/issues/809)) ([e7feb53](https://github.com/testcontainers/testcontainers-python/commit/e7feb53fe532b6d32d5d0c5a5d517249f8e7de50))
+
+
+### Bug Fixes
+
+* **compose:** use provided docker command instead of default ([#785](https://github.com/testcontainers/testcontainers-python/issues/785)) ([0ae704a](https://github.com/testcontainers/testcontainers-python/commit/0ae704a24de440b715d5f3c11eaa4f18ccd437b5))
+* **core:** Add kwargs to image build ([#708](https://github.com/testcontainers/testcontainers-python/issues/708)) ([cc02f94](https://github.com/testcontainers/testcontainers-python/commit/cc02f9444b41efa62836b21210b07aee1da94d0b))
+* **core:** change with_command type to include list of strings ([#789](https://github.com/testcontainers/testcontainers-python/issues/789)) ([f7c29cb](https://github.com/testcontainers/testcontainers-python/commit/f7c29cb913e4d42d535783c3aa0f3566d4e543bf))
+* **core:** Determine docker socket for rootless docker ([#779](https://github.com/testcontainers/testcontainers-python/issues/779)) ([6817582](https://github.com/testcontainers/testcontainers-python/commit/6817582bf67ed36448b69019ab897c50ae80e7e1))
+* **core:** Typing in docker_client ([#702](https://github.com/testcontainers/testcontainers-python/issues/702)) ([e8bf224](https://github.com/testcontainers/testcontainers-python/commit/e8bf2244c7210e31b34e5fecf2602fdd1b8c0834))
+* **core:** Typing in generic + network ([#700](https://github.com/testcontainers/testcontainers-python/issues/700)) ([2061912](https://github.com/testcontainers/testcontainers-python/commit/2061912e67705be801136f349f372f542a1f262f))
+* **core:** Typing in version ([#701](https://github.com/testcontainers/testcontainers-python/issues/701)) ([9dc2a02](https://github.com/testcontainers/testcontainers-python/commit/9dc2a02ca9b9ffbaacfd7de79ec9f78175758ec0))
+* **core:** wait in test core registry ([#812](https://github.com/testcontainers/testcontainers-python/issues/812)) ([b574c0e](https://github.com/testcontainers/testcontainers-python/commit/b574c0e0a11d57c8c56aef448292f8c2fc233078))
+* **modules:** fix cosmosdb failure ([#827](https://github.com/testcontainers/testcontainers-python/issues/827)) ([dafcbed](https://github.com/testcontainers/testcontainers-python/commit/dafcbed7608e857bebcdd0b4638bec27abadc693))
+* **modules:** update chroma version ([#826](https://github.com/testcontainers/testcontainers-python/issues/826)) ([b7d41dd](https://github.com/testcontainers/testcontainers-python/commit/b7d41ddc5742dd380b6e01c712a02b044a64cbb3))
+* **rabbitmq:** correct pika pypi reference ([#817](https://github.com/testcontainers/testcontainers-python/issues/817)) ([e90d308](https://github.com/testcontainers/testcontainers-python/commit/e90d30826fb7d7cf3cc7db39a86465d448aaa6e0))
+* **registry:** module typed ([#811](https://github.com/testcontainers/testcontainers-python/issues/811)) ([6b11268](https://github.com/testcontainers/testcontainers-python/commit/6b1126884c82529a93bd55030374d322dd0870bc))
+* use connection mode override function in config ([#775](https://github.com/testcontainers/testcontainers-python/issues/775)) ([ab2a1ab](https://github.com/testcontainers/testcontainers-python/commit/ab2a1abd957ffb35719f673a7674df83287f1545)), closes [#774](https://github.com/testcontainers/testcontainers-python/issues/774)
+
 ## [4.10.0](https://github.com/testcontainers/testcontainers-python/compare/testcontainers-v4.9.2...testcontainers-v4.10.0) (2025-04-02)
 
 

core/testcontainers/core/docker_client.py

@@ -151,7 +151,7 @@ def find_host_network(self) -> Optional[str]:
                         except ipaddress.AddressValueError:
                             continue
                         if docker_host in subnet:
-                            return cast(str, network.name)
+                            return cast("str", network.name)
         except (ipaddress.AddressValueError, OSError):
             pass
         return None
@@ -163,7 +163,7 @@ def port(self, container_id: str, port: int) -> str:
         port_mappings = self.client.api.port(container_id, port)
         if not port_mappings:
             raise ConnectionError(f"Port mapping for container {container_id} and port {port} is not available")
-        return cast(str, port_mappings[0]["HostPort"])
+        return cast("str", port_mappings[0]["HostPort"])
 
     def get_container(self, container_id: str) -> dict[str, Any]:
         """
@@ -172,7 +172,7 @@ def get_container(self, container_id: str) -> dict[str, Any]:
         containers = self.client.api.containers(filters={"id": container_id})
         if not containers:
             raise RuntimeError(f"Could not get container with id {container_id}")
-        return cast(dict[str, Any], containers[0])
+        return cast("dict[str, Any]", containers[0])
 
     def bridge_ip(self, container_id: str) -> str:
         """
@@ -241,7 +241,7 @@ def host(self) -> str:
             hostname = url.hostname
             if not hostname or (hostname == "localnpipe" and utils.is_windows()):
                 return "localhost"
-            return cast(str, url.hostname)
+            return cast("str", url.hostname)
         if utils.inside_container() and ("unix" in url.scheme or "npipe" in url.scheme):
             ip_address = utils.default_gateway_ip()
             if ip_address:
@@ -257,7 +257,7 @@ def login(self, auth_config: DockerAuthInfo) -> None:
 
     def client_networks_create(self, name: str, param: dict[str, Any]) -> dict[str, Any]:
         labels = create_labels("", param.get("labels"))
-        return cast(dict[str, Any], self.client.networks.create(name, **{**param, "labels": labels}))
+        return cast("dict[str, Any]", self.client.networks.create(name, **{**param, "labels": labels}))
 
 
 def get_docker_host() -> Optional[str]:

core/tests/test_core_registry.py

@@ -15,7 +15,7 @@
 from testcontainers.core.config import testcontainers_config
 from testcontainers.core.container import DockerContainer
 from testcontainers.core.docker_client import DockerClient
-from testcontainers.core.waiting_utils import wait_container_is_ready
+from testcontainers.core.waiting_utils import wait_for_logs
 
 from testcontainers.registry import DockerRegistryContainer
 from testcontainers.core.utils import is_mac
@@ -43,22 +43,22 @@ def test_missing_on_private_registry(monkeypatch):
         with pytest.raises(NotFound):
             # Test a container with image from private registry
             with DockerContainer(f"{registry_url}/{image}:{tag}") as test_container:
-                wait_container_is_ready(test_container)
+                wait_for_logs(test_container, "Hello from Docker!")
 
 
 @pytest.mark.skipif(
     is_mac(),
     reason="Docker Desktop on macOS does not support local insecure registries over HTTP without modifying daemon settings",
 )
 @pytest.mark.parametrize(
-    "image,tag,username,password",
+    "image,tag,username,password,expected_output",
     [
-        ("nginx", "test", "user", "pass"),
-        ("hello-world", "latest", "new_user", "new_pass"),
-        ("alpine", "3.12", None, None),
+        ("nginx", "test", "user", "pass", "start worker processes"),
+        ("hello-world", "latest", "new_user", "new_pass", "Hello from Docker!"),
+        ("alpine", "3.12", None, None, ""),
     ],
 )
-def test_with_private_registry(image, tag, username, password, monkeypatch):
+def test_with_private_registry(image, tag, username, password, expected_output, monkeypatch):
     client = DockerClient().client
 
     with DockerRegistryContainer(username=username, password=password) as registry:
@@ -85,7 +85,7 @@ def test_with_private_registry(image, tag, username, password, monkeypatch):
 
         # Test a container with image from private registry
         with DockerContainer(f"{registry_url}/{image}:{tag}") as test_container:
-            wait_container_is_ready(test_container)
+            wait_for_logs(test_container, expected_output)
 
     # cleanup
     client.images.remove(f"{registry_url}/{image}:{tag}")

modules/chroma/testcontainers/chroma/__init__.py

@@ -32,13 +32,13 @@ class ChromaContainer(DockerContainer):
 
     def __init__(
         self,
-        image: str = "chromadb/chroma:latest",
+        image: str = "chromadb/chroma:1.0.0",
         port: int = 8000,
         **kwargs,
     ) -> None:
         """
         Args:
-            image: Docker image to use for the MinIO container.
+            image: Docker image to use for the ChromaDB container.
             port: Port to expose on the container.
             access_key: Access key for client connections.
             secret_key: Secret key for client connections.
@@ -55,7 +55,7 @@ def get_config(self) -> dict:
         including the endpoint.
 
         Returns:
-            dict: {`endpoint`: str}
+            dict: {`endpoint`: str, `host`: str, `port`: int}
         """
         host_ip = self.get_container_host_ip()
         exposed_port = self.get_exposed_port(self.port)
@@ -69,7 +69,7 @@ def get_config(self) -> dict:
     def _healthcheck(self) -> None:
         """This is an internal method used to check if the Chroma container
         is healthy and ready to receive requests."""
-        url = f"http://{self.get_config()['endpoint']}/api/v1/heartbeat"
+        url = f"http://{self.get_config()['endpoint']}/api/v2/heartbeat"
         response: Response = get(url)
         response.raise_for_status()
 

modules/chroma/tests/test_chroma.py

@@ -3,7 +3,7 @@
 
 
 def test_docker_run_chroma():
-    with ChromaContainer(image="chromadb/chroma:0.4.24") as chroma:
+    with ChromaContainer(image="chromadb/chroma:1.0.0") as chroma:
         client = chromadb.HttpClient(host=chroma.get_config()["host"], port=chroma.get_config()["port"])
         col = client.get_or_create_collection("test")
         assert col.name == "test"

modules/cosmosdb/testcontainers/cosmosdb/mongodb.py

@@ -27,7 +27,7 @@ def __init__(
         self,
         mongodb_version: str,
         image: str = os.getenv(
-            "AZURE_COSMOS_EMULATOR_IMAGE", "mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:mongodb"
+            "AZURE_COSMOS_EMULATOR_IMAGE", "mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest"
         ),
         **other_kwargs,
     ):

modules/postgres/tests/test_postgres.py

@@ -133,3 +133,21 @@ def test_none_driver_urls():
 
         url = container.get_connection_url(driver=None)
         assert url == expected_url
+
+
+def test_psycopg_versions():
+    """Test that both psycopg2 and psycopg (v2 and v3) work with the container."""
+
+    postgres_container = PostgresContainer("postgres:16-alpine", driver="psycopg2")
+    with postgres_container as postgres:
+        engine = sqlalchemy.create_engine(postgres.get_connection_url())
+        with engine.begin() as connection:
+            result = connection.execute(sqlalchemy.text("SELECT 1 as test"))
+            assert result.scalar() == 1
+
+    postgres_container = PostgresContainer("postgres:16-alpine", driver="psycopg")
+    with postgres_container as postgres:
+        engine = sqlalchemy.create_engine(postgres.get_connection_url())
+        with engine.begin() as connection:
+            result = connection.execute(sqlalchemy.text("SELECT 1 as test"))
+            assert result.scalar() == 1

modules/qdrant/testcontainers/qdrant/__init__.py

@@ -39,7 +39,7 @@ class QdrantContainer(DbContainer):
 
     def __init__(
         self,
-        image: str = "qdrant/qdrant:v1.8.3",
+        image: str = "qdrant/qdrant:v1.13.5",
         rest_port: int = 6333,
         grpc_port: int = 6334,
         api_key: Optional[str] = None,