python-gardenlinux-lib documentation

APT module

class gardenlinux.apt.Debsrc(deb_source: str, deb_version: str)

Class to reflect deb sources.

Author:

Garden Linux Maintainers

Copyright:

Copyright 2024 SAP SE

Package:

gardenlinux

Subpackage:

apt

Since:

0.7.0

License:

https://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0

class gardenlinux.apt.DebsrcFile

Class to represent deb sources loaded and parsed as dict.

Author:

Garden Linux Maintainers

Copyright:

Copyright 2024 SAP SE

Package:

gardenlinux

Subpackage:

apt

Since:

0.7.0

License:

https://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0

read(f: TextIO) → None

Read and parse the given TextIO data to extract deb sources.

Parameters:

f – TextIO data to parse

Since:

0.7.0

class gardenlinux.apt.GardenLinuxRepo(dist: str, url: str | None = 'http://packages.gardenlinux.io/gardenlinux', components: list[str] | None = ['main'])

Class to reflect APT based GardenLinux repositories.

Author:

Garden Linux Maintainers

Copyright:

Copyright 2024 SAP SE

Package:

gardenlinux

Subpackage:

apt

Since:

0.7.0

License:

https://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0

get_package_version_by_name(name: str) → list[tuple[str, str]]

Returns the package version matching the given name.

Parameters:

name – name of package to find

Returns:

(list) Packages matching the input name

Since:

0.7.0

get_packages_versions() → list[tuple[str, str]]

Returns list of (package, version) tuples

Returns:

(list) Packages versions

Since:

0.7.0

Features module

class gardenlinux.features.CName(cname: str, arch: str | None = None, commit_hash: str | None = None, version: str | None = None)

Class to represent a canonical name (cname).

Author:

Garden Linux Maintainers

Copyright:

Copyright 2024 SAP SE

Package:

gardenlinux

Subpackage:

features

Since:

0.7.0

License:

https://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0

property arch: str | None

Returns the architecture for the cname parsed.

Returns:

(str) CName architecture

Since:

0.7.0

property cname: str

Returns the cname parsed.

Returns:

(str) CName

Since:

0.7.0

property commit_hash: str

Returns the commit hash if part of the cname parsed.

Returns:

(str) Commit hash

Since:

1.0.0

property commit_id: str | None

Returns the commit ID if part of the cname parsed.

Returns:

(str) Commit ID

Since:

0.7.0

property feature_set: str

Returns the feature set for the cname parsed.

Returns:

(str) Feature set of the cname

Since:

0.7.0

property feature_set_element: str

Returns the feature set of type “element” for the cname parsed.

Returns:

(str) Feature set elements

Since:

1.0.0

property feature_set_flag: str

Returns the feature set of type “flag” for the cname parsed.

Returns:

(str) Feature set flags

Since:

1.0.0

property feature_set_platform: str

Returns the feature set of type “platform” for the cname parsed.

Returns:

(str) Feature set platform

Since:

1.0.0

property flavor: str

Returns the flavor for the cname parsed.

Returns:

(str) Flavor

Since:

0.7.0

load_from_release_file(release_file: PathLike[str] | str) → None

Loads and parses a release metadata file.

Parameters:

release_file – Release metadata file

Since:

1.0.0

property platform: str

Returns the feature set of type “platform” for the cname parsed.

Returns:

(str) Feature set platforms

Since:

0.7.0

property platform_variant: str | None

Returns the platform variant for the cname parsed.

Returns:

(str) Platform variant

Since:

1.0.0

property release_metadata_string: str

Returns the release metadata describing the given CName instance.

Returns:

(str) Release metadata describing the given CName instance

Since:

1.0.0

save_to_release_file(release_file: PathLike[str] | str, overwrite: bool | None = False) → None

Saves the release metadata file.

Parameters:

release_file – Release metadata file

Since:

1.0.0

property version: str | None

Returns the version if part of the cname parsed.

Returns:

(str) Version

Since:

0.7.0

property version_and_commit_id: str | None

Returns the version and commit ID if part of the cname parsed.

Returns:

(str) Version and commit ID

Since:

0.7.0

property version_epoch: int | None

Returns the GardenLinux version epoch of the cname parsed.

Returns:

(str) GardenLinux version epoch

Since:

1.0.0

class gardenlinux.features.Parser(gardenlinux_root: str | None = None, feature_dir_name: str = 'features', logger: Logger | None = None)

Parser for GardenLinux features.

Author:

Garden Linux Maintainers

Copyright:

