Parser Reference

Parser

class apolo_sdk.Parser

A set of parsing helpers, useful for building helper dataclasses from string representations.

volume(volume: str) → Volume

Parse volume string into Volume object.

The string is a three fields separated by colon characters (:): <storage-uri:container-path[:ro]>.

storage-uri is a URL on local storage, e.g. storage:folder points on <user-root>/folder directory.

container-path is a path inside a job where storage-url is mounted.

Optional ro means that storage-url is mounted in read-only mode. Writable mode is used if ro is omitted.

Raise:

ValueError if volume has invalid format.

local_image(image: str) → LocalImage

Parse image string into LocalImage.

The string should fit to the following pattern: name[:tag], e.g. "ubuntu:latest".

Raise:

ValueError if image has invalid format.

remote_image(image: str) → RemoteImage

Parse image string into RemoteImage.

The string should fit to name[:tag] or image:name[tag] patterns, e.g. "ubuntu:latest" or image:my-image:latest. The former is used for public DockerHub images, the later is for Apolo image registry.

Raise:

ValueError if image has invalid format.

envs(env: Sequence[str], env_file: Sequence[str] = ()) → EnvParseResult

Parse a sequence of env variables and a sequence of env_file file names.

Parameters:

• env (Sequence[str]) – Sequence of env variable specification. Each element can be either: - ENV_NAME. Current system env variable value will be used. Defaults to empty string. - ENV_NAME=VALUE. Given value will be used.

• env_file (Sequence[str]) – Sequence of .env files to use. File content processed same way as env parameter.

Returns:

EnvParseResult with parsing result

volumes(volume: Sequence[str]) → VolumeParseResult

Parse a sequence of volume definition into a tuple of three mappings - first one for all regular volumes, second one for volumes using secrets and third for disk volumes.

Parameters:

env (Sequence[str]) – Sequence of volumes specification. Each element can be either: - STORAGE_URI:MOUNT_PATH:RW_FLAG. - SECRET_URI:MOUNT_PATH. - DISK_URI:MOUNT_PATH:RW_FLAG.

Returns:

VolumeParseResult with parsing result

uri_to_str(uri: URL) → str

Convert URL object into str.

str_to_uri(uri: str, *, allowed_schemes: Iterable[str] = (), cluster_name: str | None = None, short: bool = False) → URL

Parse a string into normalized URL for future usage by SDK methods.

Parameters:

• uri (str) – an URI ('storage:folder/file.txt') or local file path ('/home/user/folder/file.txt') to parse.

• allowed_schemes (Iterable[str]) – an iterable of accepted URI schemes, e.g. ('file', 'storage'). No scheme check is performed by default.

• cluster_name (Optional[str]) – optional cluster name, the default cluster is used if not specified.

• short (bool) – if True, return short URL (without cluster and user names if possible). False by default.

Returns:

URL with parsed URI.

Raises:

ValueError – if uri is invalid or provides a scheme not enumerated by allowed_schemes argument.

uri_to_path(uri: URL, *, cluster_name: str | None = None) → Path

Convert URL into Path.

Raises:

ValueError – if uri has no 'file:' scheme.

path_to_uri(path: Path) → URL

Convert Path object into normalized URL with 'file:' scheme.

Parameters:

path (Path) – a path to convert.

Returns:

URL that represent a path.

normalize_uri(uri: URL, *, allowed_schemes: Iterable[str] = (), cluster_name: str | None = None, short: bool = False) → URL

Normalize uri according to current user name, cluster and allowed schemes.

Normalized form has two variants:

1. Long form: cluster and user names are always present, e.g. storage://cluster/user/dir/file.txt.

2. Short form: cluster and user are omitted if they are equal to default values given from client.config.cluster_name and client.config.username, e.g. storage:dir/file.txt.

Parameters:

• uri (URL) – an URI to normalize.

• allowed_schemes (Iterable[str]) – an iterable of accepted URI schemes, e.g. ('file', 'storage'). No scheme check is performed by default.

• cluster_name (Optional[str]) – optional cluster name, the default cluster is used if not specified.

• short (bool) – if True, return short URL (without cluster and user names if possible). False by default.

Returns:

URL with normalized URI.

Raises:

ValueError – if uri is invalid or provides a scheme not enumerated by allowed_schemes argument.

EnvParseResult

class apolo_sdk.EnvParseResult

env

Mapping of parsed environmental variables, Dict[str, str].

secret_env

Mapping of parsed using secrets environmental variables, Dict[str, URL].

VolumeParseResult

class apolo_sdk.VolumeParseResult

volumes

List of parsed regular volumes, Sequence[str].

secret_files

List of parsed secret files, List[SecretFile].

disk_volumes

List of parsed disk volumes, List[DiskVolume].