Implement support for podman pods

[LewisGaul]

This feature only applies for podman, not docker.

• Support podman create --pod <pod> and podman run --pod <pod> (ContainerCLI.create(pod=...) and ContainerCLI.run(pod=...))
• Support podman inspect <ctr> including the pod if applicable (Container.pod property)
• Support pod subcommand/component, podman pod ... (Pod, PodCLI, and corresponding inspect data model objects)
• Add tests using podman client
• Update docs (checked locally)

Questions/notes:

• How should we encorporate this in the docs, since the commands are current listed as "docker \" but docker does not support "docker pod"?
• Following response to the above, I have added "podman pod" subcmd on the docs, and changed "Docker objects" to just "Objects" to allow inclusion of "Pods".
• I have implemented Container.pod to return the string pod ID rather than the Pod object - see https://github.com/gabrieldemarmiesse/python-on-whales/issues/543 for discussion.
• Is it the right choice to support args like pod_id_file in PodCLI.create()?
• Deferring implementation of podman pod stats and podman pod top.
• Deferring implementation of support for --latest and --all (for podman pod {start,restart,stop,kill,pause,unpause} and similar for podman containers) following comments in this PR, tracked by https://github.com/gabrieldemarmiesse/python-on-whales/issues/588.

TODO:

• [x] Docs update
• [x] More tests needed
• [x] Docstring for PodCLI.create()

Follow-up:

• Add the new test_pod.py to required PR checks (requires repo admin)
• Skip tests that aren't supported on older podman versions, depends on https://github.com/gabrieldemarmiesse/python-on-whales/issues/591

[LewisGaul]

@gabrieldemarmiesse any thoughts on what needs doing here, with regards to docs and tests?

[gabrieldemarmiesse]

How should we encorporate this in the docs, since the commands are current listed as "docker " but docker does not support "docker pod"?

We can choose the name of web pages, do instead of naming it "docker ..." like the other commands, we could just name it "podman pod"

I have implemented Container.pod to return the string pod ID rather than the Pod object

Good call, I still haven't decided what to do here.

Is it the right choice to support --latest and --all to podman pod {start,restart,stop,kill,pause,unpause}?

I think so yes. We want python-on-whales to be familiar to users who started with the CLI (in this case the podman CLI).

The rest of the review will be done, no worries, I'm just finding the time here and there

[gabrieldemarmiesse]

Is it the right choice to support args like pod_id_file in PodCLI.create()?

I don't see what is special about it. Maybe I'm missing something?

[gabrieldemarmiesse]

Food for thought, I wonder if we should have a sentinel value for "all objects" that we can use in this PR but also as default value in some other places. It might seems strange to have containers=None mean all containers (since it's the default value). We could also have a sentinel for latest.

[LewisGaul]

Is it the right choice to support args like pod_id_file in PodCLI.create()?

I don't see what is special about it. Maybe I'm missing something?

Only that it's probably easier to get the ID of the pod when using PoW than when calling the CLI so less use for having podman write it to a file for you (tbh this seems like a slightly odd CLI arg to me). But happy to just leave it for consistency with the CLI.

[LewisGaul]

@gabrieldemarmiesse This should be ready for review now (EDIT: now I've fixed the bad merge)