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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | d940216a99e1734aa157c750f6cc7eac284ff197082002d18e19d9b35475d881 |
|
MD5 | 5b8bd4ead2ed37bb0fe3cc578048a159 |
|
BLAKE2b-256 | 90702f7ba09a53f9acea97a142d56bcca02bd95bd9fd7feb06883f9a51e34376 |
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9487f0917f7351e1e9519e562345ed3e2aa8be7527b88dfbc8bb9bfe38b16127 |
|
MD5 | 62070bfece488ffc715aa0ede746c8bf |
|
BLAKE2b-256 | cefe86a485b9c840c2cd98ce6498a8b9474876d44f2c2da2c21ff4281773f63e |