feat(core): Wait strategies foundation

[terry-docker]

Aligns testcontainers-python with the testcontainers community standard wait strategy pattern used across Java, Go, and other implementations. This provides a consistent developer experience and better maintainability.

Examples

From:

wait_for_logs(container, "Test Sample Image")

To:

from testcontainers.core.wait_strategies import LogMessageWaitStrategy

container.waiting_for(LogMessageWaitStrategy("Server started"))

Backward Compatibility

No breaking changes - all existing code continues working
Deprecation warnings added to wait_for_logs() and @wait_container_is_ready
Clear migration path provided in warning messages

New:

core/testcontainers/core/wait_strategies.py - Strategy implementations
core/tests/test_wait_strategies*.py - Comprehensive test coverage

Modified:

core/testcontainers/core/container.py - Added waiting_for() method
core/testcontainers/compose/compose.py - Added compose wait strategy support
core/testcontainers/core/waiting_utils.py - Base classes and protocol

Future Strategies to quickly follow

Foundation enables community-standard wait strategies:
HttpWaitStrategy, HealthcheckWaitStrategy, PortWaitStrategy, CompositeWaitStrategy

Testing

Unit tests with parameterized scenarios
Integration tests with real Docker containers
Protocol compliance verification
Backward compatibility validation

[terry-docker]

Notes: Mypy errors got crazy and circular, so I skipped them for now to focus on getting the wait strategies up without the massive changes caused by bringing those core files inline with mypy.

Also the comments are representing some strategies not included here, but I do have working versions ready to be brought in 🥳

[Tranquility2]

I assume mypy needs all the good stuff on #810 🙂

[codecov]

Codecov Report

❌ Patch coverage is 78.26087% with 35 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@d40473f). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
core/testcontainers/core/waiting_utils.py	79.38%	16 Missing and 4 partials ⚠️
core/testcontainers/core/wait_strategies.py	76.59%	8 Missing and 3 partials ⚠️
core/testcontainers/core/container.py	76.47%	3 Missing and 1 partial ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #838   +/-   ##
=======================================
  Coverage        ?   81.79%           
=======================================
  Files           ?       14           
  Lines           ?      890           
  Branches        ?      140           
=======================================
  Hits            ?      728           
  Misses          ?      127           
  Partials        ?       35           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[alexanderankin]

if i can merge 810 and rebase this on top of that that would be ideal. i hope to be done with #810 on sunday or monday and this can follow shortly after

[terry-docker]

Sure, I can add the missing new mypy types on this PR too.

[rhoban13]

This is great - thanks!

[rhoban13]

I wonder if WaitStrategyTarget & WaitStrategy might be split into their own module - somewhat separating it from the now deprecated functions in here. That might help simplify when time comes for its eventual removal.

[alexanderankin]

If we can avoid changing files it preserves git history better. If this file was called wait or waiting it would have been better but I don't see removing utils or reorganizing code a super high priority

[terry-docker]

I was on the fence about this, they're needed for the backwards compatibility but I honestly don't have strong feelings about where to have WaitStrategyTarget and WaitStrategy live

[alexanderankin]

made some progress on conflicts here today

[alexanderankin]

if i cant figure out how to make this go away, i might just disable code coverage at all - it is supposed to be useful tool not a procrustean bed (https://www.dictionary.com/browse/procrustean-bed)

im trying to copy code out of the ui and its not working because its in the way. </vent>

[alexanderankin]

backed up to https://github.com/testcontainers/testcontainers-python/tree/archive/backup-wait-strategy-foundation

.

[alexanderankin]

@terry-docker if you want to edit the git history that is up to you or however you want to merge this - currently it does not give you credit but it is mergeable - i will take a look when i have time