From 819c1b75538e3acba1fc51d2e1098493db577f51 Mon Sep 17 00:00:00 2001 From: Leon Kniffki Date: Wed, 21 Jan 2026 13:48:46 +0100 Subject: [PATCH 1/5] docs: Add readme hint for library audience --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 00c0fe14..42f91989 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ # Parse features lib This library includes tooling to build and distribute [Garden Linux](https://github.com/gardenlinux/gardenlinux). +It is targeted to Garden Linux developers and not meant for end users. Features: From e1d8e3c919c5c393c5214570040e02fd912c282a Mon Sep 17 00:00:00 2001 From: Leon <37672722+Leon-hk@users.noreply.github.com> Date: Mon, 26 Jan 2026 15:18:57 +0100 Subject: [PATCH 2/5] Include "no stable API" statement Co-authored-by: Florian Wilhelm --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 42f91989..a6753fe3 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ This library includes tooling to build and distribute [Garden Linux](https://github.com/gardenlinux/gardenlinux). It is targeted to Garden Linux developers and not meant for end users. +There is no stable API. Features: From 06e134885fc42dbb0bad03997991852aae861c64 Mon Sep 17 00:00:00 2001 From: Tobias Wolf Date: Tue, 3 Mar 2026 10:23:20 +0100 Subject: [PATCH 3/5] Revert "Include "no stable API" statement" This reverts commit e1d8e3c919c5c393c5214570040e02fd912c282a. --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index a6753fe3..42f91989 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,6 @@ This library includes tooling to build and distribute [Garden Linux](https://github.com/gardenlinux/gardenlinux). It is targeted to Garden Linux developers and not meant for end users. -There is no stable API. Features: From a6bd7b005fc86f81a5b590457cd7d5055c57164c Mon Sep 17 00:00:00 2001 From: Tobias Wolf Date: Tue, 3 Mar 2026 10:26:19 +0100 Subject: [PATCH 4/5] Underline semver API stability. Signed-off-by: Tobias Wolf On-behalf-of: SAP --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 42f91989..81c2cab8 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ # Parse features lib This library includes tooling to build and distribute [Garden Linux](https://github.com/gardenlinux/gardenlinux). -It is targeted to Garden Linux developers and not meant for end users. +It is targeted to Garden Linux developers and not meant for end users. It follows syntax and intention of `Semantic Versioning ` for provided APIs. Each release reflects the intention and expected impact therefore. Features: From a7431879f01847b638d27d26da8bc6f210ed39f7 Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Tue, 3 Mar 2026 13:44:27 +0100 Subject: [PATCH 5/5] docs: shorten the README and link documentation --- README.md | 92 ++++++++++++++++++++++++++----------------------------- 1 file changed, 44 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 81c2cab8..0b5a2fe6 100644 --- a/README.md +++ b/README.md @@ -3,78 +3,74 @@ ![Test](https://github.com/gardenlinux/parse_features_lib/actions/workflows/pytests.yml/badge.svg) ![security check](https://github.com/gardenlinux/parse_features_lib/actions/workflows/bandit.yml/badge.svg) -# Parse features lib +## Garden Linux Python Library -This library includes tooling to build and distribute [Garden Linux](https://github.com/gardenlinux/gardenlinux). -It is targeted to Garden Linux developers and not meant for end users. It follows syntax and intention of `Semantic Versioning ` for provided APIs. Each release reflects the intention and expected impact therefore. +Python tooling to work with [Garden Linux](https://github.com/gardenlinux/gardenlinux) features, flavors, OCI artifacts, repositories, and releases. +It is primarily targeted at Garden Linux developers and CI pipelines rather than end users. -Features: +The library follows the intent of [Semantic Versioning](https://semver.org) for its public APIs. -- compare APT repositories -- parse features -- parse flavors -- push OCI artifacts to a registry +### Features -## Quickstart +- **Feature management**: parse, filter, and work with Garden Linux feature sets +- **Flavor processing**: parse `flavors.yaml` and generate flavor combinations +- **Repository utilities**: compare APT repositories and query package versions +- **OCI operations**: push OCI artifacts and manifests to container registries +- **S3 integration**: upload/download artifacts from S3 buckets +- **GitHub integration**: create and manage GitHub releases -### Example: get a list of features for a given cname +## Documentation -**Inclusion via poetry**: +Full documentation is available at the **Garden Linux Python Library Documentation** site: +[https://gardenlinux.github.io/python-gardenlinux-lib/](https://gardenlinux.github.io/python-gardenlinux-lib/) -`gardenlinux = { git = "https://github.com/gardenlinux/python_gardenlinux_lib", rev="0.6.0" }` +The docs include: -```python -from gardenlinux.features import Parser +- **Command-Line Interface**: `gl-features-*`, `gl-flavors-*`, `gl-oci`, `gl-s3`, `gl-gh-release` +- **API Reference**: modules, classes, and functions (e.g. `Parser`, `CName`, `Container`, `Repository`) +- **Release documentation**: versioning and release process -cname = "aws-gardener_prod" -feature_list = Parser().filter_as_list(cname) -print(f"features of {cname}:") -for feature in feature_list: - print(feature) -``` - -## Developer Documentation +## Installation -The library is documented with docstrings, which are used to generate the developer documentation available [here](https://gardenlinux.github.io/python-gardenlinux-lib/). +### Using `poetry` (from Git) -## Push OCI artifacts to a registry +Add the library as a dependency in your `pyproject.toml`: -this tool helps you to push oci artifacts. +```toml +[tool.poetry.dependencies] +gardenlinux = { git = "https://github.com/gardenlinux/python-gardenlinux-lib", rev = "0.10.5" } +``` -### Installation +Then install: ```bash -git clone https://github.com/gardenlinux/python-gardenlinux-lib.git -mkdir venv -python -m venv venv -source venv/bin/activate.sh poetry install -gl-oci --help ``` -### Usage - -The process to push a Gardenlinux build-output folder to an OCI registry is split into two steps: In the first step all files are pushed to the registry and a manifest that includes all those pushed files (layers) is created and pushed as well. An index entry that links to this manifest is created offline and written to a local file but not pushed to any index. This push to an index can be done in the second step where the local file containing the index entry is read and pushed to an index. The seperation into two steps was done because pushing of manifests takes long and writes to dedicated resources (possible to run in parallel). Updating the index on the other hand is quick but writes to a share resource (not possible to run in parallel). By splitting the process up into two steps it is possible to run the slow part in parallel and the quick part sequentially. - -#### 1. Push layers + manifest - -To push layers you have to supply the directory with the build outputs `--dir`. Also you have to supply cname (`--cname`), architecture `--arch` and version `--version` of the build. This information will be included in the manifest. You have to supply an endpoint where the artifacts shall be pushed to `--container`, for example `ghcr.io/gardenlinux/gardenlinux`. You can disable enforced HTTPS connections to your registry with `--insecure True`. You can supply `--cosign_file ` if you want to have the hash saved in ``. This can be handy to read the hash later to sign the manifest with cosign. With `--manifest_file ` you tell the program in which file to store the manifests index entry. This is the file that can be used in the next step to update the index. You can use the environment variable GL_CLI_REGISTRY_TOKEN to authenticate against the registry. Below is an example of a full program call of `push-manifest` +### Local development setup ```bash -GL_CLI_REGISTRY_TOKEN=asdf123 gl-oci push-manifest --dir build-metal-gardener_prod --container ghcr.io/gardenlinux/gl-oci --arch amd64 --version 1592.1 --cname metal-gardener_prod --cosign_file digest --manifest_file oci_manifest_entry_metal.json +git clone https://github.com/gardenlinux/python-gardenlinux-lib.git +cd python-gardenlinux-lib +python -m venv venv +source venv/bin/activate +poetry install ``` -#### 2. Update index with manifest entry +## Quickstart -Parameters that are the same as for `push-manifest`: +### Example: list features for a given `cname` -- env-var `GL_CLI_REGISTRY_TOKEN` -- `--version` -- `--container` -- `--manifest-file` this time this parameter adjusts the manifest entry file to be read from instead of being written to +```python +from gardenlinux.features import Parser -A full example looks like this: +cname = "aws-gardener_prod" +feature_list = Parser().filter_as_list(cname) -```bash -GL_CLI_REGISTRY_TOKEN=asdf123 gl-oci update-index --container ghcr.io/gardenlinux/gl-oci --version 1592.1 --manifest_file oci_manifest_entry_metal.json +print(f"features of {cname}:") +for feature in feature_list: + print(feature) ``` + +For more examples and for all CLI tools, see the **Command-Line Interface** and **API Reference** sections in the docs: +[https://gardenlinux.github.io/python-gardenlinux-lib/](https://gardenlinux.github.io/python-gardenlinux-lib/)