Composition files

Composition files are YAML documents with layer configurations. They are used for generating new projects and recording how a current project was generated. The composition files used for generating new projects are usually minimal, compared to the .composition.yaml file cookie-composer writes in the project as a record of state.

For example, a basic composition file for generating new projects might look like:

Example composition

template: "https://github.com/coordt/cookiecomposer-templates"
directory: "cookiecutter-boilerplate"
merge_strategies:
  '*.json': "comprehensive"
  '*.yaml': "comprehensive"
  '*.yml': "comprehensive"
---
template: "https://github.com/coordt/cookiecomposer-templates"
directory: "cookiecutter-package"
merge_strategies:
  '*.json': "comprehensive"
  '*.yaml': "comprehensive"
  '*.yml': "comprehensive"
---
template: "https://github.com/coordt/cookiecomposer-templates"
directory: "cookiecutter-docs"
merge_strategies:
  '*.json': "comprehensive"
  '*.yaml': "comprehensive"
  '*.yml': "comprehensive"

When this is used to create a project:

An interactive console example

$ cookie-composer create https://raw.githubusercontent.com/coordt/cookiecomposer-templates/master/package-composition.yaml
project_name [python-boilerplate]: my-test-project
project_slug [my_test_project]:
friendly_name [My Test Project]:
project_short_description []:
version [0.1.0]:
author [Who am I?]:
email [whoami@existential-crisis.doom]:
github_user [whoami]:

The composition file saved in the new project (named my-test-project in this example) as .composition.yaml would look like:

A rendered composition

checkout: null
commit: 3391f60471939dd412e93e9853e3328e7a5a8c44
context:
  _copy_without_render: [.github/**/*.jinja]
  _dev_requirements: {bump2version: '>=1.0.1', generate-changelog: '>=0.7.6', git-fame: '>=1.12.2',
    pip-tools: ''}
  _prod_requirements: {environs: '>=9.3.5'}
  _test_requirements: {black: '>=19.10b0', coverage: '>=6.1.2', flake8: '>=4.0.1',
    pre-commit: '>=2.15.0', pytest: '>=6.0.0', pytest-cov: '>=3.0.0'}
  author: Who am I?
  email: whoami@existential-crisis.doom
  friendly_name: My Test Project
  github_user: whoami
  project_name: my-test-project
  project_short_description: ''
  project_slug: my_test_project
  version: 0.1.0
directory: cookiecutter-boilerplate
merge_strategies: {'*.json': comprehensive, '*.yaml': comprehensive, '*.yml': comprehensive}
no_input: false
overwrite: []
overwrite_exclude: []
password: null
skip_generation: []
skip_hooks: false
skip_if_file_exists: true
template: https://github.com/coordt/cookiecomposer-templates
---
checkout: null
commit: 3391f60471939dd412e93e9853e3328e7a5a8c44
context: {friendly_name: My Test Project, project_name: my-test-project, project_short_description: '',
  project_slug: my_test_project, version: 0.1.0}
directory: cookiecutter-package
merge_strategies: {'*.json': comprehensive, '*.yaml': comprehensive, '*.yml': comprehensive}
no_input: false
overwrite: []
overwrite_exclude: []
password: null
skip_generation: []
skip_hooks: false
skip_if_file_exists: true
template: https://github.com/coordt/cookiecomposer-templates
---
checkout: null
commit: 3391f60471939dd412e93e9853e3328e7a5a8c44
context:
  _copy_without_render: [docsrc/**/*.rst]
  _dev_requirements: {bump2version: '>=1.0.1', generate-changelog: '>=0.7.6', git-fame: '>=1.12.2',
    pip-tools: ''}
  _docs_requirements: {Sphinx: '>=4.3.0', furo: '', ghp-import: '', linkify-it-py: '',
    myst-parser: '', sphinx-autodoc-typehints: '', sphinx-click: '', sphinx-copybutton: ''}
  _prod_requirements: {environs: '>=9.3.5'}
  friendly_name: My Test Project
  github_user: whoami
  project_name: my-test-project
  project_slug: my_test_project
directory: cookiecutter-docs
merge_strategies: {'*.json': comprehensive, '*.yaml': comprehensive, '*.yml': comprehensive}
no_input: false
overwrite: []
overwrite_exclude: []
password: null
skip_generation: []
skip_hooks: false
skip_if_file_exists: true
template: https://github.com/coordt/cookiecomposer-templates

If you look closely you’ll see that .composition.yaml contains the contents of package-composition.yaml. Internally the .composition.yaml file is termed a “rendered composition” because it contains all the parameters used to render this specific project. This rendered composition is used when applying updates of the templates.

Template layers

Composition files are technically YAML streams consisting of one or more documents describing a layer configuration.