diff --git a/compose.rst b/compose.rst new file mode 100644 index 000000000..b85303bb8 --- /dev/null +++ b/compose.rst @@ -0,0 +1,4 @@ +Docker Compose +============== + +Docker compose is described in :ref:`Testcontainers Core`. diff --git a/conf.py b/conf.py index 35c2ae9c5..90d000bd6 100644 --- a/conf.py +++ b/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. diff --git a/core/README.rst b/core/README.rst index 5176ce078..858345216 100644 --- a/core/README.rst +++ b/core/README.rst @@ -3,22 +3,28 @@ Testcontainers Core :code:`testcontainers-core` is the core functionality for spinning up Docker containers in test environments. -.. autoclass:: testcontainers.core.container.DockerContainer - :members: with_bind_ports, with_exposed_ports +.. automodule:: testcontainers.core.container + :members: + :undoc-members: + +.. autoclass:: testcontainers.core.network.Network + :members: -.. note:: - When using `with_bind_ports` or `with_exposed_ports` - you can specify the port in the following formats: :code:`{private_port}/{protocol}` +.. autoclass:: testcontainers.core.image.DockerImage - e.g. `8080/tcp` or `8125/udp` or just `8080` (default protocol is tcp) +.. autoclass:: testcontainers.core.generic.DbContainer - For legacy reasons, the port can be an *integer* +.. raw:: html -.. autoclass:: testcontainers.core.image.DockerImage +
-.. autoclass:: testcontainers.core.generic.DbContainer +Compose +------- -.. autoclass:: testcontainers.core.network.Network +It is also possible to use Docker Compose functionality: + +.. automodule:: testcontainers.compose.compose + :members: .. raw:: html diff --git a/core/testcontainers/compose/compose.py b/core/testcontainers/compose/compose.py index 35ca5b335..8f9bd33cf 100644 --- a/core/testcontainers/compose/compose.py +++ b/core/testcontainers/compose/compose.py @@ -150,11 +150,11 @@ class DockerCompose: >>> from testcontainers.compose import DockerCompose - >>> compose = DockerCompose("compose/tests", compose_file_name="docker-compose-4.yml", + >>> compose = DockerCompose("core/tests/compose_fixtures/basic", compose_file_name="hello.yaml", ... pull=True) >>> with compose: ... stdout, stderr = compose.get_logs() - >>> b"Hello from Docker!" in stdout + >>> "Hello from Docker!" in stdout True .. code-block:: yaml @@ -191,7 +191,7 @@ def docker_compose_command(self) -> list[str]: Returns command parts used for the docker compose commands Returns: - cmd: Docker compose command parts. + list[str]: Docker compose command parts. """ return self.compose_command_property @@ -257,8 +257,8 @@ def get_logs(self, *services: str) -> tuple[str, str]: :param services: which services to get the logs for (or omit, for all) Returns: - stdout: Standard output stream. - stderr: Standard error stream. + str: stdout: Standard output stream. + str: stderr: Standard error stream. """ logs_cmd = [*self.compose_command_property, "logs", *services] @@ -358,15 +358,15 @@ def exec_in_container( Args: service_name: Name of the docker compose service to run the command in. - command: Command to execute. + command: Command to execute. :param service_name: specify the service name :param command: the command to run in the container Returns: - stdout: Standard output stream. - stderr: Standard error stream. - exit_code: The command's exit code. + str: stdout: Standard output stream. + str: stderr: Standard error stream. + int: exit_code: The command's exit code. """ if not service_name: service_name = self.get_container().Service diff --git a/core/testcontainers/core/container.py b/core/testcontainers/core/container.py index b7979a613..4abd51968 100644 --- a/core/testcontainers/core/container.py +++ b/core/testcontainers/core/container.py @@ -235,6 +235,9 @@ def get_wrapped_container(self) -> "Container": return self._container def get_docker_client(self) -> DockerClient: + """ + :meta private: + """ return self._docker def get_logs(self) -> tuple[bytes, bytes]: @@ -253,6 +256,10 @@ def _configure(self) -> None: class Reaper: + """ + :meta private: + """ + _instance: "Optional[Reaper]" = None _container: Optional[DockerContainer] = None _socket: Optional[socket] = None diff --git a/core/tests/compose_fixtures/basic/hello.yaml b/core/tests/compose_fixtures/basic/hello.yaml new file mode 100644 index 000000000..594a5110c --- /dev/null +++ b/core/tests/compose_fixtures/basic/hello.yaml @@ -0,0 +1,8 @@ +services: + hello: + image: alpine:latest + init: true + command: + - sh + - -c + - 'while true; do echo "Hello from Docker!"; sleep 1; done' diff --git a/index.rst b/index.rst index 307f934c0..e0e288558 100644 --- a/index.rst +++ b/index.rst @@ -16,6 +16,7 @@ testcontainers-python facilitates the use of Docker containers for functional an :maxdepth: 1 core/README + compose modules/index Getting Started