dxf module

dxf.DXFBase(host[, auth, insecure, ...])

Class for communicating with a Docker v2 registry.

dxf.DXF(host, repo[, auth, insecure, ...])

Class for operating on a Docker v2 repositories.

Module for accessing a Docker v2 Registry

class dxf.DXF(host: str, repo: str, auth: Callable[[DXFBase, Response], None] | None = None, insecure: bool = False, auth_host: str | None = None, tlsverify: bool | str = True, timeout: float | None = None)

Bases: DXFBase

Class for operating on a Docker v2 repositories.

Parameters:
  • host – Host name of registry. Can contain port numbers. e.g. registry-1.docker.io, localhost:5000.

  • repo – Name of the repository to access on the registry. Typically this is of the form username/reponame but for your own registries you don’t actually have to stick to that.

  • auth – Authentication function to be called whenever authentication to the registry is required. Receives the DXF object and a HTTP response object. It should call DXFBase.authenticate() with a username, password and response before it returns.

  • insecure – Use HTTP instead of HTTPS (which is the default) when connecting to the registry.

  • auth_host – Host to use for token authentication. If set, overrides host returned by then registry.

  • tlsverify – When set to False, do not verify TLS certificate. When pointed to a <ca bundle>.crt file use this for TLS verification. See requests.verify for more details.

  • timeout – Optional timeout for requests. See requests.timeout for more details.

api_version_check() Tuple[str, Response]

Performs API version check

Returns:

version check response as a string (JSON) and requests.Response

blob_size(digest: str) int

Return the size of a blob in the registry given the hash of its content.

Parameters:

digest – Hash of the blob’s content (prefixed by sha256:).

Returns:

Size of the blob in bytes.

del_alias(alias: str) List[str] | Dict[str, str]

Delete an alias from the registry. The blobs it points to won’t be deleted. Use del_blob() for that.

Note

On private registry, garbage collection might need to be run manually; see: https://docs.docker.com/registry/garbage-collection/

Parameters:

alias – Alias name.

Returns:

A list of blob hashes (strings) which were assigned to the alias. For multi-arch aliases, a dict with the alias hash per platform. You’ll need to call DXF.del_alias() for each of those.

del_blob(digest: str)

Delete a blob from the registry given the hash of its content.

Parameters:

digest – Hash of the blob’s content (prefixed by sha256:).

classmethod from_base(base: DXFBase, repo: str) TD

Create a DXF object which uses the same host, settings and session as an existing DXFBase object.

Parameters:
  • base – Existing DXFBase object.

  • repo – Name of the repository to access on the registry. Typically this is of the form username/reponame but for your own registries you don’t actually have to stick to that.

Returns:

DXF object which shares configuration and session with base but which can also be used to operate on the repo repository.

get_alias(alias: str | None = None, manifest: str | None = None, verify: bool = True, sizes: bool = False, platform: str | None = None) List[str] | List[Tuple[str, int]] | Dict[str, List[str] | List[Tuple[str, int]]]

Get the blob hashes assigned to an alias.

Parameters:
  • alias – Alias name. You almost definitely will only need to pass this argument.

  • manifest – If you previously obtained a manifest, specify it here instead of alias. You almost definitely won’t need to do this.

  • verify – (v1 schema only) Whether to verify the integrity of the alias definition in the registry itself. You almost definitely won’t need to change this from the default (True).

  • sizes – Whether to return sizes of the blobs along with their hashes.

  • platform – For multi-arch aliases, return the information for this platform only.

Returns:

If sizes is falsey, a list of blob hashes (strings) which are assigned to the alias. If sizes is truthy, a list of (hash,size) tuples for each blob. For multi-arch aliases, a dict of the same per platform.

get_digest(alias: str | None = None, manifest: str | None = None, platform: str | None = None) str | Dict[str, str]

(v2 schema only) Get the hash of an alias’s configuration blob.

For an alias created using dxf, this is the hash of the first blob assigned to the alias.

For a Docker image tag, this is the same as docker inspect alias --format='{{.Id}}'.

Parameters:
  • alias – Alias name. You almost definitely will only need to pass this argument.

  • manifest – If you previously obtained a manifest, specify it here instead of alias. You almost definitely won’t need to do this.

  • platform – For multi-arch aliases, return the information for this platform only.

Returns:

Hash of the alias’s configuration blob. For multi-arch aliases, a dict of the same per platform.

