saltext.github.utils.gh.grains_files

Custom repository grains sourced from in-repo YAML/JSON files, as declared via the resource:grains_files key of the github resource type.

A declaration maps grain namespaces to file specifications:

grains_files:
  copier:
    path: .copier-answers.yml
    exclude:
      - "_*"
  data:
    path:
      - .github/metadata.json
      - .github/other-metadata.json
    include:
      - team
      - org:config
      - service_tier: service:tier

include/exclude entries are fnmatch patterns matched case-sensitively against colon-delimited key paths, the same idiom Salt uses for grain targeting. Note that * is not segment-aware (it can cross : boundaries) and keys containing : cannot be addressed. Mapping entries in include rename: the value at the exact source path (scalar or subtree) is exposed under the new name as a flat namespace key. Renames are not subject to exclude. A plain mapping as the include value is shorthand for a rename-only list.

The special _ namespace merges its keys into the root grains level instead of below a namespace key. Custom grains never overwrite existing ones – the builtin identity grains and earlier namespaces always win.

saltext.github.utils.gh.grains_files.RESERVED_KEYS = frozenset({'archived', 'clone_url', 'created_at', 'custom_properties', 'default_branch', 'description', 'disabled', 'fork', 'full_name', 'has_discussions', 'has_pages', 'has_projects', 'homepage', 'html_url', 'id', 'is_template', 'language', 'license', 'owner', 'private', 'repo', 'ssh_url', 'topics', 'visibility'})

Grain keys provided by the resource type itself. grains_files namespaces must not shadow them — the resource identity is not overridable by repository contents.

saltext.github.utils.gh.grains_files.validate(spec)

Normalize and validate a grains_files declaration value.

Returns the normalized form, a mapping of namespace to {"path": [str, ...], "include": [str | (new_name, source), ...] | None, "exclude": [str, ...]}. Raises a CommandExecutionError when the declaration is malformed.

spec

The declaration value. None is treated as unset.

saltext.github.utils.gh.grains_files.load_mapping(text, *, path)

Parse a file’s text as YAML (which includes JSON) into a mapping of JSON-plain values, or None (logging a warning) when the text does not parse or does not represent a mapping.

text

The file content.

path

Identifier of the file’s origin, used in log messages.

saltext.github.utils.gh.grains_files.filter_content(data, include=None, exclude=None)

Apply a normalized (per validate()) include/exclude specification to a parsed file mapping and return the result.

data

The parsed file content.

include

Normalized include entries: fnmatch patterns against colon-delimited key paths (a match includes the whole subtree, preserving nesting) and (new_name, source) rename tuples (exact source path, value exposed as flat new_name key). None includes everything.

exclude

Fnmatch patterns pruning matching key paths at any depth after includes. Does not apply to renames.

saltext.github.utils.gh.grains_files.merge_grains(grains, custom)

Merge collected (per collect()) custom grains into a grains mapping and return it. The special _ namespace contributes its keys at the root level, other namespaces become a single key each. Keys already present – the builtin identity grains or earlier namespaces – are never overwritten (logged and skipped).

grains

The grains mapping to merge into (mutated).

custom

Mapping of namespace to grain data.

saltext.github.utils.gh.grains_files.collect(conn, repo_name, spec, *, owner=None)

Fetch, parse, merge and filter all namespaces of a normalized (per validate()) grains_files specification for one repository.

Returns a mapping of namespace to grain data; namespaces without any resulting data are omitted. Per-file and per-namespace problems are logged and skipped, never raised.

conn

GitHubConnection to use.

repo_name

Repository name.

spec

The normalized grains_files specification.

owner

Owner of the repository. Defaults to the connection’s owner.