feat(valkey): add Valkey module (#947)

I’d like to add Valkey, the open-source fork of Redis, as a dedicated
Testcontainers module.

- Docker container: valkey/valkey:latest
- Valkey website: https://valkey.io/
- Documentation: https://valkey.io/docs/

---------

Signed-off-by: Daria Korenieva <daric2612@gmail.com>
Co-authored-by: Roy Moore <roy@moore.co.il>

Author: daric93

docs/modules/valkey.md

@@ -0,0 +1,23 @@
+# Valkey
+
+Since testcontainers-python <a href="https://github.com/testcontainers/testcontainers-python/releases/tag/v4.14.3"><span class="tc-version">:material-tag: v4.14.3</span></a>
+
+## Introduction
+
+The Testcontainers module for Valkey.
+
+## Adding this module to your project dependencies
+
+Please run the following command to add the Valkey module to your python dependencies:
+
+```bash
+pip install testcontainers[valkey]
+```
+
+## Usage example
+
+<!--codeinclude-->
+
+[Creating a Valkey container](../../modules/valkey/example_basic.py)
+
+<!--/codeinclude-->

mkdocs.yml

@@ -72,6 +72,7 @@ nav:
           - modules/redis.md
           - modules/scylla.md
           - modules/trino.md
+          - modules/valkey.md
           - modules/weaviate.md
       - modules/aws.md
       - modules/azurite.md

modules/valkey/README.rst

@@ -0,0 +1,2 @@
+.. autoclass:: testcontainers.valkey.ValkeyContainer
+.. title:: testcontainers.valkey.ValkeyContainer

modules/valkey/example_basic.py

@@ -0,0 +1,82 @@
+"""
+Valkey container usage examples with valkey-glide sync client.
+
+Requires: pip install valkey-glide-sync
+"""
+
+from glide_sync import GlideClient, GlideClientConfiguration, NodeAddress, ServerCredentials
+
+from testcontainers.valkey import ValkeyContainer
+
+
+def basic_example():
+    with ValkeyContainer() as valkey_container:
+        host = valkey_container.get_host()
+        port = valkey_container.get_exposed_port()
+        connection_url = valkey_container.get_connection_url()
+
+        print(f"Valkey connection URL: {connection_url}")
+        print(f"Host: {host}, Port: {port}")
+
+        config = GlideClientConfiguration([NodeAddress(host, port)])
+        client = GlideClient.create(config)
+
+        pong = client.ping()
+        print(f"PING response: {pong}")
+
+        client.set("key", "value")
+        print("SET response: OK")
+
+        value = client.get("key")
+        print(f"GET response: {value}")
+
+        client.close()
+
+
+def password_example():
+    with ValkeyContainer().with_password("mypassword") as valkey_container:
+        host = valkey_container.get_host()
+        port = valkey_container.get_exposed_port()
+        connection_url = valkey_container.get_connection_url()
+
+        print(f"\nValkey with password connection URL: {connection_url}")
+
+        config = GlideClientConfiguration(
+            [NodeAddress(host, port)],
+            credentials=ServerCredentials(password="mypassword"),
+        )
+        client = GlideClient.create(config)
+
+        pong = client.ping()
+        print(f"PING response: {pong}")
+
+        client.close()
+
+
+def version_example():
+    with ValkeyContainer().with_image_tag("8.0") as valkey_container:
+        print(f"\nUsing image: {valkey_container.image}")
+        connection_url = valkey_container.get_connection_url()
+        print(f"Connection URL: {connection_url}")
+
+
+def bundle_example():
+    with ValkeyContainer().with_bundle() as valkey_container:
+        print(f"\nUsing bundle image: {valkey_container.image}")
+        host = valkey_container.get_host()
+        port = valkey_container.get_exposed_port()
+
+        config = GlideClientConfiguration([NodeAddress(host, port)])
+        client = GlideClient.create(config)
+
+        pong = client.ping()
+        print(f"PING response: {pong}")
+
+        client.close()
+
+
+if __name__ == "__main__":
+    basic_example()
+    password_example()
+    version_example()
+    bundle_example()

modules/valkey/testcontainers/valkey/__init__.py

@@ -0,0 +1,103 @@
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+from testcontainers.core.container import DockerContainer
+from testcontainers.core.wait_strategies import ExecWaitStrategy
+
+_BASE_IMAGE = "valkey/valkey"
+_BUNDLE_IMAGE = "valkey/valkey-bundle"
+
+
+class ValkeyContainer(DockerContainer):
+    """
+    Valkey container.
+
+    """
+
+    def __init__(self, image: str = f"{_BASE_IMAGE}:latest", port: int = 6379, **kwargs) -> None:
+        super().__init__(image, **kwargs)
+        self.port = port
+        self.password: str | None = None
+        self.with_exposed_ports(self.port)
+        self.waiting_for(ExecWaitStrategy(["valkey-cli", "ping"]))
+
+    def with_password(self, password: str) -> "ValkeyContainer":
+        """
+        Configure authentication for Valkey.
+
+        Args:
+            password: Password for Valkey authentication.
+
+        Returns:
+            self: Container instance for method chaining.
+        """
+        self.password = password
+        self.with_command(["valkey-server", "--requirepass", password])
+        self.waiting_for(ExecWaitStrategy(["valkey-cli", "-a", password, "ping"]))
+        return self
+
+    def with_image_tag(self, tag: str) -> "ValkeyContainer":
+        """
+        Specify Valkey version.
+
+        Args:
+            tag: Image tag (e.g., '8.0', 'latest').
+
+        Returns:
+            self: Container instance for method chaining.
+        """
+        base_image = self.image.rsplit(":", 1)[0]
+        self.image = f"{base_image}:{tag}"
+        return self
+
+    def with_bundle(self) -> "ValkeyContainer":
+        """
+        Enable all modules by switching to valkey-bundle image.
+
+        Returns:
+            self: Container instance for method chaining.
+        """
+        tag = self.image.rsplit(":", 1)[-1]
+        self.image = f"{_BUNDLE_IMAGE}:{tag}"
+        return self
+
+    def get_connection_url(self) -> str:
+        """
+        Get connection URL for Valkey.
+
+        Returns:
+            url: Connection URL in format valkey://[:password@]host:port
+        """
+        host = self.get_host()
+        port = self.get_exposed_port()
+        if self.password:
+            return f"valkey://:{self.password}@{host}:{port}"
+        return f"valkey://{host}:{port}"
+
+    def get_host(self) -> str:
+        """
+        Get container host.
+
+        Returns:
+            host: Container host IP.
+        """
+        return self.get_container_host_ip()
+
+    def get_exposed_port(self) -> int:
+        """
+        Get mapped port.
+
+        Returns:
+            port: Exposed port number.
+        """
+        return int(super().get_exposed_port(self.port))

modules/valkey/tests/test_valkey.py

@@ -0,0 +1,84 @@
+import socket
+
+from testcontainers.valkey import ValkeyContainer
+
+
+def test_docker_run_valkey():
+    with ValkeyContainer() as valkey:
+        host = valkey.get_host()
+        port = valkey.get_exposed_port()
+
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.connect((host, port))
+            s.sendall(b"*1\r\n$4\r\nPING\r\n")
+            response = s.recv(1024)
+            assert b"+PONG" in response
+
+
+def test_docker_run_valkey_with_password():
+    with ValkeyContainer().with_password("mypass") as valkey:
+        host = valkey.get_host()
+        port = valkey.get_exposed_port()
+
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.connect((host, port))
+            # Authenticate
+            s.sendall(b"*2\r\n$4\r\nAUTH\r\n$6\r\nmypass\r\n")
+            auth_response = s.recv(1024)
+            assert b"+OK" in auth_response
+
+            # Test SET command
+            s.sendall(b"*3\r\n$3\r\nSET\r\n$5\r\nhello\r\n$5\r\nworld\r\n")
+            set_response = s.recv(1024)
+            assert b"+OK" in set_response
+
+            # Test GET command
+            s.sendall(b"*2\r\n$3\r\nGET\r\n$5\r\nhello\r\n")
+            get_response = s.recv(1024)
+            assert b"world" in get_response
+
+
+def test_get_connection_url():
+    with ValkeyContainer() as valkey:
+        url = valkey.get_connection_url()
+        assert url.startswith("valkey://")
+        assert str(valkey.get_exposed_port()) in url
+
+
+def test_get_connection_url_with_password():
+    with ValkeyContainer().with_password("secret") as valkey:
+        url = valkey.get_connection_url()
+        assert url.startswith("valkey://:secret@")
+        assert str(valkey.get_exposed_port()) in url
+
+
+def test_with_image_tag():
+    container = ValkeyContainer().with_image_tag("8.0")
+    assert container.image == "valkey/valkey:8.0"
+
+
+def test_with_bundle():
+    container = ValkeyContainer().with_bundle()
+    assert container.image == "valkey/valkey-bundle:latest"
+
+
+def test_with_bundle_and_tag():
+    container = ValkeyContainer().with_bundle().with_image_tag("9.0")
+    assert container.image == "valkey/valkey-bundle:9.0"
+
+
+def test_with_tag_and_bundle():
+    container = ValkeyContainer().with_image_tag("8.0").with_bundle()
+    assert container.image == "valkey/valkey-bundle:8.0"
+
+
+def test_bundle_starts():
+    with ValkeyContainer().with_bundle() as valkey:
+        host = valkey.get_host()
+        port = valkey.get_exposed_port()
+
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.connect((host, port))
+            s.sendall(b"*1\r\n$4\r\nPING\r\n")
+            response = s.recv(1024)
+            assert b"+PONG" in response

pyproject.toml

@@ -101,6 +101,7 @@ registry = ["bcrypt>=5"]
 selenium = ["selenium>=4"]
 scylla = ["cassandra-driver>=3; python_version < '3.14'"]
 sftp = ["cryptography"]
+valkey = []
 vault = []
 weaviate = ["weaviate-client>=4"]
 chroma = ["chromadb-client>=1"]
@@ -218,6 +219,7 @@ packages = [
   "modules/selenium/testcontainers",
   "modules/scylla/testcontainers",
   "modules/trino/testcontainers",
+  "modules/valkey/testcontainers",
   "modules/vault/testcontainers",
   "modules/weaviate/testcontainers",
 ]
@@ -267,6 +269,7 @@ dev-mode-dirs = [
   "modules/selenium",
   "modules/scylla",
   "modules/trino",
+  "modules/valkey",
   "modules/vault",
   "modules/weaviate",
 ]