Implement support for podman pods (#544)

gabrieldemarmiesse · May 29, 2024 · d09f324 · d09f324
1 parent 8b05066
commit d09f324
Show file tree

Hide file tree

Showing 29 changed files with 1,265 additions and 28 deletions.
diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml
@@ -40,6 +40,7 @@ jobs:
           - test_network.py
           - test_node.py
           - test_plugin.py
+          - test_pod.py
           - test_service.py
           - test_stack.py
           - test_swarm.py

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -18,7 +18,11 @@ with the help of [mkdocstrings](https://mkdocstrings.github.io/) and
 #### First install the dependencies:
 
 ```
+<<<<<<< HEAD
+pip install -r docs/requirements.txt
+=======
 pip install -r ./docs/requirements.txt
+>>>>>>> upstream/master
 ```
 
 #### Generate the documentation files and serve them

diff --git a/docs/autogen.py b/docs/autogen.py
@@ -42,6 +42,7 @@
     "sub-commands/plugin.md": [
         "python_on_whales.components.plugin.cli_wrapper.PluginCLI"
     ],
+    "sub-commands/pod.md": ["python_on_whales.components.pod.cli_wrapper.PodCLI"],
     "sub-commands/secret.md": [
         "python_on_whales.components.secret.cli_wrapper.SecretCLI"
     ],
@@ -58,18 +59,19 @@
     "sub-commands/volume.md": [
         "python_on_whales.components.volume.cli_wrapper.VolumeCLI"
     ],
-    "docker_objects/builders.md": ["python_on_whales.Builder"],
-    "docker_objects/containers.md": ["python_on_whales.Container"],
-    "docker_objects/configs.md": ["python_on_whales.Config"],
-    "docker_objects/images.md": ["python_on_whales.Image"],
-    "docker_objects/networks.md": ["python_on_whales.Network"],
-    "docker_objects/nodes.md": ["python_on_whales.Node"],
-    "docker_objects/plugins.md": ["python_on_whales.Plugin"],
-    "docker_objects/services.md": ["python_on_whales.Service"],
-    "docker_objects/secrets.md": ["python_on_whales.Secret"],
-    "docker_objects/stacks.md": ["python_on_whales.Stack"],
-    "docker_objects/volumes.md": ["python_on_whales.Volume"],
-    "docker_objects/tasks.md": [],
+    "objects/builders.md": ["python_on_whales.Builder"],
+    "objects/containers.md": ["python_on_whales.Container"],
+    "objects/configs.md": ["python_on_whales.Config"],
+    "objects/images.md": ["python_on_whales.Image"],
+    "objects/networks.md": ["python_on_whales.Network"],
+    "objects/nodes.md": ["python_on_whales.Node"],
+    "objects/plugins.md": ["python_on_whales.Plugin"],
+    "objects/pods.md": ["python_on_whales.Pod"],
+    "objects/services.md": ["python_on_whales.Service"],
+    "objects/secrets.md": ["python_on_whales.Secret"],
+    "objects/stacks.md": ["python_on_whales.Stack"],
+    "objects/volumes.md": ["python_on_whales.Volume"],
+    "objects/tasks.md": [],
     "user_guide/docker_run.md": [],
     "user_guide/generic_resources.md": [],
     "user_guide/running_python_on_whales_inside_a_container.md": [],

diff --git a/docs/docs_utils.py b/docs/docs_utils.py
@@ -1,9 +1,11 @@
 import tempfile
 from pathlib import Path
 
-from python_on_whales import docker
+from python_on_whales import DockerClient, docker
 from python_on_whales.exceptions import DockerException
 
+podman = DockerClient(client_call=["podman"])
+
 
 def write_code(i: int, attribute_access: str, value) -> str:
     string = f"""In [{i}]: super_print({attribute_access})
@@ -439,17 +441,42 @@ def generate_code_demo_containers():
     return "\n".join(result)
 
 
+def generate_code_demo_pods():
+    result = []
+
+    pod = podman.pod.create("my-pod")
+
+    with pod:
+        to_evaluate = [
+            "pod.id",
+            "pod.name",
+            "pod.created",
+            "pod.state",
+            "pod.num_containers",
+            "pod.infra_container_id",
+            "pod.shared_namespaces",
+            "pod.hostname",
+            "pod.exit_policy",
+        ]
+
+        for i, attribute_access in enumerate(to_evaluate):
+            value = eval(attribute_access)
+            result.append(write_code(i + 5, attribute_access, value))
+
+    return "\n".join(result)
+
+
 def add_links(text):
     text = text.replace(
         "`python_on_whales.Container`",
-        "[`python_on_whales.Container`](/docker_objects/containers/)",
+        "[`python_on_whales.Container`](/objects/containers/)",
     )
 
     return text
 
 
 def add_code_example(destination, markdown_file: str, code: str):
-    path_file = destination / "docker_objects" / markdown_file
+    path_file = destination / "objects" / markdown_file
     path_file.write_text(path_file.read_text().replace("@INSERT_GENERATED_CODE@", code))
     print("added code example for", markdown_file)
 
@@ -464,3 +491,4 @@ def add_all_code_examples(destination):
     add_code_example(destination, "builders.md", generate_code_demo_builders())
     add_code_example(destination, "nodes.md", generate_code_demo_nodes())
     add_code_example(destination, "services.md", generate_code_demo_services())
+    add_code_example(destination, "pods.md", generate_code_demo_pods())
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -55,19 +55,21 @@ nav:
     - docker task: sub-commands/task.md
     - docker trust: sub-commands/trust.md
     - docker volume: sub-commands/volume.md
-  - Docker objects:
-    - Builders: docker_objects/builders.md
-    - Configs: docker_objects/configs.md
-    - Containers: docker_objects/containers.md
-    - Images: docker_objects/images.md
-    - Networks: docker_objects/networks.md
-    - Nodes: docker_objects/nodes.md
-    - Plugins: docker_objects/plugins.md
-    - Secrets: docker_objects/secrets.md
-    - Services: docker_objects/services.md
-    - Stacks: docker_objects/stacks.md
-    - Tasks: docker_objects/tasks.md
-    - Volumes: docker_objects/volumes.md
+    - podman pod: sub-commands/pod.md
+  - Objects:
+    - Builders: objects/builders.md
+    - Configs: objects/configs.md
+    - Containers: objects/containers.md
+    - Images: objects/images.md
+    - Networks: objects/networks.md
+    - Nodes: objects/nodes.md
+    - Plugins: objects/plugins.md
+    - Pods: objects/pods.md
+    - Secrets: objects/secrets.md
+    - Services: objects/services.md
+    - Stacks: objects/stacks.md
+    - Tasks: objects/tasks.md
+    - Volumes: objects/volumes.md
   - User guide:
       - docker.run() guide: user_guide/docker_run.md
       - Swarm generic resources: user_guide/generic_resources.md

diff --git a/docs/template/docker_client.md b/docs/template/docker_client.md
@@ -20,6 +20,7 @@
 * [`docker.system`](sub-commands/system.md)
 * [`docker.trust`](sub-commands/trust.md)
 * [`docker.volume`](sub-commands/volume.md)
+* [`podman.pod`](sub-commands/pod.md)
 
 
 # Other commands

diff --git a/docs/template/docker_objects/builders.md → docs/template/objects/builders.md b/docs/template/docker_objects/builders.md → docs/template/objects/builders.md
diff --git a/docs/template/docker_objects/configs.md → docs/template/objects/configs.md b/docs/template/docker_objects/configs.md → docs/template/objects/configs.md
diff --git a/docs/template/docker_objects/containers.md → docs/template/objects/containers.md b/docs/template/docker_objects/containers.md → docs/template/objects/containers.md
diff --git a/docs/template/docker_objects/images.md → docs/template/objects/images.md b/docs/template/docker_objects/images.md → docs/template/objects/images.md
diff --git a/docs/template/docker_objects/networks.md → docs/template/objects/networks.md b/docs/template/docker_objects/networks.md → docs/template/objects/networks.md
diff --git a/docs/template/docker_objects/nodes.md → docs/template/objects/nodes.md b/docs/template/docker_objects/nodes.md → docs/template/objects/nodes.md
diff --git a/docs/template/docker_objects/plugins.md → docs/template/objects/plugins.md b/docs/template/docker_objects/plugins.md → docs/template/objects/plugins.md
diff --git a/docs/template/objects/pods.md b/docs/template/objects/pods.md
@@ -0,0 +1,50 @@
+# Podman pods
+
+Don't use the constructor directly. Instead use
+```python
+from python_on_whales import DockerClient
+
+podman = DockerClient(client_call=["podman"])
+
+my_pod = podman.pod.inspect("my-pod-name")
+
+# or
+
+my_pod = podman.pod.create("my-pod-name")
+```
+
+For type hints, use this
+```python
+from python_on_whales import Pod
+
+def print_container_names(pod: Pod):
+    print([ctr.name for ctr in pod.containers])
+```
+
+## Attributes
+
+The attributes are the same that you get with the command line:
+`podman pod inspect ...`
+
+If you want to know the exact structure, you can go to the
+[`podman pod inspect` reference page](https://docs.podman.io/en/stable/markdown/podman-pod-inspect.1.html)
+
+An example is worth many lines of descriptions.
+
+```
+In [1]: from python_on_whales import DockerClient
+
+In [2]: podman = DockerClient(client_call=["podman"])
+
+In [3]: pod = podman.pod.create("my-pod")
+
+In [4]: def super_print(obj):
+   ...:     print(f"type={type(obj)}, value={obj}")
+   ...:
+
+@INSERT_GENERATED_CODE@
+```
+
+## Methods
+
+{{autogenerated}}
diff --git a/docs/template/docker_objects/services.md → docs/template/objects/services.md b/docs/template/docker_objects/services.md → docs/template/objects/services.md
diff --git a/docs/template/docker_objects/tasks.md → docs/template/objects/tasks.md b/docs/template/docker_objects/tasks.md → docs/template/objects/tasks.md
diff --git a/docs/template/docker_objects/volumes.md → docs/template/objects/volumes.md b/docs/template/docker_objects/volumes.md → docs/template/objects/volumes.md
diff --git a/python_on_whales/__init__.py b/python_on_whales/__init__.py
@@ -11,6 +11,7 @@
 from .components.network.cli_wrapper import Network
 from .components.node.cli_wrapper import Node
 from .components.plugin.cli_wrapper import Plugin
+from .components.pod.cli_wrapper import Pod
 from .components.secret.cli_wrapper import Secret
 from .components.service.cli_wrapper import Service
 from .components.stack.cli_wrapper import Stack
@@ -38,6 +39,7 @@
     "Network",
     "Node",
     "Plugin",
+    "Pod",
     "Secret",
     "Service",
     "Stack",

diff --git a/python_on_whales/components/container/cli_wrapper.py b/python_on_whales/components/container/cli_wrapper.py
@@ -21,6 +21,7 @@
 
 import python_on_whales.components.image.cli_wrapper
 import python_on_whales.components.network.cli_wrapper
+import python_on_whales.components.pod.cli_wrapper
 import python_on_whales.components.volume.cli_wrapper
 from python_on_whales.client_config import (
     ClientConfig,
@@ -131,6 +132,10 @@ def state(self) -> ContainerState:
     def image(self) -> str:
         return self._get_inspect_result().image
 
+    @property
+    def pod(self) -> Optional[str]:
+        return self._get_inspect_result().pod
+
     @property
     def resolv_conf_path(self) -> str:
         return self._get_inspect_result().resolv_conf_path
@@ -608,6 +613,7 @@ def create(
         pid: Optional[str] = None,
         pids_limit: Optional[int] = None,
         platform: Optional[str] = None,
+        pod: Optional[python_on_whales.components.pod.cli_wrapper.ValidPod] = None,
         privileged: bool = False,
         publish: List[ValidPortMapping] = [],
         publish_all: bool = False,
@@ -769,6 +775,7 @@ def create(
         full_cmd.add_simple_arg("--pids-limit", pids_limit)
 
         full_cmd.add_simple_arg("--platform", platform)
+        full_cmd.add_simple_arg("--pod", pod)
         full_cmd.add_flag("--privileged", privileged)
 
         full_cmd.add_args_iterable_or_single(
@@ -1372,6 +1379,7 @@ def run(
         pid: Optional[str] = None,
         pids_limit: Optional[int] = None,
         platform: Optional[str] = None,
+        pod: Optional[python_on_whales.components.pod.cli_wrapper.ValidPod] = None,
         preserve_fds: Optional[int] = None,
         privileged: bool = False,
         publish: List[ValidPortMapping] = [],
@@ -1532,6 +1540,7 @@ def run(
             pid: PID namespace to use
             pids_limit: Tune container pids limit (set `-1` for unlimited)
             platform: Set platform if server is multi-platform capable.
+            pod: Create the container in an existing pod (only supported with podman).
             preserve_fds: The number of additional file descriptors to pass
                 through to the container. Only supported by podman.
             privileged: Give extended privileges to this container.
@@ -1703,6 +1712,7 @@ def run(
         full_cmd.add_simple_arg("--pids-limit", pids_limit)
 
         full_cmd.add_simple_arg("--platform", platform)
+        full_cmd.add_simple_arg("--pod", pod)
         full_cmd.add_simple_arg("--preserve-fds", preserve_fds)
         full_cmd.add_flag("--privileged", privileged)
 

diff --git a/python_on_whales/components/container/models.py b/python_on_whales/components/container/models.py
@@ -292,6 +292,7 @@ class ContainerInspectResult(DockerCamelModel):
     args: Optional[List[str]] = None
     state: Optional[ContainerState] = None
     image: Optional[str] = None
+    pod: Optional[str] = None
     resolv_conf_path: Optional[str] = None
     hostname_path: Optional[Path] = None
     hosts_path: Optional[Path] = None

diff --git a/python_on_whales/components/pod/__init__.py b/python_on_whales/components/pod/__init__.py