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]

Codecov Report

❌ Patch coverage is 95.02488% with 20 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.76%. Comparing base (bb646e9) to head (11a8f5d).
⚠️ 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 ⚠️

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     

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

this is amazing - adding those data classes takes a huge step forward to moving us away from the python docker client and we cannot add enough distance between us. if we can incorporate more of these data classes and really minimize the API items we inherited from the python client - can probably get much closer to a uniform implementation with other languages which are more stable than this one. thank you for your work on this!!!

[alexanderankin]

do we need to care about invalidating?

[VictorCavichioli]

This is something I was thinking about, and I guess the answer depends, of course, network conditions, container status, and statistics can change along the way. But in a test scenario, you would usually create the container, run your tests, and then destroy it. I see that this new functionality would be used to collect the status at the end of the test, so this simple cache helps avoid extra overhead during test execution. What do you think?

Otherwise, we have a few options here. The easiest one would be to always execute the docker inspect command and return fresh information, or we could define a default TTL for the data so that after this period, the next call retrieves updated data or something like this.

[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!