Merge remote-tracking branch 'upstream/main' into support-arm-local-development

Author: terry-docker

.github/workflows/ci-lint.yml

@@ -20,4 +20,9 @@ jobs:
       - name: Install Python dependencies
         run: poetry install --no-interaction
       - name: Execute pre-commit handler
-        run: poetry run pre-commit run -a
+        run: |
+          poetry run pre-commit run check-toml
+          poetry run pre-commit run trailing-whitespace
+          poetry run pre-commit run end-of-file-fixer
+          poetry run pre-commit run ruff
+          poetry run pre-commit run ruff-format

.pre-commit-config.yaml

@@ -10,21 +10,21 @@ repos:
       - id: end-of-file-fixer
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 'v0.3.5'
+    rev: 'v0.11.5'
     hooks:
       - id: ruff
         # Explicitly setting config to prevent Ruff from using `pyproject.toml` in sub packages.
         args: [ '--fix', '--exit-non-zero-on-fix', '--config', 'pyproject.toml' ]
       - id: ruff-format
         args: [ '--config', 'pyproject.toml' ]
 
-#  - repo: local
-#    hooks:
-#      - id: mypy
-#        name: mypy
-#        entry: poetry run mypy
-#        args: ["--config-file", "pyproject.toml"]
-#        files: "core"  # start with the core being type checked
-#        language: system
-#        types: [ python ]
-#        require_serial: true
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: poetry run mypy
+        args: ["--config-file", "pyproject.toml"]
+        files: "core"  # start with the core being type checked
+        language: system
+        types: [ python ]
+        require_serial: true

Makefile

@@ -30,6 +30,9 @@ coverage:  ## Target to combine and report coverage.
 lint:  ## Lint all files in the project, which we also run in pre-commit
 	poetry run pre-commit run -a
 
+mypy-core-report:
+	poetry run mypy --config-file pyproject.toml core | poetry run python scripts/mypy_report.py
+
 docs: ## Build the docs for the project
 	poetry run sphinx-build -nW . docs/_build
 

conf.py

@@ -161,4 +161,9 @@
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "selenium": ("https://seleniumhq.github.io/selenium/docs/api/py/", None),
+    "typing_extensions": ("https://typing-extensions.readthedocs.io/en/latest/", None),
 }
+
+nitpick_ignore = [
+    ("py:class", "typing_extensions.Self"),
+]

core/README.rst

@@ -4,6 +4,15 @@ Testcontainers Core
 :code:`testcontainers-core` is the core functionality for spinning up Docker containers in test environments.
 
 .. autoclass:: testcontainers.core.container.DockerContainer
+    :members: with_bind_ports, with_exposed_ports
+
+.. note::
+    When using `with_bind_ports` or `with_exposed_ports`
+    you can specify the port in the following formats: :code:`{private_port}/{protocol}`
+
+    e.g. `8080/tcp` or `8125/udp` or just `8080` (default protocol is tcp)
+
+    For legacy reasons, the port can be an *integer*
 
 .. autoclass:: testcontainers.core.image.DockerImage
 

core/testcontainers/compose/__init__.py

@@ -1,8 +1,8 @@
-# flake8: noqa
+# flake8: noqa: F401
 from testcontainers.compose.compose import (
+    ComposeContainer,
     ContainerIsNotRunning,
+    DockerCompose,
     NoSuchPortExposed,
     PublishedPort,
-    ComposeContainer,
-    DockerCompose,
 )

core/testcontainers/compose/compose.py

