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, repo, auth=None, insecure=False, auth_host=None, tlsverify=True)

Bases: dxf.DXFBase

Class for operating on a Docker v2 repositories.

Parameters:
  • host (str) – Host name of registry. Can contain port numbers. e.g. registry-1.docker.io, localhost:5000.
  • repo (str) – 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 (function(dxf_obj, response)) – 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 (bool) – Use HTTP instead of HTTPS (which is the default) when connecting to the registry.
  • auth_host (str) – Host to use for token authentication. If set, overrides host returned by then registry.
  • tlsverify (bool or str) – 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.
api_version_check()

Performs API version check

Return type:tuple
Returns:verson check response as a string (JSON) and requests.Response
blob_size(digest)

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

Parameters:digest (str) – Hash of the blob’s content (prefixed by sha256:).
Return type:long
Returns:Whether the blob exists.
del_alias(alias)

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 (str) – Alias name.
Return type:list
Returns:A list of blob hashes (strings) which were assigned to the alias.
del_blob(digest)

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

Parameters:digest (str) – Hash of the blob’s content (prefixed by sha256:).
classmethod from_base(base, repo)

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

Parameters:
  • base (DXFBase) – Existing DXFBase object.
  • repo (str) – 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.

Return type:

DXF

get_alias(alias=None, manifest=None, verify=True, sizes=False, dcd=None)

Get the blob hashes assigned to an alias.

Parameters:
  • alias (str) – Alias name. You almost definitely will only need to pass this argument.
  • manifest (str) – If you previously obtained a manifest, specify it here instead of alias. You almost definitely won’t need to do this.
  • verify (bool) – (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 (bool) – Whether to return sizes of the blobs along with their hashes
  • dcd (str) – (if manifest is specified) The Docker-Content-Digest header returned when getting the manifest. If present, this is checked against the manifest.
Return type:

list

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.

get_digest(alias=None, manifest=None, verify=True, dcd=None)

(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 (str) – Alias name. You almost definitely will only need to pass this argument.
  • manifest (str) – If you previously obtained a manifest, specify it here instead of alias. You almost definitely won’t need to do this.
  • verify (bool) – (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).
  • dcd (str) – (if manifest is specified) The Docker-Content-Digest header returned when getting the manifest. If present, this is checked against the manifest.
Return type:

str

Returns:

Hash of the alias’s configuration blob.

get_manifest(alias)

Get the manifest for an alias

Parameters:alias (str) – Alias name.
Return type:str
Returns:The manifest as string (JSON)
get_manifest_and_response(alias)

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

Parameters:alias (str) – Alias name.
Return type:tuple
Returns:Tuple containing the manifest as a string (JSON) and the requests.Response
list_aliases(batch_size=None, iterate=False)

List all aliases defined in the repository.

Parameters:
  • batch_size (int) – Number of alias names to ask the server for at a time.
  • iterate (bool) – Whether to return iterator over the names or a list of all the names.
Return type:

list or iterator of strings

Returns:

Alias names.

pull_blob(digest, size=False, chunk_size=None)

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

Parameters:
  • digest (str) – Hash of the blob’s content (prefixed by sha256:).
  • size (bool) – Whether to return the size of the blob too.
  • chunk_size (int) – Number of bytes to download at a time. Defaults to 8192.
Return type:

iterator

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=None, progress=None, data=None, digest=None, check_exists=True)

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 (str) – File to upload.
  • data (Generator or iterator) – Data to upload if filename isn’t given. The data is uploaded in chunks and you must also pass digest.
  • digest (str (hex-encoded SHA-256, prefixed by sha256:)) – Hash of the data to be uploaded in data, if specified.
  • progress (function(dgst, chunk, size)) – 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 (bool) – Whether to check if a blob with the same hash already exists in the registry. If so, it won’t be uploaded again.
Return type:

str

Returns:

Hash of file’s content.

set_alias(alias, *digests)

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

Parameters:
  • alias (str) – Alias name
  • digests (list of strings) – List of blob hashes (prefixed by sha256:).
Return type:

str

Returns:

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

set_manifest(alias, manifest_json)

Give a name (alias) to a manifest.

Parameters:
  • alias (str) – Alias name
  • manifest_json – A V2 Schema 2 manifest JSON string
class dxf.DXFBase(host, auth=None, insecure=False, auth_host=None, tlsverify=True)

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 (str) – Host name of registry. Can contain port numbers. e.g. registry-1.docker.io, localhost:5000.
  • auth (function(dxf_obj, response)) – 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 (bool) – Use HTTP instead of HTTPS (which is the default) when connecting to the registry.
  • auth_host (str) – Host to use for token authentication. If set, overrides host returned by then registry.
  • tlsverify (bool or str) –

    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.

authenticate(username=None, password=None, actions=None, response=None, authorization=None)

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

Parameters:
  • username (str) – User name to authenticate as.
  • password (str) – User’s password.
  • actions (list) – If you know which types of operation you need to make on the registry, specify them here. Valid actions are pull, push and *.
  • response (requests.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.
  • authorization (str) – Authorization header value.
Return type:

str

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=None, iterate=False)

List all repositories in the registry.

Parameters:
  • batch_size (int) – Number of repository names to ask the server for at a time.
  • iterate (bool) – Whether to return iterator over the names or a list of all the names.
Return type:

list or iterator of strings

Returns:

Repository names.

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)

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

Parameters:buf (binary str) – Bytes to hash
Return type:str
Returns:Hex-encoded hash of file’s content (prefixed by sha256:)
dxf.hash_file(filename)

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

Parameters:filename (str) – Name of file to hash
Return type:str
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: dxf.exceptions.DXFError

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

exception dxf.exceptions.DXFDigestMismatchError(got, expected)

Bases: dxf.exceptions.DXFUnexpectedError

Digest didn’t match expected value

Parameters:
  • got – Actual value received
  • expected – Value that was expected
exception dxf.exceptions.DXFDigestNotAvailableForSchema1

Bases: dxf.exceptions.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: dxf.exceptions.DXFError

Signature algorithm forbidden

Parameters:alg (str) – Forbidden signature algorithm
exception dxf.exceptions.DXFError

Bases: exceptions.Exception

Base exception class for all dxf errors

exception dxf.exceptions.DXFSignatureChainNotImplementedError

Bases: dxf.exceptions.DXFError

Signature chains not supported

exception dxf.exceptions.DXFUnauthorizedError

Bases: dxf.exceptions.DXFError

Registry returned authorized error

exception dxf.exceptions.DXFUnexpectedDigestMethodError(got, expected)

Bases: dxf.exceptions.DXFUnexpectedError

Digest method not supported

Parameters:
  • got – Actual value received
  • expected – Value that was expected
exception dxf.exceptions.DXFUnexpectedError(got, expected)

Bases: dxf.exceptions.DXFError

Unexpected value error

Parameters:
  • got – Actual value received
  • expected – Value that was expected
exception dxf.exceptions.DXFUnexpectedKeyTypeError(got, expected)

Bases: dxf.exceptions.DXFUnexpectedError

Cryptographic key type not supported

Parameters:
  • got – Actual value received
  • expected – Value that was expected
exception dxf.exceptions.DXFUnexpectedStatusCodeError(got, expected)

Bases: dxf.exceptions.DXFUnexpectedError

Unexpected HTTP status code

Parameters:
  • got – Actual value received
  • expected – Value that was expected

Indices and tables