Copyright 2024 SAP SE

Package:

gardenlinux

Subpackage:

features

Since:

0.7.0

License:

https://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0

filter(cname: str, ignore_excludes: bool = False, additional_filter_func: Callable[[str], bool] | None = None) → networkx.Graph

Filters the features graph.

Parameters:

  • cname – Canonical name to filter

  • ignore_excludes – Ignore exclude feature files

  • additional_filter_func – Additional filter function

Returns:

(networkx.Graph) Filtered features graph

Since:

0.7.0

filter_as_dict(cname: str, ignore_excludes: bool = False, additional_filter_func: Callable[[str], bool] | None = None) → Dict[str, List[str]]

Filters the features graph and returns it as a dict.

Parameters:

  • cname – Canonical name to filter

  • ignore_excludes – Ignore exclude feature files

  • additional_filter_func – Additional filter function

Returns:

(dict) List of features for a given cname, split into platform, element and flag

Since:

0.7.0

filter_as_list(cname: str, ignore_excludes: bool = False, additional_filter_func: Callable[[str], bool] | None = None) → List[str]

Filters the features graph and returns it as a list.

Parameters:

  • cname – Canonical name to filter

  • ignore_excludes – Ignore exclude feature files

  • additional_filter_func – Additional filter function

Returns:

(list) Features list for a given cname

Since:

0.7.0

filter_as_string(cname: str, ignore_excludes: bool = False, additional_filter_func: Callable[[str], bool] | None = None) → str

Filters the features graph and returns it as a string.

Parameters:

  • cname – Canonical name to filter

  • ignore_excludes – Ignore exclude feature files

  • additional_filter_func – Additional filter function

Returns:

(str) Comma separated string with the expanded feature set for the cname

Since:

0.7.0

filter_based_on_feature_set(feature_set: List[str], ignore_excludes: bool = False, additional_filter_func: Callable[[str], bool] | None = None) → networkx.Graph

Filters the features graph based on a feature set given.

Parameters:

  • feature_set – Feature set to filter

  • ignore_excludes – Ignore exclude feature files

  • additional_filter_func – Additional filter function

Returns:

(networkx.Graph) Filtered features graph

Since:

0.9.2

filter_graph_as_dict(graph: networkx.Graph) → Dict[str, List[str]]

Filters the features graph and returns it as a dict.

Parameters:

graph – Features graph

Returns:

(dict) List of features for a given cname, split into platform, element and flag

Since:

0.9.2

filter_graph_as_list(graph: networkx.Graph) → List[str]

Filters the features graph and returns it as a list.

Parameters:

graph – Features graph

Returns:

(list) Features list for a given cname

Since:

0.9.2

filter_graph_as_string(graph: networkx.Graph) → str

Filters the features graph and returns it as a string.

Parameters:

graph – Features graph

Returns:

(str) Comma separated string with the expanded feature set for the cname

Since:

0.9.2

static get_flavor_as_feature_set(cname: str) → List[str]

Returns the features of a given canonical name.

Parameters:

cname – Canonical name

Returns:

(list) Features of the cname

Since:

1.0.0

static get_flavor_from_feature_set(sorted_features: List[str]) → str

Get the base cname for the feature set given.

Parameters:

sorted_features – Sorted feature set

Returns:

(str) Base cname

Since:

0.7.0

property graph: networkx.Graph

Returns the features graph based on the GardenLinux features directory.

Returns:

(networkx.Graph) Features graph

Since:

0.7.0

static set_default_gardenlinux_root_dir(root_dir: str) → None

Sets the default GardenLinux root directory used.

Parameters:

root_dir – GardenLinux root directory

Since:

0.7.0

static sort_graph_nodes(graph: networkx.Graph) → List[str]

Sorts graph nodes by feature type.

Parameters:

graph – Graph to sort

Returns:

(list) Sorted feature set

Since:

0.7.0

static sort_reversed_graph_nodes(graph: networkx.Graph) → List[str]

Sorts graph nodes by feature type.

Parameters:

graph – Graph to reverse and sort

Returns:

(list) Reversed and sorted feature set

Since:

0.7.0

static subset(input_set: Set[str], order_list: List[str]) → List[str]

Returns items from order_list if given in input_set.

Parameters:

  • input_set – Set of values for filtering

  • order_list – Set of values to be filtered

Returns:

(list) Subset

Since:

1.0.0

Flavors module

class gardenlinux.flavors.Parser(data: str, logger: Logger | None = None)

Parser for GardenLinux flavors.yaml.

Author:

