aboutsummaryrefslogtreecommitdiff
path: root/contrib/python/podman
diff options
context:
space:
mode:
authorJhon Honce <jhonce@redhat.com>2018-05-14 18:01:08 -0700
committerAtomic Bot <atomic-devel@projectatomic.io>2018-05-16 14:01:10 +0000
commit1aaf8df5be32d755a3f72f9259c66c70fbf850d8 (patch)
tree6e573fc7ae988e36d6d94973cec238aee72feaad /contrib/python/podman
parentc7bc7580a6a9faf6a3159d6c17ff1dfb3710e318 (diff)
downloadpodman-1aaf8df5be32d755a3f72f9259c66c70fbf850d8.tar.gz
podman-1aaf8df5be32d755a3f72f9259c66c70fbf850d8.tar.bz2
podman-1aaf8df5be32d755a3f72f9259c66c70fbf850d8.zip
Refactor libpod python varlink bindings
- More pythonic - Leverage context managers to help with socket leaks - Add system unittest's - Add image unittest's - Add container unittest's - Add models for system, containers and images, and their collections - Add helper functions for datetime parsing/formatting - GetInfo() implemented - Add support for setuptools - Update documentation - Support for Python 3.4-3.6 Signed-off-by: Jhon Honce <jhonce@redhat.com> Closes: #748 Approved by: baude
Diffstat (limited to 'contrib/python/podman')
-rw-r--r--contrib/python/podman/__init__.py22
-rw-r--r--contrib/python/podman/client.py81
-rw-r--r--contrib/python/podman/libs/__init__.py96
-rw-r--r--contrib/python/podman/libs/containers.py211
-rw-r--r--contrib/python/podman/libs/errors.py58
-rw-r--r--contrib/python/podman/libs/images.py137
-rw-r--r--contrib/python/podman/libs/system.py40
7 files changed, 645 insertions, 0 deletions
diff --git a/contrib/python/podman/__init__.py b/contrib/python/podman/__init__.py
new file mode 100644
index 000000000..5a0356311
--- /dev/null
+++ b/contrib/python/podman/__init__.py
@@ -0,0 +1,22 @@
+"""A client for communicating with a Podman server."""
+import pkg_resources
+
+from .client import Client
+from .libs import datetime_format, datetime_parse
+from .libs.errors import (ContainerNotFound, ErrorOccurred, ImageNotFound,
+ RuntimeError)
+
+try:
+ __version__ = pkg_resources.get_distribution('podman').version
+except Exception:
+ __version__ = '0.0.0'
+
+__all__ = [
+ 'Client',
+ 'ContainerNotFound',
+ 'datetime_format',
+ 'datetime_parse',
+ 'ErrorOccurred',
+ 'ImageNotFound',
+ 'RuntimeError',
+]
diff --git a/contrib/python/podman/client.py b/contrib/python/podman/client.py
new file mode 100644
index 000000000..8a1acdd9b
--- /dev/null
+++ b/contrib/python/podman/client.py
@@ -0,0 +1,81 @@
+"""A client for communicating with a Podman varlink service."""
+import contextlib
+import functools
+
+from varlink import Client as VarlinkClient
+from varlink import VarlinkError
+
+from .libs import cached_property
+from .libs.containers import Containers
+from .libs.errors import error_factory
+from .libs.images import Images
+from .libs.system import System
+
+
+class Client(object):
+ """A client for communicating with a Podman varlink service.
+
+ Example:
+
+ >>> import podman
+ >>> c = podman.Client()
+ >>> c.system.versions
+ """
+
+ # TODO: Port to contextlib.AbstractContextManager once
+ # Python >=3.6 required
+
+ def __init__(self,
+ uri='unix:/run/podman/io.projectatomic.podman',
+ interface='io.projectatomic.podman'):
+ """Construct a podman varlink Client.
+
+ uri from default systemd unit file.
+ interface from io.projectatomic.podman.varlink, do not change unless
+ you are a varlink guru.
+ """
+ self._podman = None
+
+ @contextlib.contextmanager
+ def _podman(uri, interface):
+ """Context manager for API children to access varlink."""
+ client = VarlinkClient(address=uri)
+ try:
+ iface = client.open(interface)
+ yield iface
+ except VarlinkError as e:
+ raise error_factory(e) from e
+ finally:
+ if hasattr(client, 'close'):
+ client.close()
+ iface.close()
+
+ self._client = functools.partial(_podman, uri, interface)
+
+ # Quick validation of connection data provided
+ if not System(self._client).ping():
+ raise ValueError('Failed varlink connection "{}/{}"'.format(
+ uri, interface))
+
+ def __enter__(self):
+ """Return `self` upon entering the runtime context."""
+ return self
+
+ def __exit__(self, exc_type, exc_value, traceback):
+ """Raise any exception triggered within the runtime context."""
+ return None
+
+ @cached_property
+ def system(self):
+ """Manage system model for podman."""
+ return System(self._client)
+
+ @cached_property
+ def images(self):
+ """Manage images model for libpod."""
+ return Images(self._client)
+
+ @cached_property
+ def containers(self):
+ """Manage containers model for libpod."""
+ return Containers(self._client)
diff --git a/contrib/python/podman/libs/__init__.py b/contrib/python/podman/libs/__init__.py
new file mode 100644
index 000000000..ab8fb94a8
--- /dev/null
+++ b/contrib/python/podman/libs/__init__.py
@@ -0,0 +1,96 @@
+"""Support files for podman API implementation."""
+import datetime
+import re
+import threading
+
+__all__ = [
+ 'cached_property',
+ 'datetime_parse',
+ 'datetime_format',
+]
+
+
+class cached_property(object):
+ """cached_property() - computed once per instance, cached as attribute.
+
+ Maybe this will make a future version of python.
+ """
+
+ def __init__(self, func):
+ """Construct context manager."""
+ self.func = func
+ self.__doc__ = func.__doc__
+ self.lock = threading.RLock()
+
+ def __get__(self, instance, cls=None):
+ """Retrieve previous value, or call func()."""
+ if instance is None:
+ return self
+
+ attrname = self.func.__name__
+ try:
+ cache = instance.__dict__
+ except AttributeError: # objects with __slots__ have no __dict__
+ msg = ("No '__dict__' attribute on {}"
+ " instance to cache {} property.").format(
+ repr(type(instance).__name__), repr(attrname))
+ raise TypeError(msg) from None
+
+ with self.lock:
+ # check if another thread filled cache while we awaited lock
+ if attrname not in cache:
+ cache[attrname] = self.func(instance)
+ return cache[attrname]
+
+
+def datetime_parse(string):
+ """Convert timestamp to datetime.
+
+ Because date/time parsing in python is still pedantically stupid,
+ we rip the input string apart throwing out the stop characters etc;
+ then rebuild a string strptime() can parse. Igit!
+
+ - Python >3.7 will address colons in the UTC offset.
+ - There is no ETA on microseconds > 6 digits.
+ - And giving an offset and timezone name...
+
+ # match: 2018-05-08T14:12:53.797795191-07:00
+ # match: 2018-05-08T18:24:52.753227-07:00
+ # match: 2018-05-08 14:12:53.797795191 -0700 MST
+ # match: 2018-05-09T10:45:57.576002 (python isoformat())
+
+ Some people, when confronted with a problem, think “I know,
+ I'll use regular expressions.” Now they have two problems.
+ -- Jamie Zawinski
+ """
+ ts = re.compile(r'^(\d+)-(\d+)-(\d+)'
+ r'[ T]?(\d+):(\d+):(\d+).(\d+)'
+ r' *([-+][\d:]{4,5})? *')
+
+ x = ts.match(string)
+ if x is None:
+ raise ValueError('Unable to parse {}'.format(string))
+
+ # converting everything to int() not worth the readablity hit
+ igit_proof = '{}T{}.{}{}'.format(
+ '-'.join(x.group(1, 2, 3)),
+ ':'.join(x.group(4, 5, 6)),
+ x.group(7)[0:6],
+ x.group(8).replace(':', '') if x.group(8) else '',
+ )
+
+ format = '%Y-%m-%dT%H:%M:%S.%f'
+ if x.group(8):
+ format += '%z'
+ return datetime.datetime.strptime(igit_proof, format)
+
+
+def datetime_format(dt):
+ """Format datetime in consistent style."""
+ if isinstance(dt, str):
+ return datetime_parse(dt).isoformat()
+ elif isinstance(dt, datetime.datetime):
+ return dt.isoformat()
+ else:
+ raise ValueError('Unable to format {}. Type {} not supported.'.format(
+ dt, type(dt)))
diff --git a/contrib/python/podman/libs/containers.py b/contrib/python/podman/libs/containers.py
new file mode 100644
index 000000000..cbbef23b1
--- /dev/null
+++ b/contrib/python/podman/libs/containers.py
@@ -0,0 +1,211 @@
+"""Models for manipulating containers and storage."""
+import collections
+import functools
+import json
+import signal
+
+
+class Container(collections.UserDict):
+ """Model for a container."""
+
+ def __init__(self, client, id, data):
+ """Construct Container Model."""
+ super(Container, self).__init__(data)
+
+ self._client = client
+ self._id = id
+
+ self._refresh(data)
+ assert self._id == self.data['id'],\
+ 'Requested container id({}) does not match store id({})'.format(
+ self._id, self.id
+ )
+
+ def __getitem__(self, key):
+ """Get items from parent dict + apply aliases."""
+ if key == 'running':
+ key = 'containerrunning'
+ return super().__getitem__(key)
+
+ def _refresh(self, data):
+ super().update(data)
+ for k, v in data.items():
+ setattr(self, k, v)
+ setattr(self, 'running', data['containerrunning'])
+
+ def refresh(self):
+ """Refresh status fields for this container."""
+ ctnr = Containers(self._client).get(self.id)
+ self._refresh(ctnr)
+
+ def attach(self, detach_key=None, no_stdin=False, sig_proxy=True):
+ """Attach to running container."""
+ with self._client() as podman:
+ # TODO: streaming and port magic occur, need arguements
+ podman.AttachToContainer()
+
+ def processes(self):
+ """Show processes running in container."""
+ with self._client() as podman:
+ results = podman.ListContainerProcesses(self.id)
+ for p in results['container']:
+ yield p
+
+ def changes(self):
+ """Retrieve container changes."""
+ with self._client() as podman:
+ results = podman.ListContainerChanges(self.id)
+ return results['container']
+
+ def kill(self, signal=signal.SIGTERM):
+ """Send signal to container, return id if successful.
+
+ default signal is signal.SIGTERM.
+ """
+ with self._client() as podman:
+ results = podman.KillContainer(self.id, signal)
+ return results['container']
+
+ def _lower_hook(self):
+ """Convert all keys to lowercase."""
+
+ @functools.wraps(self._lower_hook)
+ def wrapped(input):
+ return {k.lower(): v for (k, v) in input.items()}
+
+ return wrapped
+
+ def inspect(self):
+ """Retrieve details about containers."""
+ with self._client() as podman:
+ results = podman.InspectContainer(self.id)
+ obj = json.loads(
+ results['container'], object_hook=self._lower_hook())
+ return collections.namedtuple('ContainerInspect',
+ obj.keys())(**obj)
+
+ def export(self, target):
+ """Export container from store to tarball.
+
+ TODO: should there be a compress option, like images?
+ """
+ with self._client() as podman:
+ results = podman.ExportContainer(self.id, target)
+ return results['tarfile']
+
+ def start(self):
+ """Start container, return id on success."""
+ with self._client() as podman:
+ results = podman.StartContainer(self.id)
+ return results['container']
+
+ def stop(self, timeout=25):
+ """Stop container, return id on success."""
+ with self._client() as podman:
+ results = podman.StopContainer(self.id, timeout)
+ return results['container']
+
+ def remove(self, force=False):
+ """Remove container, return id on success.
+
+ force=True, stop running container.
+ """
+ with self._client() as podman:
+ results = podman.RemoveContainer(self.id, force)
+ return results['container']
+
+ def restart(self, timeout=25):
+ """Restart container with timeout, return id on success."""
+ with self._client() as podman:
+ results = podman.RestartContainer(self.id, timeout)
+ return results['container']
+
+ def rename(self, target):
+ """Rename container, return id on success."""
+ with self._client() as podman:
+ # TODO: Need arguements
+ results = podman.RenameContainer()
+ # TODO: fixup objects cached information
+ return results['container']
+
+ def resize_tty(self, width, height):
+ """Resize container tty."""
+ with self._client() as podman:
+ # TODO: magic re: attach(), arguements
+ podman.ResizeContainerTty()
+
+ def pause(self):
+ """Pause container, return id on success."""
+ with self._client() as podman:
+ results = podman.PauseContainer(self.id)
+ return results['container']
+
+ def unpause(self):
+ """Unpause container, return id on success."""
+ with self._client() as podman:
+ results = podman.UnpauseContainer(self.id)
+ return results['container']
+
+ def update_container(self, *args, **kwargs):
+ """TODO: Update container..., return id on success."""
+ with self._client() as podman:
+ results = podman.UpdateContainer()
+ self.refresh()
+ return results['container']
+
+ def wait(self):
+ """Wait for container to finish, return 'returncode'."""
+ with self._client() as podman:
+ results = podman.WaitContainer(self.id)
+ return int(results['exitcode'])
+
+ def stats(self):
+ """Retrieve resource stats from the container."""
+ with self._client() as podman:
+ results = podman.GetContainerStats(self.id)
+ obj = results['container']
+ return collections.namedtuple('StatDetail', obj.keys())(**obj)
+
+ def logs(self, *args, **kwargs):
+ """Retrieve container logs."""
+ with self._client() as podman:
+ results = podman.GetContainerLogs(self.id)
+ for line in results:
+ yield line
+
+
+class Containers(object):
+ """Model for Containers collection."""
+
+ def __init__(self, client):
+ """Construct model for Containers collection."""
+ self._client = client
+
+ def list(self):
+ """List of containers in the container store."""
+ with self._client() as podman:
+ results = podman.ListContainers()
+ for cntr in results['containers']:
+ yield Container(self._client, cntr['id'], cntr)
+
+ def delete_stopped(self):
+ """Delete all stopped containers."""
+ with self._client() as podman:
+ results = podman.DeleteStoppedContainers()
+ return results['containers']
+
+ def create(self, *args, **kwargs):
+ """Create container layer over the specified image.
+
+ See podman-create.1.md for kwargs details.
+ """
+ with self._client() as podman:
+ results = podman.CreateContainer()
+ return results['id']
+
+ def get(self, id):
+ """Retrieve container details from store."""
+ with self._client() as podman:
+ cntr = podman.GetContainer(id)
+ return Container(self._client, cntr['container']['id'],
+ cntr['container'])
diff --git a/contrib/python/podman/libs/errors.py b/contrib/python/podman/libs/errors.py
new file mode 100644
index 000000000..c28afd940
--- /dev/null
+++ b/contrib/python/podman/libs/errors.py
@@ -0,0 +1,58 @@
+"""Error classes and wrappers for VarlinkError."""
+from varlink import VarlinkError
+
+
+class VarlinkErrorProxy(VarlinkError):
+ """Class to Proxy VarlinkError methods."""
+
+ def __init__(self, obj):
+ """Construct proxy from Exception."""
+ self._obj = obj
+ self.__module__ = 'libpod'
+
+ def __getattr__(self, item):
+ """Return item from proxied Exception."""
+ return getattr(self._obj, item)
+
+
+class ContainerNotFound(VarlinkErrorProxy):
+ """Raised when Client can not find requested container."""
+
+ pass
+
+
+class ImageNotFound(VarlinkErrorProxy):
+ """Raised when Client can not find requested image."""
+
+ pass
+
+
+class ErrorOccurred(VarlinkErrorProxy):
+ """Raised when an error occurs during the execution.
+
+ See error() to see actual error text.
+ """
+
+ pass
+
+
+class RuntimeError(VarlinkErrorProxy):
+ """Raised when Client fails to connect to runtime."""
+
+ pass
+
+
+error_map = {
+ 'io.projectatomic.podman.ContainerNotFound': ContainerNotFound,
+ 'io.projectatomic.podman.ErrorOccurred': ErrorOccurred,
+ 'io.projectatomic.podman.ImageNotFound': ImageNotFound,
+ 'io.projectatomic.podman.RuntimeError': RuntimeError,
+}
+
+
+def error_factory(exception):
+ """Map Exceptions to a discrete type."""
+ try:
+ return error_map[exception.error()](exception)
+ except KeyError:
+ return exception
diff --git a/contrib/python/podman/libs/images.py b/contrib/python/podman/libs/images.py
new file mode 100644
index 000000000..1d40984a7
--- /dev/null
+++ b/contrib/python/podman/libs/images.py
@@ -0,0 +1,137 @@
+"""Models for manipulating images in/to/from storage."""
+import collections
+import functools
+import json
+
+
+class Image(collections.UserDict):
+ """Model for an Image."""
+
+ def __init__(self, client, id, data):
+ """Construct Image Model."""
+ super(Image, self).__init__(data)
+ for k, v in data.items():
+ setattr(self, k, v)
+
+ self._id = id
+ self._client = client
+
+ assert self._id == self.id,\
+ 'Requested image id({}) does not match store id({})'.format(
+ self._id, self.id
+ )
+
+ def __getitem__(self, key):
+ """Get items from parent dict."""
+ return super().__getitem__(key)
+
+ def export(self, dest, compressed=False):
+ """Write image to dest, return True on success."""
+ with self._client() as podman:
+ results = podman.ExportImage(self.id, dest, compressed)
+ return results['image']
+
+ def history(self):
+ """Retrieve image history."""
+ with self._client() as podman:
+ for r in podman.HistoryImage(self.id)['history']:
+ yield collections.namedtuple('HistoryDetail', r.keys())(**r)
+
+ def _lower_hook(self):
+ """Convert all keys to lowercase."""
+
+ @functools.wraps(self._lower_hook)
+ def wrapped(input):
+ return {k.lower(): v for (k, v) in input.items()}
+
+ return wrapped
+
+ def inspect(self):
+ """Retrieve details about image."""
+ with self._client() as podman:
+ results = podman.InspectImage(self.id)
+ obj = json.loads(results['image'], object_hook=self._lower_hook())
+ return collections.namedtuple('ImageInspect', obj.keys())(**obj)
+
+ def push(self, target, tlsverify=False):
+ """Copy image to target, return id on success."""
+ with self._client() as podman:
+ results = podman.PushImage(self.id, target, tlsverify)
+ return results['image']
+
+ def remove(self, force=False):
+ """Delete image, return id on success.
+
+ force=True, stop any running containers using image.
+ """
+ with self._client() as podman:
+ results = podman.RemoveImage(self.id, force)
+ return results['image']
+
+ def tag(self, tag):
+ """Tag image."""
+ with self._client() as podman:
+ results = podman.TagImage(self.id, tag)
+ return results['image']
+
+
+class Images(object):
+ """Model for Images collection."""
+
+ def __init__(self, client):
+ """Construct model for Images collection."""
+ self._client = client
+
+ def list(self):
+ """List all images in the libpod image store."""
+ with self._client() as podman:
+ results = podman.ListImages()
+ for img in results['images']:
+ yield Image(self._client, img['id'], img)
+
+ def create(self, *args, **kwargs):
+ """Create image from configuration."""
+ with self._client() as podman:
+ results = podman.CreateImage()
+ return results['image']
+
+ def create_from(self, *args, **kwargs):
+ """Create image from container."""
+ # TODO: Should this be on container?
+ with self._client() as podman:
+ results = podman.CreateFromContainer()
+ return results['image']
+
+ def build(self, *args, **kwargs):
+ """Build container from image.
+
+ See podman-build.1.md for kwargs details.
+ """
+ with self._client() as podman:
+ # TODO: Need arguments
+ podman.BuildImage()
+
+ def delete_unused(self):
+ """Delete Images not associated with a container."""
+ with self._client() as podman:
+ results = podman.DeleteUnusedImages()
+ return results['images']
+
+ def import_image(self, source, reference, message=None, changes=None):
+ """Read image tarball from source and save in image store."""
+ with self._client() as podman:
+ results = podman.ImportImage(source, reference, message, changes)
+ return results['image']
+
+ def pull(self, source):
+ """Copy image from registry to image store."""
+ with self._client() as podman:
+ results = podman.PullImage(source)
+ return results['id']
+
+ def search(self, id, limit=25):
+ """Search registries for id."""
+ with self._client() as podman:
+ results = podman.SearchImage(id)
+ for img in results['images']:
+ yield img
diff --git a/contrib/python/podman/libs/system.py b/contrib/python/podman/libs/system.py
new file mode 100644
index 000000000..c59867760
--- /dev/null
+++ b/contrib/python/podman/libs/system.py
@@ -0,0 +1,40 @@
+"""Models for accessing details from varlink server."""
+import collections
+
+import pkg_resources
+
+from . import cached_property
+
+
+class System(object):
+ """Model for accessing system resources."""
+
+ def __init__(self, client):
+ """Construct system model."""
+ self._client = client
+
+ @cached_property
+ def versions(self):
+ """Access versions."""
+ with self._client() as podman:
+ vers = podman.GetVersion()['version']
+
+ client = '0.0.0'
+ try:
+ client = pkg_resources.get_distribution('podman').version
+ except Exception:
+ pass
+ vers['client_version'] = client
+ return collections.namedtuple('Version', vers.keys())(**vers)
+
+ def info(self):
+ """Return podman info."""
+ with self._client() as podman:
+ info = podman.GetInfo()['info']
+ return collections.namedtuple('Info', info.keys())(**info)
+
+ def ping(self):
+ """Return True if server awake."""
+ with self._client() as podman:
+ response = podman.Ping()
+ return 'OK' == response['ping']['message']