feat(core): Extend container support

[Tranquility2]

Overview

So basically as you can see from the title this adds a functionally that I think is super useful, supporting working with Dockerfile for achieving even more compatibility with custom images.

from testcontainers.core.container import DockerContainer
from testcontainers.core.image import DockerImage

with DockerImage(path=".", tag="new_image") as image  # tag is optional
    with DockerContainer(image=image.name) as container:
        ...

The created image is cleaned and any any intermediate containers are removed.

Background

I'm a bit biased as I originally started from working on my own project: https://github.com/Tranquility2/dockerr that has some very clear similarities with testcontainers.
I noticed testcontainers in Go and Java (for example) indeed support Dockerfile (and even some extra compatibility modes like Dockerfile DSL) so decided to take the time and add this to testcontainers-python as well.

Goal

The end goal will be supporting custom images that can be tested, in my use case:

1. FastAPI / Flask
2. Amazon Lambdas (using the built-in runtime interface emulator

Work Plan

This is what I'm planning to do

• Add this PR to support the core image
• Improve custom image support but easier usage, for example:

from testcontainers.core.generic import CustomContainer

with CustomContainer(tag="my-custom-image:latest", path="/path/to/Dockerfile") as server: # tag is optional
    server_url = custom_container.get_url()

• Add some support for get_api to get the full user experience
• Add Module for FastAPI
• Add Module for Amazon Lambda

Future work

• Add custom image support for more capabilities like the Dockerfile DSL

---

Any feedback is welcomed and I'll be happy to update/fix as needed.

Update
Took me some time but I did found #83 which is quite old and #455 which takes a different approach from what I have here.

Update 2 - Please note this proposal emphasize on 2 things

1. Cleanup as much as possible
2. Minimal changes to the current workflow. DockerContainer basically remains the same, this limits maintenance required and allows for easier integration.

Update 3 - Hopefully done ,this PR includes multiple feats

• Image build support (using Dockerfile)
• Added SrvContainer
• Added FastAPI module
• Added AWS Lambda module

[alexanderankin]

rather than untagging - why not never tag and let it be cleaned up by system prune? im just thinking aloud - not 100% confident about how it works in java but the other pr for custom image also does what you did here, just challenging yall to think of something without the tagging/removal issue.

[Tranquility2]

Let me try and follow up on this notion (sorry for the wall of text)

let me start with saying I do think its possible, the tag in the image is not mandatory, and if kept as a ref to the image object we can probably use the id to be passed as the image to DockerContainer, this will have a very different workflow from what I presented in this commit as we don't really need a context manager. now having established this:

• as a concept I think tests should cleanup after themself
  -- for example in the case where we ran similar tests one after the other, in our case a very similar image with small changes and I want to make sure it does get rebuilt in the process, you can argue that sometimes we do want to reuse the image but from my experience a clean slate is preferable.
  -- system prune is great but I tend to keep it for when I ran out of space or more generally when something bad happened, as a user I don't want to run it after each test to keep a neat and clean env. (not saying it not possible ofc, just less preferable imo)
• we can expanded this and draw similarities to the DockerContainer object. as part of its workflow on stop it also does a targeted remove, so I can argue we are simply keeping the same behavior for but containers and images. or do we consider maybe not removing the container at the end and also letting the user clean it later? (I know this is kind of a stretch)
• regarding how testcontainers-java handle this, They use a more more elaborated system to handle images (for ref https://github.com/testcontainers/testcontainers-java/tree/d3b0df2d89ee349890c94b0ce220a167c82ddf51/core/src/main/java/org/testcontainers/images) I am not sure we can or should do exactly what they are doing (at least at this stage) I did invest some time digging the code (I'm no java expert) and they do have https://github.com/testcontainers/testcontainers-java/blob/d3b0df2d89ee349890c94b0ce220a167c82ddf51/core/src/main/java/org/testcontainers/images/builder/ImageFromDockerfile.java#L55 private boolean deleteOnExit = true; and checking with the official docs https://java.testcontainers.org/features/creating_images/#automatic-deletion confirms they do intend on removing the temp images, but I can't pinpoint the exact location they are doing it (the only clue I have is that it happens on the JVM shutdown).

TL;DR
I think the tagging can be changed to be optional (need to do some testing) and the removal is not an issue but a very important feature (implemented and included on the java version) which can be optional (defaults to true)

[Tranquility2]

Image creation is now based on id as advised by @alexanderankin (tag is optional and not critical to the build flow)

[Tranquility2]

Image cleanup is now optional (defaults to True to facilitate the use-cases known to me)

[Tranquility2]

Please note that test_core.py now take double the time (~15sec on my machine)

[alexanderankin]

for fast api, i can imagine the plan is to create a Testcontainer for an intree service to test against from other intree services' test suites. what is the plan for aws lambda exactly?

[Tranquility2]

I think its basically extending the paradigm for testcontainers-python.
Instead of only providing the supporting services for testing something, one can now test a service ("dockerized" one).
I updated the doctest for SrvContainer (and code ofc) to better reflect this, so I hope it will be more clear, any python web service could benefit from testing it like this + we can provide supported services as neeed, for example:

with RedisContainer() as redis_container:
    redis_params = redis_container.get_client_params()
    with FastAPIContainer() as server: # this is very close to SrvContainer
        # do some calls to the server and utilize the fact that its connected to redis

*at this point I'm not as sure we will need a module for FastAPI but still needs to think about it

Now regarding aws lambda its very similar to the localstack module already available, and very ironically will probably also be used with it quite a lot. if we look at an example:

with LocalStackContainer() as localstack:
    dynamo_client = localstack.get_client("dynamodb")
    # prepare something in dynamo
    with AwsLambdaContainer() as lambda:
        # run some requests to http://localhost:9000/2015-03-31/functions/function/invocations
        # this way we can be validating flow with dynamo 
        # and maybe even checking the changes on dynamo itself

*this is static URL in all AWS lambdas
**AwsLambdaContainer will be a new module
***similar=have all the same env vars, as its all AWS eco system

[Tranquility2]

Decided to implement a module for FastAPI, I think it will be good even on a didactic level for anyone who needs to use it, as it include a working example and all the sources.

[Tranquility2]

1. Added Module for Amazon Lambda
2. Reorganized the PR commits:

feat(core): Added AWS Lambda module
feat(core): Added FastAPI module
feat(core): Added SrvContainer
feat(core): Image build support (using Dockerfile)

They now reflect better the improvements and the work that was done.