Garden Linux Maintainers

Copyright:

Copyright 2024 SAP SE

Package:

gardenlinux

Subpackage:

flavors

Since:

0.7.0

License:

https://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0

filter(include_only_patterns: List[str] = [], wildcard_excludes: List[str] = [], only_build: bool = False, only_test: bool = False, only_test_platform: bool = False, only_publish: bool = False, filter_categories: List[str] = [], exclude_categories: List[str] = []) → List[Tuple[Any, str]]

Filters flavors data and generates combinations.

Parameters:

  • include_only_patterns – Include pattern list

  • wildcard_excludes – Exclude wildcard list

  • only_build – Return only build-enabled flavors

  • only_test – Return only test-enabled flavors

  • only_test_platform – Return only platform-test-enabled flavors

  • only_publish – Return only flavors to be published

  • filter_categories – List of categories to include

  • exclude_categories – List of categories to exclude

Returns:

(list) Filtered flavors

Since:

0.7.0

static group_by_arch(combinations: List[Tuple[Any, str]]) → Dict[str, List[str]]

Groups combinations by architecture into a dictionary.

Parameters:

combinations – Flavor combinations to group

Returns:

(list) Grouped flavor combinations

Since:

0.7.0

static remove_arch(combinations: List[Tuple[Any, str]]) → List[str]

Removes the architecture from combinations.

Parameters:

combinations – Flavor combinations to remove the architecture

Returns:

(list) Changed flavor combinations

Since:

0.7.0

static should_exclude(combination: str, excludes: List[str], wildcard_excludes: List[str]) → bool

Checks if a combination should be excluded based on exact match or wildcard patterns.

Parameters:

  • combination – Feature

  • excludes – List of features to exclude

  • wildcard_excludes – List of feature wildcards to exclude

Returns:

(bool) True if excluded

Since:

0.7.0

static should_include_only(combination: str, include_only_patterns: List[str]) → bool

Checks if a combination should be included based on –include-only wildcard patterns. If no patterns are provided, all combinations are included by default.

Parameters:

  • combination – Feature

  • include_only_patterns – List of features to include

Returns:

(bool) True if included

Since:

0.7.0

Git module

class gardenlinux.git.Repository(git_directory: PathLike[str] | str = '.', logger: Logger | None = None, **kwargs: Any)

Repository operations handler based on the given Git directory.

Author:

Garden Linux Maintainers

Copyright:

Copyright 2024 SAP SE

Package:

gardenlinux

Subpackage:

git

Since:

0.10.0

License:

https://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0

static checkout_repo(git_directory: PathLike[str] | str, repo_url: str = 'https://github.com/gardenlinux/gardenlinux', branch: str = 'main', commit: str | None = None, pathspecs: List[str] | None = None, logger: Logger | None = None, **kwargs: Any) → Any

Returns the root Git Repo instance.

Returns:

(object) Git Repo instance

Since:

0.10.0

static checkout_repo_sparse(git_directory: PathLike[str] | str, pathspecs: List[str] = [], repo_url: str = 'https://github.com/gardenlinux/gardenlinux', branch: str = 'main', commit: str | None = None, logger: Logger | None = None, **kwargs: Any) → Any

Sparse checkout given Git repository and return the Repository instance.

Returns:

(object) Git Repository instance

Since:

0.10.0

property commit_id: str

Returns the commit ID for Git HEAD.

Returns:

(str) Git commit ID

Since:

0.10.0

property root: Path

Returns the root directory of the current Git repository.

Returns:

(object) Git root directory

Since:

0.10.0

property root_repo: Any

Returns the root Git Repository instance.

Returns:

(object) Git root Repository instance

Since:

0.10.0

OCI module

class gardenlinux.oci.Container(container_url: str, insecure: bool = False, token: str | None = None, logger: Logger | None = None)

OCI container instance to provide methods for interaction.

Author:

Garden Linux Maintainers

Copyright:

Copyright 2024 SAP SE

Package:

gardenlinux

Subpackage:

oci

Since:

0.7.0

License:

https://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0

generate_image_manifest(cname: str, architecture: str | None = None, version: str | None = None, commit: str | None = None, feature_set: str | None = None) → ImageManifest

Generates an OCI image manifest

Parameters:

  • cname – Canonical name of the manifest

  • architecture – Target architecture of the manifest

  • version – Artifacts version of the manifest

  • commit – The commit hash of the manifest

  • feature_set – The expanded list of the included features of this manifest

Returns:

(object) OCI image manifest

Since:

