feat(compose): add structured container inspect information

[VictorCavichioli]

Summary This PR adds the ability to retrieve detailed container information from docker inspect in a structured format for ComposeContainer objects, with lazy loading and caching for optimal performance.

Related with #857

[alexanderankin]

ok so i have just one small issue with this and its that i thought we wanted to give the same information from compose and container about the container - so i think these same data classes need to be returned from "DockerContainer" class which is in core package too, right? I think if we can do that, we will necessarily find these dataclasses a better home as well, which i think needs to be close to the docker client (not the docker python library but the docker client abstraction in this library).

looks very promising so far.

[alexanderankin]

i can review java as well, i have not done that before writing the above comment.

[VictorCavichioli]

ok so i have just one small issue with this and its that i thought we wanted to give the same information from compose and container about the container - so i think these same data classes need to be returned from "DockerContainer" class which is in core package too, right? I think if we can do that, we will necessarily find these dataclasses a better home as well, which i think needs to be close to the docker client (not the docker python library but the docker client abstraction in this library).

looks very promising so far.

Yes, you’re right, my first thought was to add it to compose.py, since that’s where I noticed the container state information was missing. However, in Java, the implementation is actually in a generic container interface called GenericContainer, and later the ComposeContainer extends that class. So you’re absolutely correct , I’ll move it to the core module.

However, I’m unsure about the best place to put the dataclasses. Given the files we currently have, these models don’t seem to fit perfectly anywhere. Should we perhaps create a separate file for them, something like models.py or similar? Or maybe place them in utils.py instead?

[alexanderankin]

I was thinking here tbh https://github.com/testcontainers/testcontainers-python/blob/main/core/testcontainers/core/docker_client.py

assuming these are models of API objects as described by the docker api https://docs.docker.com/reference/api/engine/version/v1.51/

[VictorCavichioli]

I was thinking here tbh https://github.com/testcontainers/testcontainers-python/blob/main/core/testcontainers/core/docker_client.py

Okay, good to know, working on that, thanks.

[VictorCavichioli]

I was thinking here tbh https://github.com/testcontainers/testcontainers-python/blob/main/core/testcontainers/core/docker_client.py

assuming these are models of API objects as described by the docker api https://docs.docker.com/reference/api/engine/version/v1.51/

Hi, now is full compliant with docker api response and all dataclasses are in docker_client.py

[codecov[bot]]

Codecov Report

:x: Patch coverage is 95.02488% with 20 lines in your changes missing coverage. Please review. :white_check_mark: Project coverage is 83.76%. Comparing base (bb646e9) to head (11a8f5d). :warning: Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
core/testcontainers/core/docker_client.py	94.84%	13 Missing and 7 partials :warning:

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #897      +/-   ##
==========================================
+ Coverage   79.78%   83.76%   +3.98%     
==========================================
  Files          14       14              
  Lines        1182     1583     +401     
  Branches      184      237      +53     
==========================================
+ Hits          943     1326     +383     
- Misses        197      209      +12     
- Partials       42       48       +6     

: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]

i will try to look at this within a week or so, currently (not very) sick and busy with work

[VictorCavichioli]

i will try to look at this within a week or so, currently (not very) sick and busy with work

Take all the time you need, I wish you a speedy recovery!

[VictorCavichioli]

Hi @alexanderankin, sorry to bother you with this, but do you have any news about this PR?

[alexanderankin]

yes i need it badly to fix the Any typing in the waitable/wait target interface. very busy otherwise i would have merged and released. i planned to get to it several weeks ago. I'm thinking about how to version things. how to handle breaking changes (other PRs i said id merge, i dont think this one)

On Tue, Oct 28, 2025 at 1:51 PM Victor Cavichioli @.***> wrote:

VictorCavichioli left a comment (testcontainers/testcontainers-python#897) https://github.com/testcontainers/testcontainers-python/pull/897#issuecomment-3457750184

Hi @alexanderankin https://github.com/alexanderankin, sorry to bother you with this, but do you have any news about this PR?

— Reply to this email directly, view it on GitHub https://github.com/testcontainers/testcontainers-python/pull/897#issuecomment-3457750184, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACECGJF7RX43BX7PXKO3Z7L3Z6ULDAVCNFSM6AAAAACIN3LWU2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTINJXG42TAMJYGQ . You are receiving this because you were mentioned.Message ID: @.***>

[VictorCavichioli]

yes i need it badly to fix the Any typing in the waitable/wait target interface. very busy otherwise i would have merged and released. i planned to get to it several weeks ago. I'm thinking about how to version things. how to handle breaking changes (other PRs i said id merge, i dont think this one) … On Tue, Oct 28, 2025 at 1:51 PM Victor Cavichioli @.> wrote: VictorCavichioli left a comment (testcontainers/testcontainers-python#897) <#897 (comment)> Hi @alexanderankin https://github.com/alexanderankin, sorry to bother you with this, but do you have any news about this PR? — Reply to this email directly, view it on GitHub <#897 (comment)>, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACECGJF7RX43BX7PXKO3Z7L3Z6ULDAVCNFSM6AAAAACIN3LWU2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTINJXG42TAMJYGQ . You are receiving this because you were mentioned.Message ID: @.>

Okay, good to know that, actually I noticed that one of the make things failed so I'm trying to solve it anyway, make docs raises this:

Warning, treated as error:
testcontainers-python/core/testcontainers/core/container.py:docstring of testcontainers.core.container.DockerContainer.get_container_info:1:py:class reference target not found: testcontainers.core.docker_client.ContainerInspectInfo
make: *** [Makefile:41: docs] Error 2

So I'm trying to understand what is the pattern expected, looking into the docstrings in other python functions it looks pretty similar