Skip to main content

No project description provided

Project description

Dokker

Development

This is a development version of the package. Its API is not stable and might change at any time.

Inspiration

This package is designed to manage docker compose projects programmatically via python.

It provides a simple way to create, start, stop, and remove docker compose projects, as well as a way to interact with the containers and services within the project ( like running commands,).

While other packages exist that provide similar functionality (e.g. python-on-whales, testcontainers, etc.), dokker focusses on interacting with the docker compose project asyncronously (using asyncio, but with sync apis).

This allows for patterns like inspecting the logs of a container while your python code is interacting with it.

The primary use case for this package is to create integration tests for docker compose projects. It easily integrates with pytest.

Installation

pip install dokker

Sync Usage

Imaging you have a docker-compose.yaml file that looks like this:

version: "3.4"

services:
  echo_service:
    image: hashicorp/http-echo
    command: ["-text", "Hello from HashiCorp!"]
    ports:
      - "5678:5678"

To utilize this project in python, you can use the local function to create a project from the docker-compose.yaml file. (you can also use other builder functions to create projects from other sources, e.g. a cookiecutter template)

from dokker import local, HealthCheck
import requests

# create a project from a docker-compose.yaml file
deployment = local(
    "docker-compose.yaml",
    health_checks=[
        HealthCheck(
            service="echo_service",
            url="http://localhost:5678",
            max_retries=2,
            timeout=5,
        )
    ],
)
deployment.health_on_enter = True  # optional: wait for all health checks to be successful on enter

watcher = deployment.logswatcher(
    "echo_service", wait_for_logs=True, 
)  # Creates a watcher for the echo_service service, a watcher
# will asynchronously collect the logs of the service and make them available

# start the project (), will block until all health checks are successful
with deployment:
    # interact with the project

    with watcher:

        # interact with the project
        print(requests.get("http://localhost:5678"))

        # as we set wait_for_logs=True, the watcher will block until the logs are collected

    print(watcher.collected_logs)
    # interact with the project

Async Usage

from dokker import local

# create a project from a docker-compose.yaml file
deployment = local("docker-compose.yaml")
deployment.up_on_enter = False # optional: do not start the project on enter

# start the project ()
async def main()
    async with deployment:
        # interact with the project
        await deployment.aup() # start the project (and detach)


        async with deployment.logwatcher("service_to_log", log=print):
            await deployment.arestart("service_to_log") # restart the service

        

asyncio.run(main())

Pytest Usage

import pytest
from dokker import local

@pytest.fixture(scope="session")
def deployment():
    deployment = local("docker-compose.yaml")
    deployment.health_on_enter = True
    with project:
        yield project

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dokker-1.0.0.tar.gz (15.5 kB view details)

Uploaded Source

Built Distribution

dokker-1.0.0-py3-none-any.whl (19.8 kB view details)

Uploaded Python 3

File details

Details for the file dokker-1.0.0.tar.gz.

File metadata

  • Download URL: dokker-1.0.0.tar.gz
  • Upload date:
  • Size: 15.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.3 CPython/3.12.3 Linux/6.8.0-44-generic

File hashes

Hashes for dokker-1.0.0.tar.gz
Algorithm Hash digest
SHA256 d940216a99e1734aa157c750f6cc7eac284ff197082002d18e19d9b35475d881
MD5 5b8bd4ead2ed37bb0fe3cc578048a159
BLAKE2b-256 90702f7ba09a53f9acea97a142d56bcca02bd95bd9fd7feb06883f9a51e34376

See more details on using hashes here.

File details

Details for the file dokker-1.0.0-py3-none-any.whl.

File metadata

  • Download URL: dokker-1.0.0-py3-none-any.whl
  • Upload date:
  • Size: 19.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.3 CPython/3.12.3 Linux/6.8.0-44-generic

File hashes

Hashes for dokker-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 9487f0917f7351e1e9519e562345ed3e2aa8be7527b88dfbc8bb9bfe38b16127
MD5 62070bfece488ffc715aa0ede746c8bf
BLAKE2b-256 cefe86a485b9c840c2cd98ce6498a8b9474876d44f2c2da2c21ff4281773f63e

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page