moby-distribution is a library for operating Docker Image Manifest and Blobs (Layers, Config, etc.).
Works for Python 3.6+.
You can install from PyPi.
❯ pip install moby-distribution
Or install from GitHub for latest version.
❯ pip install https://github.com/shabbywu/distribution/archive/main.zip
The API provides several classes: ManifestRef
, Blob
, Tags
, DockerRegistryV2Client
, APIEndpoint
, ImageRef
ManifestRef
has the following methods:
get(media_type)
retrieve image manifest as the provided media_typeget_metadata(media_type)
retrieve the manifest descriptor if the manifest exists.delete(raise_not_found)
Removes the manifest specified by the provided reference.put(manifest)
creates or updates the given manifest.
Blob
has the following methods:
download(digest)
download the blob from registry tolocal_path
orfileobj
upload()
upload the blob fromlocal_path
orfileobj
to the registry by streamingupload_at_one_time()
upload the monolithic blob fromlocal_path
orfileobj
to the registry at one time.mount_from(from_repo)
mount the blob from the given repo, if the client has read access to.delete(digest)
delete the blob at the registry.
Tags
has the following methods:
list()
return the list of tags in the repoget(tag)
retrieve the manifest descriptor identified by the tag.untag(tag)
work likeManifestRef.delete()
ImageRef
has the following methods:
from_image(from_repo, from_reference, to_repo, to_reference)
init aImageRef
from{from_repo}:{from_reference}
but will name{to_repo, to_reference}
.save(dest)
save the image to dest, as Docker Image Specification v1.2 Format.push(media_type="application/vnd.docker.distribution.manifest.v2+json")
push the image to the registry.push_v2()
push the image to the registry, with Manifest Schema2.add_layer(layer_ref)
add a layer to this image, this is a way to build a new Image.
DockerRegistryV2Client
has the following methods:
from_api_endpoint(api_endpoint, username, password)
initial a client to theapi_endpoint
withusername
andpassword
APIEndpoint
is a dataclass, you can define APIEndpoint in the following ways:
from moby_distribution import APIEndpoint
# 1. Provide scheme
APIEndpoint(url="https://registry.hub.docker.com")
# 2. No scheme provided
APIEndpoint(url="registry.hub.docker.com")
if the scheme is missing, we will detect whether the server provides ssl and verify the certificate.
If no ssl: use http(80). If have ssl, but certificate is invalid:
- try to ping the registry with https(443), if success, use it
- otherwise, downgrade to http(80)
If have ssl and valid certificate: use https(443)
We provide an anonymous client connected to Docker Official Registry as default, you can find it at moby_distribution.default_client
,
and you can override the default client by set_default_client(client)
.
from moby_distribution import Tags
Tags(repo="library/python").list()
# ['2', '2-alpine', '2-alpine3.10', '2-alpine3.11', '2-alpine3.4', '2-alpine3.6', ...]
from moby_distribution import ManifestRef, ManifestSchema1, ManifestSchema2
# Get Docker Image Manifest Version 2, Schema 1
# see alse: https://github.com/distribution/distribution/blob/main/docs/spec/manifest-v2-1.md
ManifestRef(repo="library/python", reference="latest").get(ManifestSchema1.content_type())
# Get Docker Image Manifest Version 2, Schema 2
# see alse: https://github.com/distribution/distribution/blob/main/docs/spec/manifest-v2-2.md
ManifestRef(repo="library/python", reference="latest").get(ManifestSchema2.content_type())
from io import BytesIO
from moby_distribution import ManifestRef, Blob
# Get Docker Image Manifest Version 2, Schema 2
manifest = ManifestRef(repo="library/python", reference="latest").get()
fh = BytesIO()
Blob(fileobj=fh, repo="library/python", digest=manifest.config.digest).download()
fh.seek(0)
config = fh.read()
Using the
local_path
parameter, you can download to the file system instead of memory.
from io import BytesIO
from moby_distribution import Blob, DockerRegistryV2Client, OFFICIAL_ENDPOINT
# To upload files to Docker Registry, you must login to your account
client = DockerRegistryV2Client.from_api_endpoint(OFFICIAL_ENDPOINT, username="your-username", password="your-password")
fh = BytesIO("just a demo")
assert Blob(repo="your-username/demo", fileobj=fh).upload()
Using the
local_path
parameter, you can upload blobs from the file system instead of memory.
from moby_distribution import ManifestSchema2, DockerRegistryV2Client, OFFICIAL_ENDPOINT, ManifestRef
# To upload files to Docker Registry, you must login to your account
client = DockerRegistryV2Client.from_api_endpoint(OFFICIAL_ENDPOINT, username="your-username", password="your-password")
# Build the ManifestSchema2 you need to upload
manifest = ManifestSchema2(
schemaVersion=2,
mediaType="application/vnd.docker.distribution.manifest.v2+json",
config={
...
},
layers=[
...
]
)
ManifestRef(repo="your-username/demo", reference="latest").put(manifest)
Read the process description of the official document
- Pushing the Layers as Example 4 do
- Pushing the Config as Example 4 do
- Pushing the Image Manifest as Example 5 do
Done, Congratulations!
Here is another way, use the newly implemented ImageRef!
from moby_distribution import ImageRef, DockerRegistryV2Client, OFFICIAL_ENDPOINT
# To upload files to Docker Registry, you must login to your account
client = DockerRegistryV2Client.from_api_endpoint(OFFICIAL_ENDPOINT, username="your-username", password="your-password")
image_ref = ImageRef.from_image(from_repo="your-repo", from_reference="your-reference", to_reference="the-new-reference")
image_ref.push()
The above statement achieves the equivalent function of docker tag {your-repo}:{your-reference} {your-repo}:{the-new-reference} && docker push {your-repo}:{the-new-reference}
- implement the Distribution Client API for moby(docker)
- implement the Docker Image Operator(Operator that implement Example 6)
- Command line tool for operating Image
- implement the Distribution Client API for OCI