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 https://github.com/testcontainers/testcontainers-python/pull/810 🙂

[codecov[bot]]

Codecov Report

:x: Patch coverage is 78.26087% with 35 lines in your changes missing coverage. Please review. :warning: 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 :warning:
core/testcontainers/core/wait_strategies.py	76.59%	8 Missing and 3 partials :warning:
core/testcontainers/core/container.py	76.47%	3 Missing and 1 partial :warning:

Additional details and impacted files

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

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: 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.

[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