Feature: Timeout on command execution

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.

Start at DockerContainer.exec and docs/features/executing_commands.md, then compare the documented timeout example with docker-py Container.exec_run and its limitations. Done means exec() accepts a timeout, raises TimeoutError when the deadline is exceeded, and does not leave the test run blocked indefinitely.