.devcontainer/Dockerfile

@@ -0,0 +1,20 @@
+FROM mcr.microsoft.com/devcontainers/python:1-3.11-bookworm
+
+
+RUN \
+    apt update && apt install bash-completion -y && \
+    pip install pre-commit && \
+    curl -sSL https://install.python-poetry.org | POETRY_HOME=/home/vscode/.local python3 -
+
+
+RUN  \
+    echo >> /home/vscode/.bashrc && \
+    # add completions to bashrc
+    # see how ubuntu does it for reference:
+    # https://git.launchpad.net/ubuntu/+source/base-files/tree/share/dot.bashrc
+    # https://stackoverflow.com/a/68566555
+    echo 'if [ -f /etc/bash_completion ] && ! shopt -oq posix; then' >> /home/vscode/.bashrc && \
+    echo '    . /etc/bash_completion' >> /home/vscode/.bashrc && \
+    echo 'fi' >> /home/vscode/.bashrc && \
+    echo >> /home/vscode/.bashrc && \
+    echo '. <(poetry completions)' >> /home/vscode/.bashrc

.devcontainer/commands/post-create-command.sh

@@ -1,5 +1,4 @@
 echo "Running post-create-command.sh"
 
-curl -sSL https://install.python-poetry.org | python3 -
-
+pre-commit install
 poetry install --all-extras

.devcontainer/devcontainer.json

