Provide examples for python podman API

Signed-off-by: Jhon Honce <jhonce@redhat.com>

Closes: #870
Approved by: rhatdan

9 files changed, 188 insertions, 5 deletions

diff --git a/contrib/python/.gitignore b/contrib/python/.gitignore
index 2fc8ce3da..a3903c542 100644
--- a/contrib/python/.gitignore
+++ b/contrib/python/.gitignore
@@ -1,3 +1,5 @@
 build
 dist
 *.egg-info
+*.pyc
+__pycache__
diff --git a/contrib/python/README.md b/contrib/python/README.md
index 747e71559..dcf40a1a9 100644
--- a/contrib/python/README.md
+++ b/contrib/python/README.md
@@ -1,15 +1,43 @@
 # podman - pythonic library for working with varlink interface to Podman
 
-### Status: Active Development
+## Status: Active Development
 
 See [libpod](https://github.com/projectatomic/libpod)
 
+## Releases
 
-###
-
-To build the podman wheel:
+To build the podman egg:
 
 ```sh
 cd ~/libpod/contrib/pypodman
-python3 setup.py clean -a && python3 setup.py bdist_wheel
+python3 setup.py clean -a && python3 setup.py bdist
+```
+
+## Code snippets/examples:
+
+### Show images in storage
+
+```python
+import podman
+
+with podman.Client() as client:
+  list(map(print, client.images.list()))
+```
+
+### Show containers created since midnight
+
+```python
+from datetime import datetime, time, timezone
+
+import podman
+
+midnight = datetime.combine(datetime.today(), time.min, tzinfo=timezone.utc)
+
+with podman.Client() as client:
+    for c in client.containers.list():
+        created_at = podman.datetime_parse(c.createdat)
+
+        if created_at > midnight:
+            print('Container {}: image: {} created at: {}'.format(
+                c.id[:12], c.image[:32], podman.datetime_format(created_at)))
 ```
diff --git a/contrib/python/examples/eg_attach.py b/contrib/python/examples/eg_attach.py
new file mode 100644
index 000000000..f8008163f
--- /dev/null
+++ b/contrib/python/examples/eg_attach.py
@@ -0,0 +1,17 @@
+#!/usr/bin/env python3
+"""Example: Run Alpine container and attach."""
+
+import podman
+
+print('{}\n'.format(__doc__))
+
+with podman.Client() as client:
+    id = client.images.pull('alpine:latest')
+    img = client.images.get(id)
+    cntr = img.create()
+    cntr.start()
+
+    try:
+        cntr.attach()
+    except BrokenPipeError:
+        print('Container disconnected.')
diff --git a/contrib/python/examples/eg_containers_by_image.py b/contrib/python/examples/eg_containers_by_image.py
new file mode 100644
index 000000000..bf4fdebf1
--- /dev/null
+++ b/contrib/python/examples/eg_containers_by_image.py
@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+"""Example: Show containers grouped by image id."""
+
+from itertools import groupby
+
+import podman
+
+print('{}\n'.format(__doc__))
+
+with podman.Client() as client:
+    ctnrs = sorted(client.containers.list(), key=lambda k: k.imageid)
+    for key, grp in groupby(ctnrs, key=lambda k: k.imageid):
+        print('Image: {}'.format(key))
+        for c in grp:
+            print('     : container: {} created at: {}'.format(
+                c.id[:12], podman.datetime_format(c.createdat)))
diff --git a/contrib/python/examples/eg_image_list.py b/contrib/python/examples/eg_image_list.py
new file mode 100644
index 000000000..ef31fd708
--- /dev/null
+++ b/contrib/python/examples/eg_image_list.py
@@ -0,0 +1,10 @@
+#!/usr/bin/env python3
+"""Example: Show all images on system."""
+
+import podman
+
+print('{}\n'.format(__doc__))
+
+with podman.Client() as client:
+    for img in client.images.list():
+        print(img)
diff --git a/contrib/python/examples/eg_inspect_fedora.py b/contrib/python/examples/eg_inspect_fedora.py
new file mode 100644
index 000000000..b5bbba46d
--- /dev/null
+++ b/contrib/python/examples/eg_inspect_fedora.py
@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+"""Example: Pull Fedora and inspect image and container."""
+
+import podman
+
+print('{}\n'.format(__doc__))
+
+with podman.Client() as client:
+    id = client.images.pull('registry.fedoraproject.org/fedora:28')
+    img = client.images.get(id)
+    print(img.inspect())
+
+    cntr = img.create()
+    print(cntr.inspect())
+
+    cntr.remove()
diff --git a/contrib/python/examples/eg_latest_containers.py b/contrib/python/examples/eg_latest_containers.py
new file mode 100644
index 000000000..446f670dd
--- /dev/null
+++ b/contrib/python/examples/eg_latest_containers.py
@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+"""Example: Show all containers created since midnight."""
+
+from datetime import datetime, time, timezone
+
+import podman
+
+print('{}\n'.format(__doc__))
+
+
+midnight = datetime.combine(datetime.today(), time.min, tzinfo=timezone.utc)
+
+with podman.Client() as client:
+    for c in client.containers.list():
+        created_at = podman.datetime_parse(c.createdat)
+
+        if created_at > midnight:
+            print('{}: image: {} createdAt: {}'.format(
+                c.id[:12], c.image[:32], podman.datetime_format(created_at)))
diff --git a/contrib/python/examples/eg_new_image.py b/contrib/python/examples/eg_new_image.py
new file mode 100644
index 000000000..21e076dcb
--- /dev/null
+++ b/contrib/python/examples/eg_new_image.py
@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""Example: Create new image from container."""
+
+import sys
+
+import podman
+
+
+def print_history(details):
+    """Format history data from an image, in a table."""
+    for i, r in enumerate(details):
+        print(
+            '{}: {} {} {}'.format(i, r.id[:12],
+                                  podman.datetime_format(r.created), r.tags),
+            sep='\n')
+    print("-" * 25)
+
+
+print('{}\n'.format(__doc__))
+
+with podman.Client() as client:
+    ctnr = next(
+        (c for c in client.containers.list() if 'alpine' in c['image']), None)
+
+    if ctnr:
+        print_history(client.images.get(ctnr.imageid).history())
+
+        # Make changes as we save the container to a new image
+        id = ctnr.commit('alpine-ash', changes=['CMD=/bin/ash'])
+        print_history(client.images.get(id).history())
+    else:
+        print('Unable to find "alpine" container.', file=sys.stderr)
diff --git a/contrib/python/examples/run_example.sh b/contrib/python/examples/run_example.sh
new file mode 100755
index 000000000..0f6575073
--- /dev/null
+++ b/contrib/python/examples/run_example.sh
@@ -0,0 +1,43 @@
+#!/bin/bash
+
+export PYTHONPATH=..
+
+function examples {
+  for file in $@; do
+    python3 -c "import ast; f=open('"${file}"'); t=ast.parse(f.read()); print(ast.get_docstring(t) + '  -- "${file}"')"
+  done
+}
+
+while getopts "lh" arg; do
+  case $arg in
+    l ) examples $(ls eg_*.py); exit 0 ;;
+    h ) echo 1>&2 $0 [-l] [-h] filename ; exit 2 ;;
+  esac
+done
+shift $((OPTIND-1))
+
+# podman needs to play some games with resources
+if [[ $(id -u) != 0 ]]; then
+  echo 1>&2 $0 must be run as root.
+  exit 2
+fi
+
+if ! systemctl --quiet is-active io.projectatomic.podman.socket; then
+  echo 1>&2 'podman is not running. systemctl enable --now io.projectatomic.podman.socket'
+  exit 1
+fi
+
+function cleanup {
+  podman rm $1 >/dev/null 2>&1
+}
+
+# Setup storage with an image and container
+podman pull alpine:latest >/tmp/podman.output 2>&1
+CTNR=$(podman create alpine)
+trap "cleanup $CTNR" EXIT
+
+if [[ -f $1 ]]; then
+  python3 $1
+else
+  python3 $1.py
+fi