axio-tools-docker 0.8.0__tar.gz → 0.9.1__tar.gz

{axio_tools_docker-0.8.0 → axio_tools_docker-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axio-tools-docker
-Version: 0.8.0
+Version: 0.9.1
 Summary: Docker sandbox tools for Axio
 Project-URL: Homepage, https://github.com/mosquito/axio-agent
 Project-URL: Repository, https://github.com/mosquito/axio-agent
@@ -22,7 +22,7 @@ Docker sandbox tools for [axio](https://github.com/mosquito/axio-agent).
 
 `DockerSandbox` is an async context manager that spins up an isolated Docker
 container on entry and removes it on exit. Inside the context it exposes six
-`axio` tools — the same `shell`, `write_file`, `read_file`, `list_files`,
+`axio` tools - the same `shell`, `write_file`, `read_file`, `list_files`,
 `run_python`, and `patch_file` as `axio-tools-local`, but every operation runs
 inside the container, never on the host.
 
@@ -35,7 +35,7 @@ docker info   # should succeed
 ```
 
 The package talks to the Docker Engine API directly via
-[aiodocker](https://aiodocker.readthedocs.io/) — the `docker` CLI is not
+[aiodocker](https://aiodocker.readthedocs.io/) - the `docker` CLI is not
 required.
 
 ## Installation
@@ -46,7 +46,7 @@ pip install axio-tools-docker
 
 ## Quick start
 
-<!-- name: test_readme_usage; mark: docker -->
+<!-- name: test_readme_usage; fixtures: docker -->
 ```python
 import asyncio
 from axio.agent import Agent
@@ -71,7 +71,7 @@ asyncio.run(main())
 
 ## Sandbox tools
 
-These mirror `axio-tools-local` exactly — same names and field schemas:
+These mirror `axio-tools-local` exactly - same names and field schemas:
 
 | Tool | Description |
 |---|---|
@@ -88,9 +88,18 @@ The container is created on `__aenter__` and removed on `__aexit__` (`docker rm
 Cleanup runs even when the body raises an exception:
 
 ```python
+from axio_tools_docker import DockerSandbox
+from axio import Agent
+
 async def run(ctx):
+    agent = Agent(
+        system="You are a coding assistant. Use the sandbox tools to run code safely.",
+        tools=ctx.sandbox.tools,
+    )
+
     async with DockerSandbox(image="alpine:latest") as sandbox:
         await agent.run("...", ctx)
+
     # container removed here (unless remove=False)
 ```
 
@@ -106,9 +115,10 @@ The running container's ID is available as `sandbox.container_id` inside the
 
 ## Named containers and reuse
 
-Pass `name=` to give the container a fixed name. If a running container with
-that name already exists, the sandbox attaches to it instead of creating a new
-one, and never removes it on exit — regardless of `remove`:
+Pass `name=` to give the container a fixed name. If a container with that name
+already exists, the sandbox starts it if needed and attaches instead of creating
+a new one. Attached containers are never removed on exit - regardless of
+`remove`:
 
 ```python
 import asyncio
@@ -126,37 +136,76 @@ asyncio.run(first_session())
 asyncio.run(second_session())
 ```
 
+## Named volumes
+
+Named volumes are managed by the Docker daemon and persist across container
+restarts. Use them to share state between sandbox sessions:
+
+<!-- name: test_readme_example; fixtures: docker -->
+```python
+import asyncio
+from axio_tools_docker import DockerSandbox
+
+async def main() -> None:
+    async with DockerSandbox(
+        image="python:3.12-alpine",
+        named_volumes={"/data": "my-project-data"},
+    ) as sb:
+        await sb.write_file("/data/state.json", '{"count": 1}')
+    # Container removed, volume survives.
+
+    async with DockerSandbox(
+        image="python:3.12-alpine",
+        named_volumes={"/data": "my-project-data"},
+        volumes_remove=True,   # delete the volume on exit
+    ) as sb:
+        raw = await sb.read_file_bytes("/data/state.json")
+        assert raw.decode() == '{"count": 1}'
+
+asyncio.run(main())
+```
+
+Docker creates the volume automatically if it does not exist yet.
+
 ## Configuration
 
-<!-- name: test_readme_config -->
+<!-- name: test_readme_config; fixtures: docker -->
 ```python
+import os
 from axio_tools_docker import DockerSandbox
 
 sandbox = DockerSandbox(
-    "unix:///var/run/docker.sock",   # Docker daemon URL (positional)
+    os.getenv("DOCKER_HOST", "unix:///var/run/docker.sock"),  # Docker daemon URL, optional
     image="python:3.12-slim",
-    memory="512m",                   # memory limit: "256m", "1g", …
-    cpus="2.0",                      # CPU limit
-    network=False,                   # False=none, True=default, str=explicit mode
+    memory="512m",  # memory limit: "256m", "1g", …
+    cpus="2.0",  # CPU limit
+    network=False,  # False=none, True=default, str=explicit mode
     workdir="/workspace",
-    volumes={"/workspace": "/tmp/host-dir"},   # {container_path: host_path}
+    volumes={"/workspace": "/tmp/host-dir"},  # {container_path: host_path}
+    named_volumes={"/data": "my-project-data"},  # named Docker volumes
+    volumes_remove=False,  # remove named volumes on exit
     env={"PYTHONPATH": "/app"},
     user="nobody",
     name="my-agent-sandbox",
     remove=False,
-    read_only=True,                  # read-only root filesystem
-    shm_size="64m",                  # /dev/shm size
-    cap_add=["NET_ADMIN"],           # add Linux capabilities
-    cap_drop=["ALL"],                # drop Linux capabilities
+    read_only=True,  # read-only root filesystem
+    shm_size="64m",  # /dev/shm size
+    cap_add=["NET_ADMIN"],  # add Linux capabilities
+    cap_drop=["ALL"],  # drop Linux capabilities
     privileged=False,
     ulimits={"nofile": (1024, 65536), "nproc": 512},
     tmpfs={"/tmp": "size=128m,mode=1777"},
-    ports={8080: 8080},              # {container_port: host_port}
+    ports={8080: 8080},  # {container_port: host_port}
     platform="linux/amd64",
     extra_hosts={"host.docker.internal": "host-gateway"},
     devices=["/dev/net/tun", "/dev/sda:/dev/xvda:r"],
     dns=["8.8.8.8", "1.1.1.1"],
 )
+
+assert sandbox.image == "python:3.12-slim"
+assert sandbox.memory == "512m"
+assert sandbox.cpus == "2.0"
+assert sandbox.network == False
 ```
 
 | Parameter | Type | Default | Description |
@@ -168,6 +217,8 @@ sandbox = DockerSandbox(
 | `network` | `bool \| str` | `False` | Network mode. `False` → `none`. `True` → Docker default. String → explicit `NetworkMode` (e.g. `"host"`, `"bridge"`, `"my-net"`). |
 | `workdir` | `str` | `"/workspace"` | Working directory inside the container. |
 | `volumes` | `dict[str, str]` | `{}` | Bind mounts as `{container_path: host_path}`. |
+| `named_volumes` | `dict[str, str]` | `{}` | Named Docker volumes as `{container_path: volume_name}`. Created automatically if absent. |
+| `volumes_remove` | `bool` | `False` | Remove named volumes on exit. No effect when attached to an existing container. |
 | `env` | `dict[str, str]` | `{}` | Environment variables passed to all commands. |
 | `user` | `str` | `""` | User to run as (e.g. `"nobody"`, `"1000"`). |
 | `name` | `str` | `""` | Container name. Attaches to existing container if found; creates new one otherwise. |
@@ -176,7 +227,7 @@ sandbox = DockerSandbox(
 | `shm_size` | `str` | `""` | `/dev/shm` size (e.g. `"64m"`). Useful for PyTorch / shared-memory IPC. |
 | `cap_add` | `list[str]` | `[]` | Linux capabilities to add (e.g. `["NET_ADMIN", "SYS_PTRACE"]`). |
 | `cap_drop` | `list[str]` | `[]` | Linux capabilities to drop (e.g. `["ALL"]`). |
-| `privileged` | `bool` | `False` | Extended privileges — full capability set and device access. Use with care. |
+| `privileged` | `bool` | `False` | Extended privileges - full capability set and device access. Use with care. |
 | `ulimits` | `dict[str, int \| tuple[int, int]]` | `{}` | Resource limits. `{"nofile": 1024}` → soft=hard=1024. `{"nofile": (1024, 65536)}` → soft/hard split. |
 | `tmpfs` | `dict[str, str]` | `{}` | Tmpfs mounts as `{path: options}` (e.g. `{"/tmp": "size=128m,mode=1777"}`). |
 | `ports` | `dict[int, int]` | `{}` | Port bindings as `{container_port: host_port}`. Only meaningful when `network != False`. |

{axio_tools_docker-0.8.0 → axio_tools_docker-0.9.1}/README.md

@@ -8,7 +8,7 @@ Docker sandbox tools for [axio](https://github.com/mosquito/axio-agent).
 
 `DockerSandbox` is an async context manager that spins up an isolated Docker
 container on entry and removes it on exit. Inside the context it exposes six
-`axio` tools — the same `shell`, `write_file`, `read_file`, `list_files`,
+`axio` tools - the same `shell`, `write_file`, `read_file`, `list_files`,
 `run_python`, and `patch_file` as `axio-tools-local`, but every operation runs
 inside the container, never on the host.
 
@@ -21,7 +21,7 @@ docker info   # should succeed
 ```
 
 The package talks to the Docker Engine API directly via
-[aiodocker](https://aiodocker.readthedocs.io/) — the `docker` CLI is not
+[aiodocker](https://aiodocker.readthedocs.io/) - the `docker` CLI is not
 required.
 
 ## Installation
@@ -32,7 +32,7 @@ pip install axio-tools-docker
 
 ## Quick start
 
-<!-- name: test_readme_usage; mark: docker -->
+<!-- name: test_readme_usage; fixtures: docker -->
 ```python
 import asyncio
 from axio.agent import Agent
@@ -57,7 +57,7 @@ asyncio.run(main())
 
 ## Sandbox tools
 
-These mirror `axio-tools-local` exactly — same names and field schemas:
+These mirror `axio-tools-local` exactly - same names and field schemas:
 
 | Tool | Description |
 |---|---|
@@ -74,9 +74,18 @@ The container is created on `__aenter__` and removed on `__aexit__` (`docker rm
 Cleanup runs even when the body raises an exception:
 
 ```python
+from axio_tools_docker import DockerSandbox
+from axio import Agent
+
 async def run(ctx):
+    agent = Agent(
+        system="You are a coding assistant. Use the sandbox tools to run code safely.",
+        tools=ctx.sandbox.tools,
+    )
+
     async with DockerSandbox(image="alpine:latest") as sandbox:
         await agent.run("...", ctx)
+
     # container removed here (unless remove=False)
 ```
 
@@ -92,9 +101,10 @@ The running container's ID is available as `sandbox.container_id` inside the
 
 ## Named containers and reuse
 
-Pass `name=` to give the container a fixed name. If a running container with
-that name already exists, the sandbox attaches to it instead of creating a new
-one, and never removes it on exit — regardless of `remove`:
+Pass `name=` to give the container a fixed name. If a container with that name
+already exists, the sandbox starts it if needed and attaches instead of creating
+a new one. Attached containers are never removed on exit - regardless of
+`remove`:
 
 ```python
 import asyncio
@@ -112,37 +122,76 @@ asyncio.run(first_session())
 asyncio.run(second_session())
 ```
 
+## Named volumes
+
+Named volumes are managed by the Docker daemon and persist across container
+restarts. Use them to share state between sandbox sessions:
+
+<!-- name: test_readme_example; fixtures: docker -->
+```python
+import asyncio
+from axio_tools_docker import DockerSandbox
+
+async def main() -> None:
+    async with DockerSandbox(
+        image="python:3.12-alpine",
+        named_volumes={"/data": "my-project-data"},
+    ) as sb:
+        await sb.write_file("/data/state.json", '{"count": 1}')
+    # Container removed, volume survives.
+
+    async with DockerSandbox(
+        image="python:3.12-alpine",
+        named_volumes={"/data": "my-project-data"},
+        volumes_remove=True,   # delete the volume on exit
+    ) as sb:
+        raw = await sb.read_file_bytes("/data/state.json")
+        assert raw.decode() == '{"count": 1}'
+
+asyncio.run(main())
+```
+
+Docker creates the volume automatically if it does not exist yet.
+
 ## Configuration
 
-<!-- name: test_readme_config -->
+<!-- name: test_readme_config; fixtures: docker -->
 ```python
+import os
 from axio_tools_docker import DockerSandbox
 
 sandbox = DockerSandbox(
-    "unix:///var/run/docker.sock",   # Docker daemon URL (positional)
+    os.getenv("DOCKER_HOST", "unix:///var/run/docker.sock"),  # Docker daemon URL, optional
     image="python:3.12-slim",
-    memory="512m",                   # memory limit: "256m", "1g", …
-    cpus="2.0",                      # CPU limit
-    network=False,                   # False=none, True=default, str=explicit mode
+    memory="512m",  # memory limit: "256m", "1g", …
+    cpus="2.0",  # CPU limit
+    network=False,  # False=none, True=default, str=explicit mode
     workdir="/workspace",
-    volumes={"/workspace": "/tmp/host-dir"},   # {container_path: host_path}
+    volumes={"/workspace": "/tmp/host-dir"},  # {container_path: host_path}
+    named_volumes={"/data": "my-project-data"},  # named Docker volumes
+    volumes_remove=False,  # remove named volumes on exit
     env={"PYTHONPATH": "/app"},
     user="nobody",
     name="my-agent-sandbox",
     remove=False,
-    read_only=True,                  # read-only root filesystem
-    shm_size="64m",                  # /dev/shm size
-    cap_add=["NET_ADMIN"],           # add Linux capabilities
-    cap_drop=["ALL"],                # drop Linux capabilities
+    read_only=True,  # read-only root filesystem
+    shm_size="64m",  # /dev/shm size
+    cap_add=["NET_ADMIN"],  # add Linux capabilities
+    cap_drop=["ALL"],  # drop Linux capabilities
     privileged=False,
     ulimits={"nofile": (1024, 65536), "nproc": 512},
     tmpfs={"/tmp": "size=128m,mode=1777"},
-    ports={8080: 8080},              # {container_port: host_port}
+    ports={8080: 8080},  # {container_port: host_port}
     platform="linux/amd64",
     extra_hosts={"host.docker.internal": "host-gateway"},
     devices=["/dev/net/tun", "/dev/sda:/dev/xvda:r"],
     dns=["8.8.8.8", "1.1.1.1"],
 )
+
+assert sandbox.image == "python:3.12-slim"
+assert sandbox.memory == "512m"
+assert sandbox.cpus == "2.0"
+assert sandbox.network == False
 ```
 
 | Parameter | Type | Default | Description |
@@ -154,6 +203,8 @@ sandbox = DockerSandbox(
 | `network` | `bool \| str` | `False` | Network mode. `False` → `none`. `True` → Docker default. String → explicit `NetworkMode` (e.g. `"host"`, `"bridge"`, `"my-net"`). |
 | `workdir` | `str` | `"/workspace"` | Working directory inside the container. |
 | `volumes` | `dict[str, str]` | `{}` | Bind mounts as `{container_path: host_path}`. |
+| `named_volumes` | `dict[str, str]` | `{}` | Named Docker volumes as `{container_path: volume_name}`. Created automatically if absent. |
+| `volumes_remove` | `bool` | `False` | Remove named volumes on exit. No effect when attached to an existing container. |
 | `env` | `dict[str, str]` | `{}` | Environment variables passed to all commands. |
 | `user` | `str` | `""` | User to run as (e.g. `"nobody"`, `"1000"`). |
 | `name` | `str` | `""` | Container name. Attaches to existing container if found; creates new one otherwise. |
@@ -162,7 +213,7 @@ sandbox = DockerSandbox(
 | `shm_size` | `str` | `""` | `/dev/shm` size (e.g. `"64m"`). Useful for PyTorch / shared-memory IPC. |
 | `cap_add` | `list[str]` | `[]` | Linux capabilities to add (e.g. `["NET_ADMIN", "SYS_PTRACE"]`). |
 | `cap_drop` | `list[str]` | `[]` | Linux capabilities to drop (e.g. `["ALL"]`). |
-| `privileged` | `bool` | `False` | Extended privileges — full capability set and device access. Use with care. |
+| `privileged` | `bool` | `False` | Extended privileges - full capability set and device access. Use with care. |
 | `ulimits` | `dict[str, int \| tuple[int, int]]` | `{}` | Resource limits. `{"nofile": 1024}` → soft=hard=1024. `{"nofile": (1024, 65536)}` → soft/hard split. |
 | `tmpfs` | `dict[str, str]` | `{}` | Tmpfs mounts as `{path: options}` (e.g. `{"/tmp": "size=128m,mode=1777"}`). |
 | `ports` | `dict[int, int]` | `{}` | Port bindings as `{container_port: host_port}`. Only meaningful when `network != False`. |

axio_tools_docker-0.9.1/conftest.py

@@ -0,0 +1,28 @@
+"""Pytest configuration for axio-tools-docker."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+import aiodocker
+import pytest
+
+
+@pytest.fixture(scope="session")
+def docker() -> str:
+    docker_url = os.getenv("DOCKER_HOST", "unix:///var/run/docker.sock")
+
+    async def _probe() -> bool:
+        # noinspection PyBroadException
+        try:
+            async with aiodocker.Docker(url=docker_url) as client:
+                await client.system.info()
+            return True
+        except Exception:
+            return False
+
+    if not asyncio.run(_probe()):
+        pytest.skip("Skipping due to missing Docker daemon")
+
+    return docker_url

{axio_tools_docker-0.8.0 → axio_tools_docker-0.9.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "axio-tools-docker"
-version = "0.8.0"
+version = "0.9.1"
 description = "Docker sandbox tools for Axio"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -24,6 +24,7 @@ testpaths = ["tests", "README.md"]
 
 [tool.ruff]
 line-length = 119
+output-format = "concise"
 target-version = "py312"
 
 [tool.ruff.lint]
@@ -33,6 +34,10 @@ select = ["E", "F", "I", "UP"]
 strict = true
 python_version = "3.12"
 
+[[tool.mypy.overrides]]
+module = "aiodocker.*"
+follow_imports = "skip"
+
 [dependency-groups]
 dev = [
     "pytest>=8",
@@ -43,4 +48,3 @@ dev = [
     "markdown-pytest>=0.6.0",
     "aiodocker>=0.26",
 ]
-