0.10.0

generate_index() → Index

Generates an OCI image index

Returns:

(object) OCI image index

Since:

0.7.0

generate_manifest(version: str | None = None, commit: str | None = None) → Manifest

Generates an OCI manifest

Parameters:

  • cname – Canonical name of the manifest

  • architecture – Target architecture of the manifest

  • version – Artifacts version of the manifest

  • commit – The commit hash of the manifest

  • feature_set – The expanded list of the included features of this manifest

Returns:

(object) OCI manifest

Since:

0.9.2

static get_artifacts_metadata_from_files(files: List[str], arch: str) → List[Dict[str, Any]]

Returns OCI layer metadata for the given list of files.

Parameters:

  • files – a list of filenames (not paths) to set oci_metadata for

  • arch – arch of the target image

Returns:

(list) List of dicts, where each dict represents a layer

Since:

0.7.0

push_index_for_tags(index: Index, tags: List[str]) → None

Push tags for an given OCI image index.

Parameters:

  • index – OCI image index

  • tags – List of tags to push the index for

Since:

0.7.0

push_index_from_directory(manifests_dir: PathLike[str] | str, additional_tags: List[str] | None = None) → None

Replaces an old manifest entries with new ones

Parameters:

  • manifests_dir – Directory where the manifest entries are read from

  • additional_tags – Additional tags to push the index with

Since:

0.7.0

push_manifest(manifest: Manifest, manifest_file: str | None = None, additional_tags: List[str] | None = None) → Manifest

Pushes an OCI image manifest.

Parameters:

  • manifest – OCI image manifest

  • artifacts_with_metadata – A list of file names and their artifacts metadata

  • manifest_file – File name where the modified manifest is written to

  • additional_tags – Additional tags to push the manifest with

Returns:

(object) OCI image manifest

Since:

0.7.0

push_manifest_and_artifacts(manifest: ImageManifest, artifacts_with_metadata: list[Dict[str, Any]], artifacts_dir: PathLike[str] | str = '.build', manifest_file: str | None = None, additional_tags: List[str] | None = None) → Manifest

Pushes an OCI image manifest and its artifacts.

Parameters:

  • manifest – OCI image manifest

  • artifacts_with_metadata – A list of file names and their artifacts metadata

  • artifacts_dir – Path of the image artifacts

  • manifest_file – File name where the modified manifest is written to

  • additional_tags – Additional tags to push the manifest with

Returns:

(object) OCI image manifest

Since:

0.7.0

push_manifest_and_artifacts_from_directory(manifest: ImageManifest, artifacts_dir: PathLike[str] | str = '.build', manifest_file: str | None = None, additional_tags: List[str] | None = None) → Manifest

Pushes an OCI image manifest and its artifacts from the given directory.

Parameters:

  • manifest – OCI image manifest

  • artifacts_dir – Path of the image artifacts

  • manifest_file – File name where the modified manifest is written to

  • additional_tags – Additional tags to push the manifest with

Returns:

(object) OCI image manifest

Since:

0.7.0

push_manifest_for_tags(manifest: Manifest, tags: List[str]) → None

Push tags for an given OCI image manifest.

Parameters:

  • manifest – OCI image manifest

  • tags – List of tags to push the index for

Since:

0.7.0

read_or_generate_index() → Index

Reads from registry or generates the OCI image index.

Returns:

OCI image index

Since:

0.7.0

read_or_generate_manifest(cname: str | None = None, architecture: str | None = None, version: str | None = None, commit: str | None = None, feature_set: str | None = None) → Manifest | ImageManifest

Reads from registry or generates the OCI manifest.

Parameters:

  • cname – Canonical name of the manifest

  • architecture – Target architecture of the manifest

  • version – Artifacts version of the manifest

  • commit – The Git commit ID of the manifest

  • feature_set – The expanded list of the included features of this manifest

Returns:

OCI image manifest

Since:

0.7.0

class gardenlinux.oci.ImageManifest(*args: Any, **kwargs: Any)

OCI image manifest

Author:

Garden Linux Maintainers

Copyright:

Copyright 2024 SAP SE

Package:

gardenlinux

Subpackage:

oci

Since:

0.10.0

License:

https://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0

append_layer(layer: Layer) → None

Appends the given OCI image manifest layer to the manifest

Parameters:

layer – OCI image manifest layer

Since:

0.7.0

property arch: str

Returns the architecture of the OCI image manifest.

Returns:

(str) OCI image architecture

Since:

0.7.0

property cname: str