get_manifest(alias: str, platform: str | None = None) str | Dict[str, str]

Get the manifest for an alias

Parameters:
  • alias – Alias name.

  • platform – For multi-arch aliases, return the information for this platform only.

Returns:

The manifest as a string (JSON). For multi-arch aliases, a dict of manifest per platform.

get_manifest_and_response(alias: str) Tuple[str, Response]

Request the manifest for an alias and return the manifest and the response.

Parameters:

alias – Alias name.

Returns:

Tuple containing the manifest as a string (JSON) and the requests.Response

head_manifest_and_response(alias: str) Tuple[str, Response]

Request the manifest for an alias and return the digest and the response.

Parameters:

alias – Alias name.

Returns:

Tuple containing the digest as str and the requests.Response

list_aliases(batch_size: int | None = None, iterate: bool = False) Iterable[str] | List[str]

List all aliases defined in the repository.

Parameters:
  • batch_size – Number of alias names to ask the server for at a time.

  • iterate – Whether to return iterator over the names or a list of all the names.

Returns:

Alias names.

mount_blob(repo: str, digest: str) str

Mount a blob from another repository in the registry.

Parameters:
  • repo – Repository containing the existing blob.

  • digest – Hash of the existing blob’s content (prefixed by sha256:).

Returns:

Hash of blob’s content.

pull_blob(digest: str, size: bool = False, chunk_size: int | None = None) Iterable[bytes] | Tuple[Iterable[bytes], int]

Download a blob from the registry given the hash of its content.

Parameters:
  • digest – Hash of the blob’s content (prefixed by sha256:).

  • size – Whether to return the size of the blob too.

  • chunk_size – Number of bytes to download at a time. Defaults to 8192.

Returns:

If size is falsey, a byte string iterator over the blob’s content. If size is truthy, a tuple containing the iterator and the blob’s size.

push_blob(filename: str | None = None, progress: Callable[[str, bytes, int], None] | None = None, data: Iterable[bytes] | None = None, digest: str | None = None, check_exists: bool = True) str

Upload a file to the registry and return its (SHA-256) hash.

The registry is content-addressable so the file’s content (aka blob) can be retrieved later by passing the hash to pull_blob().

Parameters:
  • filename – File to upload.

  • data – Data to upload if filename isn’t given. The data is uploaded in chunks and you must also pass digest.

  • digest – Hash of the data to be uploaded in data, if specified.

  • progress – Optional function to call as the upload progresses. The function will be called with the hash of the file’s content (or digest), the blob just read from the file (or chunk from data) and if filename is specified the total size of the file.

  • check_exists – Whether to check if a blob with the same hash already exists in the registry. If so, it won’t be uploaded again.

Returns:

Hash of file’s content.

set_alias(alias: str, *digests: str) str

Give a name (alias) to a set of blobs. Each blob is specified by the hash of its content.

Parameters:
  • alias – Alias name

  • digests – List of blob hashes (prefixed by sha256:).

Returns:

The registry manifest used to define the alias. You almost definitely won’t need this.

set_manifest(alias: str, manifest_json: str)

Give a name (alias) to a manifest.

Parameters:
  • alias – Alias name

  • manifest_json – A V2 Schema 2 manifest JSON string

class dxf.DXFBase(host: str, auth: Callable[[DXFBase, Response], None] | None = None, insecure: bool = False, auth_host: str | None = None, tlsverify: bool | str = True, timeout: float | None = None)

Bases: object

Class for communicating with a Docker v2 registry. Contains only operations which aren’t related to repositories.

Can act as a context manager. For each context entered, a new requests.Session is obtained. Connections to the same host are shared by the session. When the context exits, all the session’s connections are closed.

If you don’t use DXFBase as a context manager, each request uses an ephemeral session. If you don’t read all the data from an iterator returned by DXF.pull_blob() then the underlying connection won’t be closed until Python garbage collects the iterator.

Parameters:
  • host – Host name of registry. Can contain port numbers. e.g. registry-1.docker.io, localhost:5000.

  • auth – Authentication function to be called whenever authentication to the registry is required. Receives the DXFBase object and a HTTP response object. It should call authenticate() with a username, password and response before it returns.

  • insecure – Use HTTP instead of HTTPS (which is the default) when connecting to the registry.

  • auth_host – Host to use for token authentication. If set, overrides host returned by then registry.

  • tlsverify

    When set to False, do not verify TLS certificate. When pointed to a <ca bundle>.crt file use this for TLS verification. See requests.verify for more details.

  • timeout

    Optional timeout for requests. See requests.timeout for more details.