@@ -3,7 +3,13 @@
 {
 	"name": "Python 3",
 	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
-	"image": "mcr.microsoft.com/devcontainers/python:1-3.11-bookworm",
+	"build": {
+		// Path is relative to the devcontainer.json file.
+		// We prebuild the image to get poetry into the image
+		// This saves the user a bit of time, when re-opening containers
+		"dockerfile": "Dockerfile"
+	},
+
 	"features": {
 		"ghcr.io/devcontainers/features/docker-in-docker:2": {
 			"version": "latest",

.github/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "4.2.0"
+    ".": "4.3.0"
 }

.github/settings.yml

@@ -63,6 +63,7 @@ labels:
   - { name: '🐧 linux',                  color: '#3ED4D',, description: '' }
   - { name: '👀 requires attention',     color: '#fef2c0', description: '' }
   - { name: '📖 documentation',          color: '#d93f0b', description: '' }
+  - { name: '📦 package: cassandra',     color: '#0052CC', description: '' }
   - { name: '📦 package: clickhouse',    color: '#0052CC', description: '' }
   - { name: '📦 package: compose',       color: '#0052CC', description: '' }
   - { name: '📦 package: core',          color: '#0052CC', description: '' }

.github/workflows/ci-community.yml

@@ -14,7 +14,7 @@ on:
 
 jobs:
   track-modules:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
       - name: Checkout contents
         uses: actions/checkout@v4
@@ -38,14 +38,14 @@ jobs:
     outputs:
       changed_modules: ${{ steps.compute-changes.outputs.computed_modules }}
   test:
+    runs-on: ubuntu-22.04
     needs: [track-modules]
     if: ${{ needs.track-modules.outputs.changed_modules != '[]' }}
     strategy:
       fail-fast: false
       matrix:
-        python-version: [ "3.11" ]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
         module: ${{ fromJSON(needs.track-modules.outputs.changed_modules) }}
-    runs-on: ubuntu-latest
     steps:
       - name: Checkout contents
         uses: actions/checkout@v4
@@ -57,3 +57,5 @@ jobs:
         run: poetry install -E ${{ matrix.module }}
       - name: Run tests
         run: make modules/${{ matrix.module }}/tests
+      - name: Run doctests
+        run: make modules/${{ matrix.module }}/doctests

.github/workflows/ci-core.yml

@@ -10,12 +10,11 @@ on:
 
 jobs:
   test:
+    runs-on: ubuntu-22.04
     strategy:
       fail-fast: false
       matrix:
-        os: [ ubuntu ]
         python-version: ["3.9", "3.10", "3.11", "3.12"]
-    runs-on: ${{ matrix.os }}-latest
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python
@@ -28,3 +27,5 @@ jobs:
         run: poetry build && poetry run twine check dist/*.tar.gz
       - name: Run tests
         run: make core/tests
+      - name: Run doctests
+        run: make core/doctests

.github/workflows/ci-lint.yml

@@ -10,7 +10,7 @@ on:
 
 jobs:
   python:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v4
       - name: Setup Env

.github/workflows/docs.yml

@@ -8,7 +8,7 @@ on:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python

.github/workflows/pr-lint.yml

@@ -13,7 +13,7 @@ permissions:
 jobs:
   validate:
     name: validate-pull-request-title
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
       - name: validate pull request title
         uses: kontrolplane/pull-request-title-validator@ab2b54babb5337246f4b55cf8e0a1ecb0575e46d  #v1

.github/workflows/release-please.yml

@@ -6,7 +6,7 @@ on:
 
 jobs:
   release:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     outputs:
       release_created: ${{ steps.track-release.outputs.release_created }}
     steps:
@@ -16,7 +16,7 @@ jobs:
           manifest-file: .github/.release-please-manifest.json
           config-file: .github/release-please-config.json
   publish:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     environment: release
     permissions:
       id-token: write

CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [4.3.0](https://github.com/testcontainers/testcontainers-python/compare/testcontainers-v4.2.0...testcontainers-v4.3.0) (2024-04-01)
+
+
+### Features
+
+* **client:** Add custom User-Agent in Docker client as `tc-python/<version>` ([#507](https://github.com/testcontainers/testcontainers-python/issues/507)) ([dd55082](https://github.com/testcontainers/testcontainers-python/commit/dd55082991b3405038a90678a39e8c815f0d1fc8))
+
+
+### Bug Fixes
+
+* Add CassandraContainer ([#476](https://github.com/testcontainers/testcontainers-python/issues/476)) ([507e466](https://github.com/testcontainers/testcontainers-python/commit/507e466a1fa9ac64c254ceb9ae0d57f6bfd8c89d))
+* add chroma container ([#515](https://github.com/testcontainers/testcontainers-python/issues/515)) ([0729bf4](https://github.com/testcontainers/testcontainers-python/commit/0729bf4af957f8b6638cc204b108358745c0cfc9))
+* Add Weaviate module ([#492](https://github.com/testcontainers/testcontainers-python/issues/492)) ([90762e8](https://github.com/testcontainers/testcontainers-python/commit/90762e817bf49de6d6366212fb48e7edb67ab0c6))
+* **cassandra:** make cassandra dependency optional/test-only ([#518](https://github.com/testcontainers/testcontainers-python/issues/518)) ([bddbaeb](https://github.com/testcontainers/testcontainers-python/commit/bddbaeb20cbd147c429f8020395355402b8a7268))
+* **core:** allow setting docker command path for docker compose ([#512](https://github.com/testcontainers/testcontainers-python/issues/512)) ([63fcd52](https://github.com/testcontainers/testcontainers-python/commit/63fcd52ec2d6ded5f6413166a3690c1138e4dae0))
+* **google:** add support for Datastore emulator ([#508](https://github.com/testcontainers/testcontainers-python/issues/508)) ([3d891a5](https://github.com/testcontainers/testcontainers-python/commit/3d891a5ec62944d01d1bf3d6f70e6aec83f6e516))
+* Improved Oracle DB module ([#363](https://github.com/testcontainers/testcontainers-python/issues/363)) ([6e6d8e3](https://github.com/testcontainers/testcontainers-python/commit/6e6d8e3c919be3efa581704868193e66da54acf3))
+* inconsistent test runs for community modules ([#497](https://github.com/testcontainers/testcontainers-python/issues/497)) ([914f1e5](https://github.com/testcontainers/testcontainers-python/commit/914f1e55bcb3b10260788c3affb8426f77eb9036))
+* **kafka:** Add redpanda testcontainer module ([#441](https://github.com/testcontainers/testcontainers-python/issues/441)) ([451d278](https://github.com/testcontainers/testcontainers-python/commit/451d27865873bb75f4a09a26442572745408d013))
+* **kafka:** wait_for_logs in kafka container to reduce lib requirement ([#377](https://github.com/testcontainers/testcontainers-python/issues/377)) ([909107b](https://github.com/testcontainers/testcontainers-python/commit/909107b221417a39516f961364beb518d2756f45))
+* **keycloak:** container should use dedicated API endpoints to determine container readiness ([#490](https://github.com/testcontainers/testcontainers-python/issues/490)) ([2e27225](https://github.com/testcontainers/testcontainers-python/commit/2e272253148797759748bd40c42f797697d3163f))
+* **nats:** Client-Free(ish) NATS container ([#462](https://github.com/testcontainers/testcontainers-python/issues/462)) ([302c73d](https://github.com/testcontainers/testcontainers-python/commit/302c73ddaa7a6b5bc071ab0cc36d15461cae348b))
+* **new:** add a new Docker Registry test container ([#389](https://github.com/testcontainers/testcontainers-python/issues/389)) ([0f554fb](https://github.com/testcontainers/testcontainers-python/commit/0f554fbaa9511e0221806f57de971abedf1c0bf2))
+* pass doctests, s/doctest/doctests/, run them in gha, s/asyncpg/psycopg/ in doctest, fix keycloak flakiness: wait for first user ([#505](https://github.com/testcontainers/testcontainers-python/issues/505)) ([545240d](https://github.com/testcontainers/testcontainers-python/commit/545240dfdcb2a565ad7cef0e9813f03b9b6f910e))
+* pass updated keyword args to Publisher/Subscriber client in google/pubsub [#161](https://github.com/testcontainers/testcontainers-python/issues/161) ([#164](https://github.com/testcontainers/testcontainers-python/issues/164)) ([8addc11](https://github.com/testcontainers/testcontainers-python/commit/8addc111c94826c2a619a0880d48550673f4d7b9))
+* Qdrant module ([#463](https://github.com/testcontainers/testcontainers-python/issues/463)) ([e8876f4](https://github.com/testcontainers/testcontainers-python/commit/e8876f422abeb29a7236f2174f7e7a324b7d26cb))
+* remove accidentally added pip in dev dependencies ([#516](https://github.com/testcontainers/testcontainers-python/issues/516)) ([dee20a7](https://github.com/testcontainers/testcontainers-python/commit/dee20a76c88445b911d38b4704c2380114a66794))
+* **ryuk:** Enable Ryuk test suite. Ryuk image 0.5.1 -> 0.7.0. Add RYUK_RECONNECTION_TIMEOUT env variable ([#509](https://github.com/testcontainers/testcontainers-python/issues/509)) ([472b2c2](https://github.com/testcontainers/testcontainers-python/commit/472b2c24aec232a04c00dd7dcd9a9f05f2dfaa66))
+
 ## [4.2.0](https://github.com/testcontainers/testcontainers-python/compare/testcontainers-v4.1.0...testcontainers-v4.2.0) (2024-03-24)
 
 

Makefile

@@ -11,7 +11,7 @@ UPLOAD = $(addsuffix /upload,${PACKAGES})
 # All */tests folders for each of the test suites.
 TESTS = $(addsuffix /tests,$(filter-out meta,${PACKAGES}))
 TESTS_DIND = $(addsuffix -dind,${TESTS})
-DOCTESTS = $(addsuffix /doctest,$(filter-out meta,${PACKAGES}))
+DOCTESTS = $(addsuffix /doctests,$(filter-out modules/README.md,${PACKAGES}))
 # All linting targets.
 LINT = $(addsuffix /lint,${PACKAGES})
 
@@ -56,10 +56,10 @@ ${TESTS_DIND} : %/tests-dind : image
 docs :
 	poetry run sphinx-build -nW . docs/_build
 
-doctest : ${DOCTESTS}
+doctests : ${DOCTESTS}
 	poetry run sphinx-build -b doctest . docs/_build
 
-${DOCTESTS} : %/doctest :
+${DOCTESTS} : %/doctests :
 	poetry run sphinx-build -b doctest -c doctests $* docs/_build
 
 # Remove any generated files.

README.md

@@ -25,9 +25,10 @@ The snippet above will spin up a postgres database in a container. The `get_conn
 
 ## Configuration
 
-| Env Variable                              | Example                       | Description                              |
-| ----------------------------------------- | ----------------------------- | ---------------------------------------- |
-| `TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE`   | `/var/run/docker.sock`        | Path to Docker's socket used by ryuk     |
-| `TESTCONTAINERS_RYUK_PRIVILEGED`          | `false`                       | Run ryuk as a privileged container       |
-| `TESTCONTAINERS_RYUK_DISABLED`            | `false`                       | Disable ryuk                             |
-| `RYUK_CONTAINER_IMAGE`                    | `testcontainers/ryuk:0.5.1`   | Custom image for ryuk                    |
+| Env Variable                            | Example                     | Description                                                                        |
+| --------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------- |
+| `TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE` | `/var/run/docker.sock`      | Path to Docker's socket used by ryuk                                               |
+| `TESTCONTAINERS_RYUK_PRIVILEGED`        | `false`                     | Run ryuk as a privileged container                                                 |
+| `TESTCONTAINERS_RYUK_DISABLED`          | `false`                     | Disable ryuk                                                                       |
+| `RYUK_CONTAINER_IMAGE`                  | `testcontainers/ryuk:0.7.0` | Custom image for ryuk                                                              |
+| `RYUK_RECONNECTION_TIMEOUT`             | `10s`                       | Reconnection timeout for Ryuk TCP socket before Ryuk reaps all dangling containers |

conf.py

@@ -31,6 +31,7 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
 ]
 
@@ -74,7 +75,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "meta/README.rst", ".venv"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".venv", ".git"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
@@ -156,3 +157,7 @@
         "Miscellaneous",
     ),
 ]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}

core/testcontainers/compose/compose.py

@@ -158,6 +158,7 @@ class DockerCompose:
     wait: bool = True
     env_file: Optional[str] = None
     services: Optional[list[str]] = None
+    docker_command_path: Optional[str] = None
 
     def __post_init__(self):
         if isinstance(self.compose_file_name, str):
@@ -181,7 +182,7 @@ def docker_compose_command(self) -> list[str]:
 
     @cached_property
     def compose_command_property(self) -> list[str]:
-        docker_compose_cmd = ["docker", "compose"]
+        docker_compose_cmd = [self.docker_command_path or "docker", "compose"]
         if self.compose_file_name:
             for file in self.compose_file_name:
                 docker_compose_cmd += ["-f", file]

core/testcontainers/core/config.py

@@ -4,7 +4,8 @@
 SLEEP_TIME = int(environ.get("TC_POOLING_INTERVAL", 1))
 TIMEOUT = MAX_TRIES * SLEEP_TIME
 
-RYUK_IMAGE: str = environ.get("RYUK_CONTAINER_IMAGE", "testcontainers/ryuk:0.5.1")
+RYUK_IMAGE: str = environ.get("RYUK_CONTAINER_IMAGE", "testcontainers/ryuk:0.7.0")
 RYUK_PRIVILEGED: bool = environ.get("TESTCONTAINERS_RYUK_PRIVILEGED", "false") == "true"
 RYUK_DISABLED: bool = environ.get("TESTCONTAINERS_RYUK_DISABLED", "false") == "true"
 RYUK_DOCKER_SOCKET: str = environ.get("TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE", "/var/run/docker.sock")
+RYUK_RECONNECTION_TIMEOUT: str = environ.get("RYUK_RECONNECTION_TIMEOUT", "10s")

core/testcontainers/core/container.py

@@ -1,8 +1,17 @@
+import contextlib
 from platform import system
 from socket import socket
 from typing import TYPE_CHECKING, Optional
 
-from testcontainers.core.config import RYUK_DISABLED, RYUK_DOCKER_SOCKET, RYUK_IMAGE, RYUK_PRIVILEGED
+import docker.errors
+
+from testcontainers.core.config import (
+    RYUK_DISABLED,
+    RYUK_DOCKER_SOCKET,
+    RYUK_IMAGE,
+    RYUK_PRIVILEGED,
+    RYUK_RECONNECTION_TIMEOUT,
+)
 from testcontainers.core.docker_client import DockerClient
 from testcontainers.core.exceptions import ContainerStartException
 from testcontainers.core.labels import LABEL_SESSION_ID, SESSION_ID
@@ -177,8 +186,9 @@ def delete_instance(cls) -> None:
             Reaper._socket.close()
             Reaper._socket = None
 
-        if Reaper._container is not None:
-            Reaper._container.stop()
+        if Reaper._container is not None and Reaper._container._container is not None:
+            with contextlib.suppress(docker.errors.NotFound):
+                Reaper._container.stop()
             Reaper._container = None
 
         if Reaper._instance is not None:
@@ -194,6 +204,7 @@ def _create_instance(cls) -> "Reaper":
             .with_exposed_ports(8080)
             .with_volume_mapping(RYUK_DOCKER_SOCKET, "/var/run/docker.sock", "rw")
             .with_kwargs(privileged=RYUK_PRIVILEGED, auto_remove=True)
+            .with_env("RYUK_RECONNECTION_TIMEOUT", RYUK_RECONNECTION_TIMEOUT)
             .start()
         )
         wait_for_logs(Reaper._container, r".* Started!")

core/testcontainers/core/docker_client.py

@@ -11,6 +11,7 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 import functools as ft
+import importlib.metadata
 import ipaddress
 import os
 import urllib
@@ -44,6 +45,7 @@ def __init__(self, **kwargs) -> None:
         else:
             self.client = docker.from_env(**kwargs)
         self.client.api.headers["x-tc-sid"] = SESSION_ID
+        self.client.api.headers["User-Agent"] = "tc-python/" + importlib.metadata.version("testcontainers")
 
     @ft.wraps(ContainerCollection.run)
     def run(