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 callDXFBase.authenticate()
with a username, password andresponse
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) – When set to False do not verify TLS certificate
-
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. 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.
-
get_alias
(alias=None, manifest=None, verify=True, sizes=False)¶ 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
Return type: list
Returns: If
sizes
is falsey, a list of blob hashes (strings) which are assigned to the alias. Ifsizes
is truthy, a list of (hash,size) tuples for each blob.
-
get_manifest
(alias)¶ Get the manifest for an alias
Parameters: alias (str) – Alias name. Return type: str Returns: The manifest as string(JSON)
-
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.
- 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. Ifsize
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 passdigest
. - digest (str (hex-encoded SHA-256)) – 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 fromdata
) and iffilename
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.
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
- host (str) – Host name of registry. Can contain port numbers. e.g.
-
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 byDXF.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 callauthenticate()
with a username, password andresponse
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) – When set to False, do not verify TLS certificate.
-
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 toDXFBase
‘s constructor is called, it is passed a HTTP response object. Pass it back toauthenticate()
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.
-
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.
- host (str) – Host name of registry. Can contain port numbers. e.g.
-
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
-
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
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.
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
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