cki_lib.yaml

Set keys in YAML data

usage: python3 -m cki_lib.yaml set-value [-h] [--format {yaml,json}] key value

Set a dot-delimited key

positional arguments:
  key         dot-delimited key
  value       YAML-formatted value

options:
  -h, --help  show this help message and exit
  --format {yaml,json}  output format (default: yaml)

Reads from stdin and writes to stdout.

Example:

$ python -m cki_lib.yaml set-value foo.1 'qux: true' <<< 'foo: [bar, baz]'
---
foo:
  - bar
  - qux: true

Delete keys from YAML data

usage: python3 -m cki_lib.yaml del [-h] [--format {yaml,json}] key

Set a dot-delimited key

positional arguments:
  key         dot-delimited key

options:
  -h, --help  show this help message and exit
  --format {yaml,json}  output format (default: yaml)

Reads from stdin and writes to stdout.

Example:

$ python -m cki_lib.yaml del foo.1 <<< 'foo: [bar, baz]'
---
foo:
  - bar

Dump YAML data

usage: python3 -m cki_lib.yaml dump [-h] [--format {yaml,json}]

Dump YAML data

options:
  -h, --help  show this help message and exit
  --format {yaml,json}  output format (default: yaml)

Reads from stdin and writes to stdout.

Example:

$ python -m cki_lib.yaml dump <<< 'foo: [bar, baz]'
---
foo:
  - bar
  - baz

Validate YAML files with a JSON schema

usage: python3 -m cki_lib.yaml validate [-h]
                                        [--schema SCHEMA]
                                        [--process-config-tree]
                                        [--resolve-includes]
                                        [--resolve-references]
                                        [files ...]
Validation of YAML files

positional arguments:
  files            paths of YAML files to validate

options:
  -h, --help             show this help message and exit
  --schema SCHEMA        path of JSON schema file
  --process-config-tree  support .default and .extends
  --resolve-includes     support .include
  --resolve-references   support !reference tags

Reads from stdin if no files are passed.

CKI schema support

The validation code tries to determine the values for the following parameters automatically:

Exit codes

Processing features

The validate command’s --resolve-includes, --resolve-references, and --process-config-tree flags (and the corresponding cki_lib.yaml.load() parameters) enable the processing stages described below. They are applied in order: includes first, then references, then config tree.

.include (--resolve-includes)

Merges other YAML files into the document before further processing. The .include key is consumed (removed from the result).

.include: [base.yml, 'overrides/*.yml']
key: value

Supported include forms:

• Literal relative paths: .include: [other.yml, dir/more.yml]
• URLs: .include: https://example.com/config.yml
• Glob patterns: .include: ['vars.d/*.yml'] (supports ** for recursive matching)

Merge order: included files are merged first (in list order), then the document’s own keys are merged on top (document keys win on conflict). Within a glob expansion, files are sorted alphabetically.

Constraints:

• Glob patterns matching no files raise FileNotFoundError
• Glob paths resolving outside the parent directory raise ValueError
• Only files are included (directories matching a glob are skipped)

!reference tag (--resolve-references)

Resolves !reference [path, to, node] tags by looking up the referenced path in the document root, similar to GitLab CI reference tags.

defaults:
  timeout: 30
job:
  timeout: !reference [defaults, timeout]

.extends and .default (--process-config-tree)

Processes a dict-of-dicts as a configuration tree with inheritance, similar to GitLab CI extends:

• .extends: other_key (or a list) — inherit from named sibling(s)
• .default — automatically inherited by all entries without explicit .extends
• Keys starting with . are removed from the final output

.default:
  retries: 3
.base:
  timeout: 60
job:
  .extends: .base
  command: run
# Result: {job: {retries: 3, timeout: 60, command: run}}

.schema (auto-detection)

A document can specify its own JSON schema inline:

.schema: python.module/path/to/schema.yml

The schema is loaded via importlib.resources and used for validation. It can also auto-enable processing features via custom keys ($ckiResolveIncludes, $ckiResolveReferences, $ckiProcessConfigTree) — see CKI schema support above.