composition
Data models for configurations.
Classes¶
pydantic-model
¶
Bases: BaseModel
The settings for a composition.
Show JSON schema:
{
"$defs": {
"Location": {
"description": "The location of a file or directory.\n\nA location supports referencing the file or directory using:\n\n- relative path\n- absolute path\n- git URL\n- git URL plus revision/tag/branch plus path in the repo\n\nWhen `url` is specified, the `path` is relative to the root of the repository.\n\nAt least one of `path` or `url` must be specified.",
"properties": {
"path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The relative or absolute path to the location.",
"title": "Path"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The Git URL to the location.",
"title": "Url"
}
},
"title": "Location",
"type": "object"
},
"Overlay": {
"description": "An object describing how to overlay a pattern in a composition.",
"properties": {
"pattern_location": {
"anyOf": [
{
"type": "string"
},
{
"$ref": "#/$defs/Location"
}
],
"description": "The location of the pattern file for this overlay.",
"title": "Pattern Location"
},
"ask_questions": {
"default": true,
"description": "Ask the user this pattern's questions? When false, the defaults are used.",
"title": "Ask Questions",
"type": "boolean"
},
"defaults": {
"description": "Override one or more question's default values in this pattern. Values can be a template string.",
"title": "Defaults",
"type": "object"
},
"extra_context": {
"description": "Override one or more keys in this pattern's `extra_context`. Values can be a template string.",
"title": "Extra Context",
"type": "object"
},
"answer_map": {
"description": "This signifies that a previous overlay has already answered one or more of this pattern's questions. The key is this pattern's question name and the value is a template string that references or modifies a previous pattern's question name.",
"title": "Answer Map",
"type": "object"
},
"overwrite_files": {
"description": "A list of paths or glob patterns of files that may be overwritten. An empty list means do not overwrite any files.",
"items": {
"type": "string"
},
"title": "Overwrite Files",
"type": "array"
},
"exclude_files": {
"description": "A list of paths or glob patterns of files to exclude from the generation (overrides the pattern's configuration)",
"items": {
"type": "string"
},
"title": "Exclude Files",
"type": "array"
}
},
"required": [
"pattern_location"
],
"title": "Overlay",
"type": "object"
},
"Task": {
"description": "A task to run while rendering a composition.",
"properties": {
"command": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"type": "string"
},
"type": "array"
}
],
"description": "The command to run.",
"title": "Command"
},
"use_shell": {
"default": false,
"description": "Whether to run the command in a shell.\n\nIf `command` is a str, this is always `True`.",
"title": "Use Shell",
"type": "boolean"
},
"env": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Environment variables to set when running the command.\n\nEach environment variable value may be a template string rendered using the context so far.",
"title": "Env"
},
"when": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "A template string that will render as `True` if the task should run.",
"title": "When"
},
"context_variable_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The name of a context variable that will be set to the command's stdout. If not provided, the the output is not saved to the context.",
"title": "Context Variable Name"
}
},
"required": [
"command"
],
"title": "Task",
"type": "object"
}
},
"description": "The settings for a composition.",
"properties": {
"steps": {
"description": "A list of pattern overlays and tasks to compose.",
"items": {
"anyOf": [
{
"$ref": "#/$defs/Overlay"
},
{
"$ref": "#/$defs/Task"
}
]
},
"title": "Steps",
"type": "array"
},
"merge_keys": {
"additionalProperties": {
"enum": [
"overwrite",
"comprehensive"
],
"type": "string"
},
"description": "Merge the values of one or more keys in a specific way. This is useful for `yaml` or `json` values. Valid merge methods are `overwrite`, `nested-overwrite`, and `comprehensive`.",
"title": "Merge Keys",
"type": "object"
},
"extra_context": {
"description": "Override one or more keys in this pattern's `extra_context`. Values can be a template string.",
"title": "Extra Context",
"type": "object"
}
},
"title": "Composition",
"type": "object"
}
Fields:
-
steps(List[Overlay | Task]) -
merge_keys(Dict[str, MergeMethods]) -
extra_context(dict)
Attributes¶
pydantic-field
¶
extra_context: dict
Override one or more keys in this pattern’s extra_context. Values can be a template string.
pydantic-field
¶
merge_keys: Dict[str, MergeMethods]
Merge the values of one or more keys in a specific way. This is useful for yaml or json values. Valid merge methods are overwrite, nested-overwrite, and comprehensive.
Functions¶
cache_data() -> None
Makes sure all the patterns are cached and have their pattern objects loaded.
Accessing the pattern property on an overlay will lazily load the pattern.
classmethod
¶
from_location(
location: Union[str, Location]
) -> Composition
Convert the location to a pattern into a composition.
Functions¶
is_composition_data(data: dict) -> bool
Returns True if the data is for a composition, otherwise False.
read_composition_file(
path: Union[str, Path]
) -> Composition
Read, parse, and validate the contents of a composition file and patterns.
If the path is to a pattern file, it is added to a composition and returned.
| PARAMETER | DESCRIPTION |
|---|---|
path
|
The path to the composition or pattern file |
| RETURNS | DESCRIPTION |
|---|---|
Composition
|
A resolved and validated composition object. |