==============================
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=main
   :target: https://github.com/aio-libs/aiodocker/actions/workflows/ci-cd.yml?query=branch%3Amain
   :alt: GitHub Actions status for the main branch

.. image:: https://codecov.io/gh/aio-libs/aiodocker/branch/main/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
===========

The recommended developer setup uses `uv <https://docs.astral.sh/uv/>`_, which
manages the virtualenv and resolves dependencies from the committed
``uv.lock`` so every contributor and CI job builds against the same versions.

.. code-block:: sh

   # Install uv first: https://docs.astral.sh/uv/getting-started/installation/
   uv sync --extra dev --extra lint --extra test --extra doc
   uv run pre-commit install

The ``Makefile`` helpers (``make develop``, ``make install``, ``make lint``,
``make test``) all assume uv.

Using pip instead (fallback)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you can't install uv, you can still bootstrap with pip. The resulting
environment isn't pinned to ``uv.lock``, so versions may drift from CI.

.. code-block:: sh

   python -m venv .venv && source .venv/bin/activate
   pip install -U pip
   pip install -e '.[dev,lint,test,doc]'  # in zsh, you need to escape brackets
   pre-commit install

Running tests
~~~~~~~~~~~~~

.. code-block:: sh

   # Run all tests
   make test

   # Run individual tests
   uv run pytest tests/test_images.py


Building packages
~~~~~~~~~~~~~~~~~

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

.. code-block:: sh

   uv build


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())