What are you trying to do?

The DockerContainer.exec() method does not support a timeout parameter, even though the documentation explicitly describes this functionality:

with GenericContainer("alpine:latest") as container:
 try:
 exit_code, output = container.exec(
 ["sleep", "10"],
 timeout=5 # Timeout in seconds
 )
 except TimeoutError:
 print("Command timed out")

However, the actual implementation simply forwards to docker-py's exec_run without accepting any additional keyword arguments:

def exec(self, command: Union[str, list[str]]) -> ExecResult:
 if not self._container:
 raise ContainerStartException("Container should be started before executing a command")
 return self._container.exec_run(command)

We'd like exec() to support a timeout so that commands that hang or take too long don't block test runs indefinitely.

Why should it be done this way?

Without a timeout, any exec() call that hangs (e.g. a command waiting on a resource that never becomes available) will block the test process forever with no way to recover other than killing the process externally.

Unfortunately this isn't a simple pass through - the underlying docker-py Container.exec_run() also does not expose a timeout parameter. So this would need a client-side implementation, for example wrapping the call with concurrent.futures.ThreadPoolExecutor and a deadline, or using exec_run(socket=True) with a socket-level timeout.

Just like the timeout for a subprocess.run run doesn't guarantee closing the process after the timeout, so will this.

I'm happy to open a PR for this, but wanted to gain agreement on the issue first before submitting code.