Profile

import kloch
import kloch.filesyntax

Serialization and unserialization of environment profile to disk.

class kloch.filesyntax.EnvironmentProfile(identifier: str, version: str, inherit: EnvironmentProfile | None, launchers: LauncherSerializedDict)

A profile is a collection of parameters required to start a pre-defined launcher.

This can be seen as the context/environment necessary to run a launcher thus its full name ‘Environment Profile’ that we abbreviate to profile for convenience.

Profiles can inherit each other by specifying a inherit attribute. The inheritance only merge the content of the launchers attribute between 2 profiles.

classmethod from_dict(serialized: Dict) → EnvironmentProfile

Generate a profile instance from a serialized dict object.

No type checking is performed and the user is reponsible for the correct type being stored in the dict.

get_merged_profile()

Resolve the inheritance the profile might have over another profile.

Returns:

a new instance.

identifier: str
inherit: EnvironmentProfile | None
launchers: LauncherSerializedDict
to_dict() → Dict[str, Any]

Convert a profile instance to a serialized dict object.

version: str
exception kloch.filesyntax.ProfileAPIVersionError

Issue with the ‘__magic__’ attribute of a profile.

exception kloch.filesyntax.ProfileIdentifierError

Issue with the ‘identifier’ attribute of a profile.

exception kloch.filesyntax.ProfileInheritanceError

Issue with the ‘inherit’ attribute of a profile.

kloch.filesyntax.get_all_profile_file_paths(locations: List[Path] | None = None) → List[Path]

Get all the environment-profile file paths as registred by the user.

Parameters:

locations – list of filesystem path to directory that might exist

kloch.filesyntax.get_profile_file_path(profile_id: str, profile_locations: List[Path] | None = None) → List[Path]

Get the filesystem location to the profile(s) with the given name.

Parameters:

  • profile_id – identifier that must match returned profiles.

  • profile_locations – list of filesystem path to potential existing directories containing profiles.

Returns:

list of filesystem path to existing files . Might be empty.

kloch.filesyntax.is_file_environment_profile(file_path: Path) → bool

Return True if the given file is an Environment Profile.

Parameters:

file_path – filesystem path to an existing file

kloch.filesyntax.read_profile_from_file(file_path: Path, profile_locations: List[Path] | None = None) → EnvironmentProfile

Generate an instance from a serialized file on disk.

Raises:
Parameters:

  • file_path – filesystem path to an existing valid profile file.

  • profile_locations – list of filesystem path to potential existing directories containing profiles.

kloch.filesyntax.read_profile_from_id(profile_id: str, profile_locations: List[Path] | None = None) → EnvironmentProfile

Generate a profile instance from a serialized file on disk retrieved using the given identifier.

Raises error if the profile file is not built properly.

This a convenient function wrapping read_profile_from_file() and get_profile_file_path() and assuming that no profile with the same identifier exist in the locations.

Parameters:

  • profile_id – identifier that must match the profile.

  • profile_locations – list of filesystem path to potential existing directories containing profiles.

Returns:

a profile instance

kloch.filesyntax.serialize_profile(profile: EnvironmentProfile, profile_locations: List[Path] | None = None) → str

Convert the instance to a serialized dictionnary intended to be written on disk.

Raises:

ProfileInheritanceError – if the inherited profile specified is not found on disk

kloch.filesyntax.write_profile_to_file(profile: EnvironmentProfile, file_path: Path, profile_locations: List[Path] | None = None, check_valid_id: bool = True, extra_comments: List[str] | None = None) → Path

Convert the instance to a serialized file on disk.

Raises:

ProfileIdentifierError – if check_valid_id=True and the profile identifier is not unique

Parameters:

  • profile – profile instance to write to disk

  • file_path – filesystem path to a file that might exist. parent location is expected to exist.

  • check_valid_id – if True, ensure the identifier of the profile is unique among all profile_locations

  • profile_locations – list of filesystem path to potential existing directories containing profiles.

  • extra_comments – optional lines of comments to put in the yaml header