============================== AsyncIO bindings for docker.io

.. image:: https://badge.fury.io/py/aiodocker.svg :target: https://badge.fury.io/py/aiodocker :alt: PyPI version

.. image:: https://img.shields.io/pypi/pyversions/aiodocker.svg :target: https://pypi.org/project/aiodocker/ :alt: Python Versions

.. image:: https://github.com/aio-libs/aiodocker/actions/workflows/ci-cd.yml/badge.svg?branch=master :target: https://github.com/aio-libs/aiodocker/actions/workflows/ci-cd.yml?query=branch%3Amaster :alt: GitHub Actions status for the main branch

.. image:: https://codecov.io/gh/aio-libs/aiodocker/branch/master/graph/badge.svg :target: https://codecov.io/gh/aio-libs/aiodocker :alt: Code Coverage

.. image:: https://badges.gitter.im/Join%20Chat.svg :target: https://gitter.im/aio-libs/Lobby :alt: Chat on Gitter

A simple Docker HTTP API wrapper written with asyncio and aiohttp.

Installation

.. code-block:: sh

pip install aiodocker

Development

Create a virtualenv (either using python -m venv, pyenv or your favorite tools) and install in the editable mode with ci and dev optional dependency sets.

.. code-block:: sh

pip install -U pip pip install -e '.[ci,dev]' # in zsh, you need to escape brackets pre-commit install

Running tests

.. code-block:: sh

   # Run all tests
   make test

   # Run individual tests
   python -m pytest tests/test_images.py

Building packages

NOTE: Usually you don't need to run this step by yourself.

.. code-block:: sh

pip install -U build python -m build --sdist --wheel

Documentation

http://aiodocker.readthedocs.io

Examples

.. code-block:: python

import asyncio
import aiodocker

async def list_things(docker):
    print('== Images ==')
    for image in (await docker.images.list()):
        tags = image['RepoTags'][0] if image['RepoTags'] else ''
        print(image['Id'], tags)
    print('== Containers ==')
    for container in (await docker.containers.list()):
        print(f" {container._id}")

async def run_container(docker):
    print('== Running a hello-world container ==')
    container = await docker.containers.create_or_replace(
        config={
            'Cmd': ['/bin/ash', '-c', 'echo "hello world"'],
            'Image': 'alpine:latest',
        },
        name='testing',
    )
    await container.start()
    logs = await container.log(stdout=True)
    print(''.join(logs))
    await container.delete(force=True)

async def main():
    docker = aiodocker.Docker()
    await list_things(docker)
    await run_container(docker)
    await docker.close()

if __name__ == "__main__":
    asyncio.run(main())