Title images.pull without tag fails and appears to send empty tag; docstring suggests “pull all tags”

[mpnowacki-reef]

• Summary

  • Calling images.pull("alpine", stream=True) fails, but images.pull("alpine", tag="latest", stream=True) succeeds. It looks like when tag is not provided, the client sends the tag query parameter with an empty value (tag=) instead of omitting it or defaulting to latest. The docstring also suggests that an empty tag pulls “all tags,” which doesn’t match Docker Engine behavior and likely isn’t intended.

• Environment

  • aiodocker: <insert version, e.g., 0.x.y>
  • Python: 3.11.11
  • OS: macOS Sonoma (Apple Silicon, arm64)
  • Docker Desktop / Engine:
    • Client:
      Version: 28.0.1
      API version: 1.48
      Go version: go1.23.6
      Git commit: 068a01e
      Built: Wed Feb 26 10:38:16 2025
      OS/Arch: darwin/arm64
      Context: default

Server: Docker Desktop 4.39.0 (184744)
Engine:
Version: 28.0.1
API version: 1.48 (minimum version 1.24)
Go version: go1.23.6
Git commit: bbd0a17
Built: Wed Feb 26 10:40:57 2025
OS/Arch: linux/arm64
Experimental: false
containerd:
Version: 1.7.25
GitCommit: bcc810d6b9066471b0b6fa75f557a15a1cbf31bb
runc:
Version: 1.2.4
GitCommit: v1.2.4-0-g6c52b3f
docker-init:
Version: 0.19.0
GitCommit: de40ad0

- aiohttp: 0.24.0
- Reproducible on clean environment: yes/no

• Steps to Reproduce
  1. Run the following script:
     insert
     insert

     # Python
     import asyncio
     import aiodocker

     async def main():
         async with aiodocker.Docker() as client:
             async for line in client.images.pull("alpine", stream=True):
                 print(line)

     asyncio.run(main())

1. Observe that it fails.
2. Change the call to specify a tag and run again:

     # Python
     async with aiodocker.Docker() as client:
         async for line in client.images.pull("alpine", tag="latest", stream=True):
             print(line)

1. This succeeds.

• Expected Behavior

  • Omitting tag should behave like docker pull alpine (i.e., pull the default tag), or at least should not fail. At minimum, behavior should be documented consistently.

• Actual Behavior

  • The pull fails when tag is omitted. On Apple Silicon, this can surface as pulling a non-existent/legacy tag or a registry error. Supplying tag="latest" succeeds.

• Additional Context

  • Architecture differences (arm64 vs amd64) make this more visible because very old tags often lack multi-arch manifests, so an unintended tag resolution can fail on Apple Silicon.