Merge remote-tracking branch 'testcontainers/main' into reusable_containers

Author: matthiasschaub

.github/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "4.10.0"
+    ".": "4.12.0"
 }

.github/workflows/ci-core.yml

@@ -1,4 +1,4 @@
-# Contrinuous Integration for the core package
+# Continuous Integration for the core package
 
 name: core
 
@@ -25,6 +25,8 @@ jobs:
         run: poetry install --all-extras
       - name: Run twine check
         run: poetry build && poetry run twine check dist/*.tar.gz
+      - name: Set up Docker
+        uses: docker/setup-docker-action@v4
       - name: Run tests
         run: make core/tests
       - name: Rename coverage file

.github/workflows/ci-lint.yml

@@ -20,9 +20,14 @@ jobs:
       - name: Install Python dependencies
         run: poetry install --no-interaction
       - name: Execute pre-commit handler
+        continue-on-error: true
         run: |
           poetry run pre-commit run check-toml
           poetry run pre-commit run trailing-whitespace
           poetry run pre-commit run end-of-file-fixer
           poetry run pre-commit run ruff
           poetry run pre-commit run ruff-format
+      - name: Execute mypy
+        run: |
+          make mypy-core-report
+          make mypy-core

.gitignore

@@ -72,3 +72,6 @@ venv
 .python-version
 .env
 .github-token
+
+# docs build
+site/

CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## [4.12.0](https://github.com/testcontainers/testcontainers-python/compare/testcontainers-v4.11.0...testcontainers-v4.12.0) (2025-07-21)
+
+
+### Features
+
+* **main:** New Testcontainers Python Docs Site ([#822](https://github.com/testcontainers/testcontainers-python/issues/822)) ([a6bdf0e](https://github.com/testcontainers/testcontainers-python/commit/a6bdf0ef84643074fbc7edf3a75936ce3f1d0880))
+* make config monkeypatchable, fix config related startup issues ([#833](https://github.com/testcontainers/testcontainers-python/issues/833)) ([ff6a32d](https://github.com/testcontainers/testcontainers-python/commit/ff6a32db803046db8d89ba5a7157bf573d9f25c2))
+* **modules:** add OpenFGA module ([#762](https://github.com/testcontainers/testcontainers-python/issues/762)) ([0b7b482](https://github.com/testcontainers/testcontainers-python/commit/0b7b482f9ec807e87fd43d1372226fa43eb4ed7c))
+* set multiple variables via keyword args ([#804](https://github.com/testcontainers/testcontainers-python/issues/804)) ([1532df5](https://github.com/testcontainers/testcontainers-python/commit/1532df5e9094d15b9f3e9233e7f5843d8bc24386))
+
+
+### Bug Fixes
+
+* **core:** mypy ([#810](https://github.com/testcontainers/testcontainers-python/issues/810)) ([b816762](https://github.com/testcontainers/testcontainers-python/commit/b816762b9a548033b065c3f46267c289a560f6ed))
+* Enable mypy in the CI ([#842](https://github.com/testcontainers/testcontainers-python/issues/842)) ([ef65bd1](https://github.com/testcontainers/testcontainers-python/commit/ef65bd113b564bce614aaf6df13bbf5339b9bc58))
+* just use the getLogger API and do not override logger settings ([#836](https://github.com/testcontainers/testcontainers-python/issues/836)) ([f467c84](https://github.com/testcontainers/testcontainers-python/commit/f467c842b851613b9a087bd5f9a08d8c39577cb8))
+
+
+### Documentation
+
+* missing compose html from old docs ([#776](https://github.com/testcontainers/testcontainers-python/issues/776)) ([d749fc6](https://github.com/testcontainers/testcontainers-python/commit/d749fc69b32715742d834c003ee6893e2077753a))
+
+## [4.11.0](https://github.com/testcontainers/testcontainers-python/compare/testcontainers-v4.10.0...testcontainers-v4.11.0) (2025-06-15)
+
+
+### Features
+
+* **core:** Protocol support for container port bind and expose ([#690](https://github.com/testcontainers/testcontainers-python/issues/690)) ([a0d4317](https://github.com/testcontainers/testcontainers-python/commit/a0d4317643005dde4f344eccbfc56c062e83bf05))
+* DockerContainer initializer to accept its private members as kwargs ([#809](https://github.com/testcontainers/testcontainers-python/issues/809)) ([e7feb53](https://github.com/testcontainers/testcontainers-python/commit/e7feb53fe532b6d32d5d0c5a5d517249f8e7de50))
+
+
+### Bug Fixes
+
+* **compose:** use provided docker command instead of default ([#785](https://github.com/testcontainers/testcontainers-python/issues/785)) ([0ae704a](https://github.com/testcontainers/testcontainers-python/commit/0ae704a24de440b715d5f3c11eaa4f18ccd437b5))
+* **core:** Add kwargs to image build ([#708](https://github.com/testcontainers/testcontainers-python/issues/708)) ([cc02f94](https://github.com/testcontainers/testcontainers-python/commit/cc02f9444b41efa62836b21210b07aee1da94d0b))
+* **core:** change with_command type to include list of strings ([#789](https://github.com/testcontainers/testcontainers-python/issues/789)) ([f7c29cb](https://github.com/testcontainers/testcontainers-python/commit/f7c29cb913e4d42d535783c3aa0f3566d4e543bf))
+* **core:** Determine docker socket for rootless docker ([#779](https://github.com/testcontainers/testcontainers-python/issues/779)) ([6817582](https://github.com/testcontainers/testcontainers-python/commit/6817582bf67ed36448b69019ab897c50ae80e7e1))
+* **core:** Typing in docker_client ([#702](https://github.com/testcontainers/testcontainers-python/issues/702)) ([e8bf224](https://github.com/testcontainers/testcontainers-python/commit/e8bf2244c7210e31b34e5fecf2602fdd1b8c0834))
+* **core:** Typing in generic + network ([#700](https://github.com/testcontainers/testcontainers-python/issues/700)) ([2061912](https://github.com/testcontainers/testcontainers-python/commit/2061912e67705be801136f349f372f542a1f262f))
+* **core:** Typing in version ([#701](https://github.com/testcontainers/testcontainers-python/issues/701)) ([9dc2a02](https://github.com/testcontainers/testcontainers-python/commit/9dc2a02ca9b9ffbaacfd7de79ec9f78175758ec0))
+* **core:** wait in test core registry ([#812](https://github.com/testcontainers/testcontainers-python/issues/812)) ([b574c0e](https://github.com/testcontainers/testcontainers-python/commit/b574c0e0a11d57c8c56aef448292f8c2fc233078))
+* **modules:** fix cosmosdb failure ([#827](https://github.com/testcontainers/testcontainers-python/issues/827)) ([dafcbed](https://github.com/testcontainers/testcontainers-python/commit/dafcbed7608e857bebcdd0b4638bec27abadc693))
+* **modules:** update chroma version ([#826](https://github.com/testcontainers/testcontainers-python/issues/826)) ([b7d41dd](https://github.com/testcontainers/testcontainers-python/commit/b7d41ddc5742dd380b6e01c712a02b044a64cbb3))
+* **rabbitmq:** correct pika pypi reference ([#817](https://github.com/testcontainers/testcontainers-python/issues/817)) ([e90d308](https://github.com/testcontainers/testcontainers-python/commit/e90d30826fb7d7cf3cc7db39a86465d448aaa6e0))
+* **registry:** module typed ([#811](https://github.com/testcontainers/testcontainers-python/issues/811)) ([6b11268](https://github.com/testcontainers/testcontainers-python/commit/6b1126884c82529a93bd55030374d322dd0870bc))
+* use connection mode override function in config ([#775](https://github.com/testcontainers/testcontainers-python/issues/775)) ([ab2a1ab](https://github.com/testcontainers/testcontainers-python/commit/ab2a1abd957ffb35719f673a7674df83287f1545)), closes [#774](https://github.com/testcontainers/testcontainers-python/issues/774)
+
 ## [4.10.0](https://github.com/testcontainers/testcontainers-python/compare/testcontainers-v4.9.2...testcontainers-v4.10.0) (2025-04-02)
 
 

Dockerfile.docs

@@ -0,0 +1,5 @@
+FROM python:3.11-slim
+
+RUN pip install poetry
+
+WORKDIR /docs

Makefile

@@ -31,7 +31,10 @@ coverage:  ## Target to combine and report coverage.
 lint:  ## Lint all files in the project, which we also run in pre-commit
 	poetry run pre-commit run -a
 
-mypy-core-report:
+mypy-core:  ## Run mypy on the core package
+	poetry run mypy --config-file pyproject.toml core
+
+mypy-core-report:  ## Generate a report for mypy on the core package
 	poetry run mypy --config-file pyproject.toml core | poetry run python scripts/mypy_report.py
 
 docs: ## Build the docs for the project
@@ -68,3 +71,39 @@ clean-all: clean ## Remove all generated files and reset the local virtual envir
 .PHONY: help
 help:  ## Display command usage
 	@grep -E '^[0-9a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+## --------------------------------------
+
+DOCS_CONTAINER=mkdocs-container
+DOCS_IMAGE=mkdocs-poetry
+DOCS_DOCKERFILE := Dockerfile.docs
+
+.PHONY: clean-docs
+clean-docs:
+	@echo "Destroying docs"
+	@if docker ps -a --format '{{.Names}}' | grep -q '^$(DOCS_CONTAINER)$$'; then \
+		docker rm -f $(DOCS_CONTAINER); \
+	fi
+	@if docker images -q $(DOCS_IMAGE) | grep -q .; then \
+		docker rmi $(DOCS_IMAGE); \
+	fi
+
+.PHONY: docs-ensure-image
+docs-ensure-image:
+	@if [ -z "$$(docker images -q $(DOCS_IMAGE))" ]; then \
+		docker build -f $(DOCS_DOCKERFILE) -t $(DOCS_IMAGE) . ; \
+	fi
+
+.PHONY: serve-docs
+serve-docs: docs-ensure-image
+	docker run --rm --name $(DOCS_CONTAINER) -it -p 8000:8000 \
+		-v $(PWD):/testcontainers-go \
+		-w /testcontainers-go \
+		$(DOCS_IMAGE) bash -c "\
+			cd docs && poetry install --no-root && \
+			poetry run mkdocs serve -f ../mkdocs.yml -a 0.0.0.0:8000"
+
+# Needed if dependencies are added to the docs site
+.PHONY: export-docs-deps
+export-docs-deps:
+	cd docs && poetry export --without-hashes --output requirements.txt

README.md

@@ -41,10 +41,20 @@ See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for more details.
 
 ## Configuration
 
+You can set environment variables to configure the library behaviour:
+
 | Env Variable                            | Example                     | Description                                                                        |
 | --------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------- |
 | `TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE` | `/var/run/docker.sock`      | Path to Docker's socket used by ryuk                                               |
 | `TESTCONTAINERS_RYUK_PRIVILEGED`        | `false`                     | Run ryuk as a privileged container                                                 |
 | `TESTCONTAINERS_RYUK_DISABLED`          | `false`                     | Disable ryuk                                                                       |
 | `RYUK_CONTAINER_IMAGE`                  | `testcontainers/ryuk:0.8.1` | Custom image for ryuk                                                              |
 | `RYUK_RECONNECTION_TIMEOUT`             | `10s`                       | Reconnection timeout for Ryuk TCP socket before Ryuk reaps all dangling containers |
+
+Alternatively you can set the configuration during runtime:
+
+```python
+from testcontainers.core import testcontainers_config
+
+testcontainers_config.ryuk_docker_socket = "/home/user/docker.sock"
+```

compose.rst

@@ -0,0 +1,4 @@
+Docker Compose
+==============
+
+Docker compose is described in :ref:`Testcontainers Core`.

conf.py

@@ -33,6 +33,7 @@
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
+    "sphinx.ext.autosectionlabel",
 ]
 
 # Configure autodoc to avoid excessively long fully-qualified names.
@@ -166,4 +167,5 @@
 
 nitpick_ignore = [
     ("py:class", "typing_extensions.Self"),
+    ("py:class", "docker.models.containers.ExecResult"),
 ]