dxf module¶
|
Class for communicating with a Docker v2 registry. |
|
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 callDXFBase.authenticate()
with a username, password andresponse
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 existingDXFBase
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 withbase
but which can also be used to operate on therepo
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. Ifsizes
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. Ifsize
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 passdigest
.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 fromdata
) and iffilename
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 byDXF.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 callauthenticate()
with a username, password andresponse
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 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 –
Authorization
header value.user_agent –
User-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.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