@@ -293,7 +293,7 @@ def get_config(
             config_cmd.append("--no-interpolate")
 
         cmd_output = self._run_command(cmd=config_cmd).stdout
-        return cast(dict[str, Any], loads(cmd_output))
+        return cast(dict[str, Any], loads(cmd_output))  # noqa: TC006
 
     def get_containers(self, include_all=False) -> list[ComposeContainer]:
         """

core/testcontainers/core/config.py

@@ -17,13 +17,11 @@ class ConnectionMode(Enum):
     @property
     def use_mapped_port(self) -> bool:
         """
-        Return true if we need to use mapped port for this connection
+        Return True if mapped ports should be used for this connection mode.
 
-        This is true for everything but bridge mode.
+        Mapped ports are used for all connection modes except 'bridge_ip'.
         """
-        if self == self.bridge_ip:
-            return False
-        return True
+        return self != ConnectionMode.bridge_ip
 
 
 def get_docker_socket() -> str:
@@ -63,7 +61,7 @@ def get_user_overwritten_connection_mode() -> Optional[ConnectionMode]:
     """
     Return the user overwritten connection mode.
     """
-    connection_mode: str | None = environ.get("TESTCONTAINERS_CONNECTION_MODE")
+    connection_mode: Union[str, None] = environ.get("TESTCONTAINERS_CONNECTION_MODE")
     if connection_mode:
         try:
             return ConnectionMode(connection_mode)
@@ -137,15 +135,15 @@ def timeout(self) -> int:
 testcontainers_config = TestcontainersConfiguration()
 
 __all__ = [
-    # the public API of this module
-    "testcontainers_config",
-    # and all the legacy things that are deprecated:
+    # Legacy things that are deprecated:
     "MAX_TRIES",
-    "SLEEP_TIME",
-    "TIMEOUT",
-    "RYUK_IMAGE",
-    "RYUK_PRIVILEGED",
     "RYUK_DISABLED",
     "RYUK_DOCKER_SOCKET",
+    "RYUK_IMAGE",
+    "RYUK_PRIVILEGED",
     "RYUK_RECONNECTION_TIMEOUT",
+    "SLEEP_TIME",
+    "TIMEOUT",
+    # Public API of this module:
+    "testcontainers_config",
 ]

core/testcontainers/core/container.py

@@ -65,11 +65,38 @@ def with_env_file(self, env_file: Union[str, PathLike]) -> Self:
             self.with_env(key, value)
         return self
 
-    def with_bind_ports(self, container: int, host: Optional[int] = None) -> Self:
+    def with_bind_ports(self, container: Union[str, int], host: Optional[Union[str, int]] = None) -> Self:
+        """
+        Bind container port to host port
+
+        :param container: container port
+        :param host: host port
+
+        :doctest:
+
+        >>> from testcontainers.core.container import DockerContainer
+        >>> container = DockerContainer("nginx")
+        >>> container = container.with_bind_ports("8080/tcp", 8080)
+        >>> container = container.with_bind_ports("8081/tcp", 8081)
+
+        """
         self.ports[container] = host
         return self
 
-    def with_exposed_ports(self, *ports: int) -> Self:
+    def with_exposed_ports(self, *ports: Union[str, int]) -> Self:
+        """
+        Expose ports from the container without binding them to the host.
+
+        :param ports: ports to expose
+
+        :doctest:
+
+        >>> from testcontainers.core.container import DockerContainer
+        >>> container = DockerContainer("nginx")
+        >>> container = container.with_exposed_ports("8080/tcp", "8081/tcp")
+
+        """
+
         for port in ports:
             self.ports[port] = None
         return self

core/testcontainers/core/docker_client.py

@@ -19,7 +19,7 @@
 import urllib
 import urllib.parse
 from collections.abc import Iterable
-from typing import Callable, Optional, TypeVar, Union
+from typing import Any, Callable, Optional, TypeVar, Union, cast
 
 import docker
 from docker.models.containers import Container, ContainerCollection
@@ -59,7 +59,7 @@ class DockerClient:
     Thin wrapper around :class:`docker.DockerClient` for a more functional interface.
     """
 
-    def __init__(self, **kwargs) -> None:
+    def __init__(self, **kwargs: Any) -> None:
         docker_host = get_docker_host()
 
         if docker_host:
@@ -82,14 +82,14 @@ def run(
         self,
         image: str,
         command: Optional[Union[str, list[str]]] = None,
-        environment: Optional[dict] = None,
-        ports: Optional[dict] = None,
+        environment: Optional[dict[str, str]] = None,
+        ports: Optional[dict[int, Optional[int]]] = None,
         labels: Optional[dict[str, str]] = None,
         detach: bool = False,
         stdout: bool = True,
         stderr: bool = False,
         remove: bool = False,
-        **kwargs,
+        **kwargs: Any,
     ) -> Container:
         # If the user has specified a network, we'll assume the user knows best
         if "network" not in kwargs and not get_docker_host():
@@ -112,7 +112,7 @@ def run(
         return container
 
     @_wrapped_image_collection
-    def build(self, path: str, tag: str, rm: bool = True, **kwargs) -> tuple[Image, Iterable[dict]]:
+    def build(self, path: str, tag: str, rm: bool = True, **kwargs: Any) -> tuple[Image, Iterable[dict[str, Any]]]:
         """
         Build a Docker image from a directory containing the Dockerfile.
 
@@ -151,43 +151,43 @@ def find_host_network(self) -> Optional[str]:
                         except ipaddress.AddressValueError:
                             continue
                         if docker_host in subnet:
-                            return network.name
+                            return cast(str, network.name)
         except (ipaddress.AddressValueError, OSError):
             pass
         return None
 
-    def port(self, container_id: str, port: int) -> int:
+    def port(self, container_id: str, port: int) -> str:
         """
         Lookup the public-facing port that is NAT-ed to :code:`port`.
         """
         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 port_mappings[0]["HostPort"]
+            raise ConnectionError(f"Port mapping for container {container_id} and port {port} is not available")
+        return cast(str, port_mappings[0]["HostPort"])
 
-    def get_container(self, container_id: str) -> Container:
+    def get_container(self, container_id: str) -> dict[str, Any]:
         """
         Get the container with a given identifier.
         """
         containers = self.client.api.containers(filters={"id": container_id})
         if not containers:
             raise RuntimeError(f"Could not get container with id {container_id}")
-        return containers[0]
+        return cast(dict[str, Any], containers[0])
 
     def bridge_ip(self, container_id: str) -> str:
         """
         Get the bridge ip address for a container.
         """
         container = self.get_container(container_id)
         network_name = self.network_name(container_id)
-        return container["NetworkSettings"]["Networks"][network_name]["IPAddress"]
+        return str(container["NetworkSettings"]["Networks"][network_name]["IPAddress"])
 
     def network_name(self, container_id: str) -> str:
         """
         Get the name of the network this container runs on
         """
         container = self.get_container(container_id)
-        name = container["HostConfig"]["NetworkMode"]
+        name = str(container["HostConfig"]["NetworkMode"])
         if name == "default":
             return "bridge"
         return name
@@ -198,7 +198,7 @@ def gateway_ip(self, container_id: str) -> str:
         """
         container = self.get_container(container_id)
         network_name = self.network_name(container_id)
-        return container["NetworkSettings"]["Networks"][network_name]["Gateway"]
+        return str(container["NetworkSettings"]["Networks"][network_name]["Gateway"])
 
     def get_connection_mode(self) -> ConnectionMode:
         """
@@ -233,11 +233,15 @@ def host(self) -> str:
             url = urllib.parse.urlparse(self.client.api.base_url)
         except ValueError:
             return "localhost"
-        if "http" in url.scheme or "tcp" in url.scheme and url.hostname:
+
+        is_http_scheme = "http" in url.scheme
+        is_tcp_scheme_with_hostname = "tcp" in url.scheme and url.hostname
+        if is_http_scheme or is_tcp_scheme_with_hostname:
             # see https://github.com/testcontainers/testcontainers-python/issues/415
-            if url.hostname == "localnpipe" and utils.is_windows():
+            hostname = url.hostname
+            if not hostname or (hostname == "localnpipe" and utils.is_windows()):
                 return "localhost"
-            return 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:
@@ -251,9 +255,9 @@ def login(self, auth_config: DockerAuthInfo) -> None:
         login_info = self.client.login(**auth_config._asdict())
         LOGGER.debug(f"logged in using {login_info}")
 
-    def client_networks_create(self, name: str, param: dict):
+    def client_networks_create(self, name: str, param: dict[str, Any]) -> dict[str, Any]:
         labels = create_labels("", param.get("labels"))
-        return 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/testcontainers/core/generic.py

@@ -10,7 +10,7 @@
 #    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 typing import Any, Optional
 from urllib.parse import quote
 
 from testcontainers.core.container import DockerContainer
@@ -55,7 +55,7 @@ def _create_connection_url(
         host: Optional[str] = None,
         port: Optional[int] = None,
         dbname: Optional[str] = None,
-        **kwargs,
+        **kwargs: Any,
     ) -> str:
         if raise_for_deprecated_parameter(kwargs, "db_name", "dbname"):
             raise ValueError(f"Unexpected arguments: {','.join(kwargs)}")

core/testcontainers/core/network.py

@@ -11,7 +11,7 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 import uuid
-from typing import Optional
+from typing import Any, Optional
 
 from testcontainers.core.docker_client import DockerClient
 
@@ -21,12 +21,14 @@ class Network:
     Network context manager for programmatically connecting containers.
     """
 
-    def __init__(self, docker_client_kw: Optional[dict] = None, docker_network_kw: Optional[dict] = None) -> None:
+    def __init__(
+        self, docker_client_kw: Optional[dict[str, Any]] = None, docker_network_kw: Optional[dict[str, Any]] = None
+    ):
         self.name = str(uuid.uuid4())
         self._docker = DockerClient(**(docker_client_kw or {}))
         self._docker_network_kw = docker_network_kw or {}
 
-    def connect(self, container_id: str, network_aliases: Optional[list] = None):
+    def connect(self, container_id: str, network_aliases: Optional[list[str]] = None) -> None:
         self._network.connect(container_id, aliases=network_aliases)
 
     def remove(self) -> None:
@@ -40,5 +42,5 @@ def create(self) -> "Network":
     def __enter__(self) -> "Network":
         return self.create()
 
-    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:  # type: ignore[no-untyped-def]
         self.remove()