Docker Image Python Parser

0.1.13 · active · verified Sat Apr 11

docker-image-py is a Python library designed to parse Docker image names, tags, and registries, mimicking how Docker distributions handle image parsing. It provides a structured way to break down an image string into its components. The current version is 0.1.13, released in July 2024, and the library maintains an active, albeit infrequent, release cadence, driven by community contributions and specific parsing needs.

Warnings

gotcha This library is 'docker-image-py' (from realityone), which specifically focuses on *parsing* Docker image names. It is not the 'docker-py' or 'docker' SDK (from Docker Inc.) which is used to interact with the Docker daemon API to build, run, and manage containers. Confusing the two can lead to incorrect imports and unexpected behavior.
Fix: Ensure you are importing from `docker_image` for parsing, or `docker` for the Docker SDK. Verify the PyPI package `docker-image-py` is installed if you intend to use the parsing library.
gotcha The `Reference.parse()` method will infer 'docker.io' as the registry if no registry is explicitly provided in the image string. Be aware of this default behavior, especially when working with private or custom registries where an explicit registry name is always expected.
Fix: Always provide the full registry path for private or custom images (e.g., `myregistry.com/myimage:tag`) or explicitly check the `registry` attribute if the default `docker.io` is not desired.
gotcha The library primarily handles the structural parsing of image names. It does not validate the existence of the image, the correctness of the digest (beyond format), or the accessibility of the registry. Malformed image strings may raise exceptions or produce unexpected parsing results.
Fix: Implement robust error handling (e.g., `try-except`) when parsing user-provided or external image strings. Consider additional validation steps if the integrity or existence of the image is critical.

Install

pip install docker-image-py Install from PyPI

Imports

Reference
```
from docker_image import Reference
```

Quickstart

The `Reference.parse()` method is the primary entry point for parsing Docker image strings. It returns a `Reference` object with attributes for registry, repository, tag, and digest.

from docker_image import Reference

# Parse a full image reference
ref = Reference.parse('registry.example.com/repo/image:tag')
print(f"Registry: {ref.registry}")
print(f"Repository: {ref.repository}")
print(f"Tag: {ref.tag}")
print(f"Digest: {ref.digest}")
print(f"Raw: {ref.raw}")

# Parse an image with no registry specified (defaults to 'docker.io')
ref_default = Reference.parse('ubuntu:latest')
print(f"\nRegistry (default): {ref_default.registry}")
print(f"Repository: {ref_default.repository}")

# Parse an image with a digest
ref_digest = Reference.parse('myrepo/myimage@sha256:456abc...')
print(f"\nRepository: {ref_digest.repository}")
print(f"Digest: {ref_digest.digest}")

view raw JSON →