Update compose docs (testcontainers#198)

kieranlea · web-flow · commit 4cfe4c3f54d6 · 2022-04-04T12:30:16.000-04:00
diff --git a/.gitignore b/.gitignore
@@ -62,6 +62,7 @@ docs/_build/
 .noseids
 .idea/
 .venv/
+venv
 .testrepository/
 
 # vscode:
diff --git a/testcontainers/compose.py b/testcontainers/compose.py
@@ -1,5 +1,5 @@
 """
-Docker compose support
+Docker Compose Support
 ======================
 
 Allows to spin up services configured via :code:`docker-compose.yml`.
@@ -14,7 +14,20 @@
 
 class DockerCompose(object):
     """
-    Docker compose containers.
+    Manage docker compose environments.
+
+    Parameters
+    ----------
+    filepath: str
+        The relative directory containing the docker compose configuration file
+    compose_file_name: str
+        The file name of the docker compose configuration file
+    pull: bool
+        Attempts to pull images before launching environment
+    build: bool
+        Whether to build images referenced in the configuration file
+    env_file: str
+        Path to an env file containing environment variables to pass to docker compose
 
     Example
     -------
@@ -54,7 +67,6 @@ class DockerCompose(object):
         expose:
             - "5555"
     """
-
     def __init__(
             self,
             filepath,
@@ -78,6 +90,14 @@ def __exit__(self, exc_type, exc_val, exc_tb):
         self.stop()
 
     def docker_compose_command(self):
+        """
+        Returns command parts used for the docker compose commands
+
+        Returns
+        -------
+        list[str]
+            The docker compose command parts
+        """
         docker_compose_cmd = ['docker-compose']
         for file in self.compose_file_names:
             docker_compose_cmd += ['-f', file]
@@ -86,6 +106,9 @@ def docker_compose_command(self):
         return docker_compose_cmd
 
     def start(self):
+        """
+        Starts the docker compose environment.
+        """
         if self.pull:
             pull_cmd = self.docker_compose_command() + ['pull']
             self._call_command(cmd=pull_cmd)
@@ -97,10 +120,21 @@ def start(self):
         self._call_command(cmd=up_cmd)
 
     def stop(self):
+        """
+        Stops the docker compose environment.
+        """
         down_cmd = self.docker_compose_command() + ['down', '-v']
         self._call_command(cmd=down_cmd)
 
     def get_logs(self):
+        """
+        Returns all log output from stdout and stderr
+
+        Returns
+        -------
+        tuple[bytes, bytes]
+            stdout, stderr
+        """
         logs_cmd = self.docker_compose_command() + ["logs"]
         result = subprocess.run(
             logs_cmd,
@@ -136,9 +170,39 @@ def exec_in_container(self, service_name, command):
         return result.stdout.decode("utf-8"), result.stderr.decode("utf-8"), result.returncode
 
     def get_service_port(self, service_name, port):
+        """
+        Returns the mapped port for one of the services.
+
+        Parameters
+        ----------
+        service_name: str
+            Name of the docker compose service
+        port: int
+            The internal port to get the mapping for
+
+        Returns
+        -------
+        str:
+            The mapped port on the host
+        """
         return self._get_service_info(service_name, port)[1]
 
     def get_service_host(self, service_name, port):
+        """
+        Returns the host for one of the services.
+
+        Parameters
+        ----------
+        service_name: str
+            Name of the docker compose service
+        port: int
+            The internal port to get the host for
+
+        Returns
+        -------
+        str:
+            The hostname for the service
+        """
         return self._get_service_info(service_name, port)[0]
 
     def _get_service_info(self, service, port):
@@ -157,5 +221,16 @@ def _call_command(self, cmd, filepath=None):
 
     @wait_container_is_ready(requests.exceptions.ConnectionError)
     def wait_for(self, url):
+        """
+        Waits for a response from a given URL. This is typically used to
+        block until a service in the environment has started and is responding.
+        Note that it does not assert any sort of return code, only check that
+        the connection was successful.
+
+        Parameters
+        ----------
+        url: str
+            URL from one of the services in the environment to use to wait on
+        """
         requests.get(url)
         return self