Returns the GardenLinux canonical name of the OCI image manifest.

Returns:

(str) OCI image GardenLinux canonical name

Since:

0.7.0

property feature_set: str

Returns the GardenLinux feature set of the OCI image manifest.

Returns:

(str) OCI image GardenLinux feature set

Since:

0.7.0

property flavor: str

Returns the GardenLinux flavor of the OCI image manifest.

Returns:

(str) OCI image GardenLinux flavor

Since:

0.7.0

property layers_as_dict: Dict[str, Any]

Returns the OCI image manifest layers as a dictionary.

Returns:

(dict) OCI image manifest layers with title as key

Since:

0.7.0

property version: str

Returns the GardenLinux version of the OCI image manifest.

Returns:

(str) OCI image GardenLinux version

Since:

0.7.0

write_metadata_file(manifest_file_path_name: PathLike[str] | str) → None

Create OCI image manifest metadata and write it to the file given.

Parameters:

manifest_file_path_name – OCI image manifest metadata file

Since:

0.7.0

class gardenlinux.oci.Index(*args: Any, **kwargs: Any)

OCI image index

Author:

Garden Linux Maintainers

Copyright:

Copyright 2024 SAP SE

Package:

gardenlinux

Subpackage:

oci

Since:

0.7.0

License:

https://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0

append_manifest(manifest: Dict[str, Any]) → None

Appends the given OCI image manifest to the index

Parameters:

manifest – OCI image manifest

Since:

0.7.0

property json: bytes

Returns the OCI image index as a JSON

Returns:

(bytes) OCI image index as JSON

Since:

0.7.0

property manifests_as_dict: Dict[str, Dict[str, Any]]

Returns the OCI image manifests of the index

Returns:

(dict) OCI image manifests with CNAME or digest as key

Since:

0.7.0

class gardenlinux.oci.Layer(blob_path: PathLike[str] | str, media_type: str | None = None, is_dir: bool = False)

OCI image layer

Author:

Garden Linux Maintainers

Copyright:

Copyright 2024 SAP SE

Package:

gardenlinux

Subpackage:

oci

Since:

0.7.0

License:

https://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0

property dict: Dict[Any, Any]

Return a dictionary representation of the layer

Returns:

(dict) OCI manifest layer metadata dictionary

Since:

0.7.2

static generate_metadata_from_file_name(file_name: PathLike[str] | str, arch: str) → Dict[str, Any]

Generates OCI manifest layer metadata for the given file path and name.

Parameters:

  • file_name – File path and name of the target layer

  • arch – The arch of the target image

Returns:

(dict) OCI manifest layer metadata dictionary

Since:

0.7.0

static lookup_media_type_for_file_name(file_name: PathLike[str] | str) → str

Looks up the media type based on file name or extension.

Parameters:

file_name – File path and name of the target layer

Returns:

(str) Media type

Since:

0.7.0

class gardenlinux.oci.Manifest(*args: Any, **kwargs: Any)

OCI image manifest

Author:

Garden Linux Maintainers

Copyright:

Copyright 2024 SAP SE

Package:

gardenlinux

Subpackage:

oci

Since:

0.7.0

License:

https://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0

property commit: str

Returns the GardenLinux Git commit ID of the OCI manifest.

Returns:

(str) OCI GardenLinux Git commit ID

Since:

0.7.0

config_from_dict(config: Dict[str, Any], annotations: Dict[str, Any]) → None

Write a new OCI configuration to file, and generate oci metadata for it.

For reference see https://github.com/opencontainers/image-spec/blob/main/config.md annotations, mediatype, size, digest are not part of digest and size calculation, and therefore must be attached to the output dict and not written to the file.

Parameters:

  • config – dict with custom configuration (the payload of the configuration)

  • annotations – dict with custom annotations to be attached to metadata part of config

Since:

0.7.0

property config_json: bytes

Returns the OCI image manifest config.

Returns:

(bytes) OCI image manifest config

Since:

0.7.0

property digest: str

Returns the OCI image manifest digest.

Returns:

(str) OCI image manifest digest

Since:

0.7.0

property json: bytes

Returns the OCI image manifest as a JSON

Returns:

(bytes) OCI image manifest as JSON

Since:

0.7.0

property size: int

Returns the OCI image manifest JSON size in bytes.

Returns:

(int) OCI image manifest JSON size in bytes

Since:

0.7.0

property version: str

Returns the GardenLinux version of the OCI image manifest.

Returns:

(str) OCI image GardenLinux version

Since:

0.7.0

Indices and tables