authenticate(username: str | None = None, password: str | None = None, actions: List[str] | None = None, response: Response | None = None, authorization: str | None = None, user_agent: str = 'Docker-Client/19.03.2 (linux)') str | None

Authenticate to the registry using a username and password, an authorization header or otherwise as the anonymous user.

Parameters:
  • username – User name to authenticate as.

  • password – User’s password.

  • actions – If you know which types of operation you need to make on the registry, specify them here. Valid actions are pull, push and *.

  • response – When the auth function you passed to DXFBase’s constructor is called, it is passed a HTTP response object. Pass it back to authenticate() to have it automatically detect which actions are required.

  • authorizationAuthorization header value.

  • user_agentUser-Agent header value.

Returns:

Authentication token, if the registry supports bearer tokens. Otherwise None, and HTTP Basic auth is used (if the registry requires authentication).

list_repos(batch_size: int | None = None, iterate: bool = False) List[str] | Iterable[str]

List all repositories in the registry.

Parameters:
  • batch_size – Number of repository names to ask the server for at a time.

  • iterate – Whether to return iterator over the names or a list of all the names.

Returns:

Repository names.

property token

str: Authentication token. This will be obtained automatically when you call authenticate(). If you’ve obtained a token previously, you can also set it but be aware tokens expire quickly.

dxf.hash_bytes(buf: bytes) str

Hash bytes using the same method the registry uses (currently SHA-256).

Parameters:

buf – Bytes to hash

Returns:

Hex-encoded hash of file’s content (prefixed by sha256:)

dxf.hash_file(filename: str) str

Hash a file using the same method the registry uses (currently SHA-256).

Parameters:

filename – Name of file to hash

Returns:

Hex-encoded hash of file’s content (prefixed by sha256:)

dxf.exceptions module

Module containing exceptions thrown by dxf.

exception dxf.exceptions.DXFAuthInsecureError

Bases: DXFError

Can’t authenticate over insecure (non-HTTPS) connection

exception dxf.exceptions.DXFDigestMismatchError(got, expected)

Bases: DXFUnexpectedError

Digest didn’t match expected value

Parameters:
  • got – Actual value received

  • expected – Value that was expected

exception dxf.exceptions.DXFDigestNotAvailableForSchema1

Bases: DXFError

https://github.com/docker/distribution/issues/1662#issuecomment-213101772 A schema1 manifest should always produce the same image id but defining the steps to produce directly from the manifest is not straight forward.”

exception dxf.exceptions.DXFDisallowedSignatureAlgorithmError(alg)

Bases: DXFError

Signature algorithm forbidden

Parameters:

alg (str) – Forbidden signature algorithm

exception dxf.exceptions.DXFError

Bases: Exception

Base exception class for all dxf errors

exception dxf.exceptions.DXFMountFailed

Bases: DXFError

Failed to mount blob from another repository.

exception dxf.exceptions.DXFPlatformDataNotFound(platform)

Bases: DXFError

Platform data not found

Parameters:

alg (str) – Platform

exception dxf.exceptions.DXFSignatureChainNotImplementedError

Bases: DXFError

Signature chains not supported

exception dxf.exceptions.DXFUnauthorizedError

Bases: DXFError

Registry returned authorized error

exception dxf.exceptions.DXFUnexpectedDigestMethodError(got, expected)

Bases: DXFUnexpectedError

Digest method not supported

Parameters:
  • got – Actual value received

  • expected – Value that was expected

exception dxf.exceptions.DXFUnexpectedError(got, expected)

Bases: DXFError

Unexpected value error

Parameters:
  • got – Actual value received

  • expected – Value that was expected

exception dxf.exceptions.DXFUnexpectedKeyTypeError(got, expected)

Bases: DXFUnexpectedError

Cryptographic key type not supported

Parameters:
  • got – Actual value received

  • expected – Value that was expected

exception dxf.exceptions.DXFUnexpectedStatusCodeError(got, expected)

Bases: DXFUnexpectedError

Unexpected HTTP status code

Parameters:
  • got – Actual value received

  • expected – Value that was expected

exception dxf.exceptions.DXFUnsupportedSchemaType

Bases: DXFError

Schema type (mediaType) is not recognized/supported

Indices and tables