feat: support influxdb (testcontainers#413)

Thanks to the team for this great testing utility 🙏 

This PR brings the possibility to spawn a Docker instance of InfluxDB
(timeseries-oriented database) for integration testing. This PR supports
both 1.x and 2.x versions of InfluxDB, which rely on different query
languages and require the use of different Python client libraries.
Therefore:

- there is a root `InfluxDbContainer` class in
`testcontainers/influxdb.py` for the common mechanisms (health check,
connection url, etc.)
- there are 2 separate classes, one for each InfluxDB major version:
`InfluxDb1Container` class in `testcontainers/influxdb1/__init__.py`,
`InfluxDb2Container` in `testcontainers/influxdb2/__init__.py` that are
meant to be used by the testcontainers users. Each one has its own
`.get_client()` method involving the dedicated Python client library

Unit and integration tests (meant to be examples for the testcontainers
end-users) are provided in the PR.

Author: lucsorel

INDEX.rst

@@ -20,6 +20,7 @@ testcontainers-python facilitates the use of Docker containers for functional an
     modules/clickhouse/README
     modules/elasticsearch/README
     modules/google/README
+    modules/influxdb/README
     modules/kafka/README
     modules/keycloak/README
     modules/localstack/README

modules/influxdb/README.rst

@@ -0,0 +1,2 @@
+.. autoclass:: testcontainers.influxdb.InfluxDbContainer
+.. title:: testcontainers.influxdb.InfluxDbContainer

modules/influxdb/testcontainers/influxdb.py

@@ -0,0 +1,99 @@
+#
+#    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.
+
+"""
+testcontainers/influxdb provides means to spawn an InfluxDB instance within a Docker container.
+
+- this influxdb.py module provides the common mechanism to spawn an InfluxDB container.
+  You are not likely to use this module directly.
+- import the InfluxDb1Container class from the influxdb1/__init__.py module to spawn
+  a container for an InfluxDB 1.x instance
+- import the InfluxDb2Container class from the influxdb2/__init__.py module to spawn
+  a container for an InfluxDB 2.x instance
+
+The 2 containers are separated in different modules for 2 reasons:
+- because the Docker images are not designed to be used in the same way
+- because the InfluxDB clients are different for 1.x and 2.x versions,
+  so you won't have to install dependencies that you do not need
+"""
+from typing import Optional
+
+from requests import get
+from requests.exceptions import ConnectionError, ReadTimeout
+
+from testcontainers.core.container import DockerContainer
+from testcontainers.core.waiting_utils import wait_container_is_ready
+
+
+class InfluxDbContainer(DockerContainer):
+    """
+    Abstract class for Docker containers of InfluxDB v1 and v2.
+
+    Concrete implementations for InfluxDB 1.x and 2.x are separated iun different packages
+    because their respective clients rely on different Python libraries which we don't want
+    to import at the same time.
+    """
+
+    def __init__(
+        self,
+        # Docker image name
+        image: str,
+        # in the container, the default port for influxdb is often 8086 and not likely to change
+        container_port: int = 8086,
+        # specifies the port on the host machine where influxdb is exposed; a random available port otherwise
+        host_port: Optional[int] = None,
+        **docker_client_kw,
+    ):
+        super().__init__(image=image, **docker_client_kw)
+        self.container_port = container_port
+        self.host_port = host_port
+        self.with_bind_ports(self.container_port, self.host_port)
+
+    def get_url(self) -> str:
+        """
+        Returns the url to interact with the InfluxDB container (health check, REST API, etc.)
+        """
+        host = self.get_container_host_ip()
+        port = self.get_exposed_port(self.container_port)
+
+        return f"http://{host}:{port}"
+
+    @wait_container_is_ready(ConnectionError, ReadTimeout)
+    def _health_check(self) -> dict:
+        """
+        Performs a health check on the running InfluxDB container.
+        The call is retried until it works thanks to the @wait_container_is_ready decorator.
+        See its documentation for the max number of retries or the timeout.
+        """
+
+        url = self.get_url()
+        response = get(f"{url}/health", timeout=1)
+        response.raise_for_status()
+
+        return response.json()
+
+    def get_influxdb_version(self) -> str:
+        """
+        Returns the version of the InfluxDB service, as returned by the healthcheck.
+        """
+
+        return self._health_check().get("version")
+
+    def start(self) -> "InfluxDbContainer":
+        """
+        Spawns a container of the InfluxDB Docker image, ready to be used.
+        """
+        super().start()
+        self._health_check()
+
+        return self

modules/influxdb/testcontainers/influxdb1/__init__.py

@@ -0,0 +1,65 @@
+#
+#    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 typing import Optional
+
+from influxdb import InfluxDBClient
+
+from testcontainers.influxdb import InfluxDbContainer
+
+
+class InfluxDb1Container(InfluxDbContainer):
+    """
+    Docker container for InfluxDB 1.x.
+    Official Docker images for InfluxDB are hosted at https://hub.docker.com/_/influxdb/.
+
+    Example:
+
+        .. doctest::
+
+            >>> from testcontainers.influxdb1 import InfluxDbContainer
+
+            >>> with InfluxDbContainer() as influxdb:
+            ...    version = influxdb.get_version()
+    """
+
+    def __init__(
+        self,
+        image: str = "influxdb:1.8",
+        # in the container, the default port for influxdb is often 8086 and not likely to change
+        container_port: int = 8086,
+        # specifies the port on the host machine where influxdb is exposed; a random available port otherwise
+        host_port: Optional[int] = None,
+        **docker_client_kw,
+    ):
+        super().__init__(image, container_port, host_port, **docker_client_kw)
+
+    def get_client(self, **client_kwargs):
+        """
+        Returns an instance of the influxdb client, for InfluxDB 1.x versions.
+        Note that this client is not maintained anymore, but it is the only
+        official client available for 1.x InfluxDB versions:
+        - https://github.com/influxdata/influxdb-python
+        - https://pypi.org/project/influxdb/
+
+        To some extent, you can use the v2 client with InfluxDB v1.8+:
+        - https://github.com/influxdata/influxdb-client-python#influxdb-18-api-compatibility
+        """
+
+        return InfluxDBClient(self.get_container_host_ip(), self.get_exposed_port(self.container_port), **client_kwargs)
+
+    def start(self) -> "InfluxDb1Container":
+        """
+        Overridden for better typing reason
+        """
+        return super().start()

modules/influxdb/testcontainers/influxdb2/__init__.py

@@ -0,0 +1,106 @@
+#
+#    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 os import getenv
+from typing import Optional
+
+from influxdb_client import InfluxDBClient, Organization
+
+from testcontainers.influxdb import InfluxDbContainer
+
+
+class InfluxDb2Container(InfluxDbContainer):
+    """
+    Docker container for InfluxDB 2.x.
+    Official Docker images for InfluxDB are hosted at https://hub.docker.com/_/influxdb/.
+
+    Example:
+
+        .. doctest::
+
+            >>> from testcontainers.influxdb2 import InfluxDb2Container
+
+            >>> with InfluxDb2Container() as influxdb2:
+            ...    version = influxdb2.get_version()
+    """
+
+    def __init__(
+        self,
+        image: str = "influxdb:latest",
+        # in the container, the default port for influxdb is often 8086 and not likely to change
+        container_port: int = 8086,
+        # specifies the port on the host machine where influxdb is exposed; a random available port otherwise
+        host_port: Optional[int] = None,
+        # parameters used by the InfluxDSB 2.x Docker container when spawned in setup mode
+        # (which is likely what you want). In setup mode, init_mode should be "setup" and all
+        # the other parameters should be set (via this constructor or their respective
+        # environment variables); retention does not need to be explicitely set.
+        init_mode: Optional[str] = None,
+        admin_token: Optional[str] = None,
+        username: Optional[str] = None,
+        password: Optional[str] = None,
+        org_name: Optional[str] = None,
+        bucket: Optional[str] = None,
+        retention: Optional[str] = None,
+        **docker_client_kw,
+    ):
+        super().__init__(image, container_port, host_port, **docker_client_kw)
+
+        configuration = {
+            "DOCKER_INFLUXDB_INIT_MODE": init_mode,
+            "DOCKER_INFLUXDB_INIT_ADMIN_TOKEN": admin_token,
+            "DOCKER_INFLUXDB_INIT_USERNAME": username,
+            "DOCKER_INFLUXDB_INIT_PASSWORD": password,
+            "DOCKER_INFLUXDB_INIT_ORG": org_name,
+            "DOCKER_INFLUXDB_INIT_BUCKET": bucket,
+            "DOCKER_INFLUXDB_INIT_RETENTION": retention,
+        }
+        for env_key, constructor_param in configuration.items():
+            env_value = constructor_param or getenv(env_key)
+            if env_value:
+                self.with_env(env_key, env_value)
+
+    def start(self) -> "InfluxDb2Container":
+        """
+        Overridden for better typing reason
+        """
+        return super().start()
+
+    def get_client(
+        self, token: Optional[str] = None, org_name: Optional[str] = None, **influxdb_client_kwargs
+    ) -> tuple[InfluxDBClient, Organization]:
+        """
+        Returns an instance of the influxdb client with the associated test organization created
+        when the container is spawn; for InfluxDB 2.x versions.
+        - https://github.com/influxdata/influxdb-client-python
+        - https://pypi.org/project/influxdb-client/
+
+        This InfluxDB client requires to specify the organization when using most of the API's endpoints,
+        as an Organisation instance rather than its name or id (deprecated). As a convenience, this
+        client getter can also retrieve and return the organization instance along with the client.
+        Otherwise, None is returned in place of the organization instance.
+
+        This organization is created when spawning the container in setup mode (which is likely what you
+        want) by giving its name to the 'org_name' parameter constructor.
+        """
+
+        influxclient = InfluxDBClient(self.get_url(), token=token, **influxdb_client_kwargs)
+
+        if org_name is None:
+            return influxclient, None
+
+        orgs = influxclient.organizations_api().find_organizations(org=org_name)
+        if len(orgs) == 0:
+            raise ValueError(f"Could not retrieved the Organization corresponding to name '{org_name}'")
+
+        return influxclient, orgs[0]