-d, --destination, -o, --output-dir
<function <lambda> at 0x7f7bd452af80><function <lambda> at 0x7f0e92634430>--accept-hooks-d, --destination
<function <lambda> at 0x7f7bd452ad40><function <lambda> at 0x7f0e926341f0>--helpCookie composer builds on the cookie cutter project to generate projects based on one or more cookiecutter templates.
"},{"location":"#goals","title":"Goals","text":"Cookie Cutter treats templates like sandwiches. There are templates for hamburgers, clubs, and any other kind of sandwich you can dream up. You might have options and defaults on a template, like Hold the mustard?[False]: or Mustard type [dijon]:, but those are decided by the template author.
If you look closely at the sandwiches (templates), there is usually many things in common. What if we treated the templates as compositions of other templates:
You now can manage several smaller and specialized templates that provide functionality. Each template\u2019s options will be specific to what that template needs.
Cookie Composer uses a composition file to describe the layers required, and even override a template\u2019s default answers.
template: bottom-bun\ncontext:\n toasting_level: light\n buttered: False\n---\ntemplate: burger\n---\ntemplate: cheese\ncontext:\n kind: swiss\n---\ntemplate: bacon\ncontext:\n cooking_level: crispy\n---\ntemplate: ketchup\n---\ntemplate: mustard\ncontext:\n type: yellow\n---\ntemplate: top-bun\ncontext:\n toasting_level: light\n buttered: False\nWe have created a repo of highly composable templates as examples or reference. However, Cookie Composer is designed to handle any Cookie Cutter template.
"},{"location":"#purpose","title":"Purpose","text":"Compare the full difference.
"},{"location":"changelog/#fixes","title":"Fixes","text":"Fixed parseurl with windows path. 9d14ae4
Was making the drive letter the scheme. - Fixed test PyPI upload. 7c59fc2
Fixed cookiecutter update incompatibilities. 9132c3c
Bump aiohttp from 3.9.2 to 3.9.4 in /requirements. 9eb6f0c
Bumps aiohttp from 3.9.2 to 3.9.4. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: aiohttp dependency-type: direct:production
signed-off-by: dependabot[bot] support@github.com
Bump idna from 3.4 to 3.7 in /requirements. 61297b5
Bumps idna from 3.4 to 3.7. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: idna dependency-type: direct:production
signed-off-by: dependabot[bot] support@github.com
Bump tqdm from 4.66.1 to 4.66.3 in /requirements. 94421a6
Bumps tqdm from 4.66.1 to 4.66.3. - Release notes - Commits
updated-dependencies: - dependency-name: tqdm dependency-type: direct:development
signed-off-by: dependabot[bot] support@github.com
Bump orjson from 3.9.9 to 3.9.15 in /requirements. ff8a8d6
Bumps orjson from 3.9.9 to 3.9.15. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: orjson dependency-type: direct:production
signed-off-by: dependabot[bot] support@github.com
[pre-commit.ci] pre-commit autoupdate. 8a67e75
updates: - github.com/astral-sh/ruff-pre-commit: v0.3.5 \u2192 v0.4.2
[pre-commit.ci] pre-commit autoupdate. e610733
updates: - github.com/astral-sh/ruff-pre-commit: v0.2.0 \u2192 v0.3.5
Compare the full difference.
"},{"location":"changelog/#fixes_1","title":"Fixes","text":"Fixed git worktree issue. e27636c
Fixed issue with determining rendered layer names. 06bad39
Added get_template_rendered_name to proactively determine the name of the rendered template. - Fixed resiliency issue with git template repos. a9bb80d
Provided better error checking for bad cached repos. - Fixed issue with relative paths in local files. 7f1b354
You can pass a local_path to use to resolve relative local paths for I/O and template determination. - Fixed data merge organization. 4bba0f4
[pre-commit.ci] pre-commit autoupdate. 86a2c04
updates: - github.com/astral-sh/ruff-pre-commit: v0.1.3 \u2192 v0.2.0
Bump gitpython from 3.1.40 to 3.1.41 in /requirements. 119c786
Bumps gitpython from 3.1.40 to 3.1.41. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: gitpython dependency-type: direct:production
signed-off-by: dependabot[bot] support@github.com
Bump jinja2 from 3.1.2 to 3.1.3 in /requirements. 100a239
Bumps jinja2 from 3.1.2 to 3.1.3. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: jinja2 dependency-type: direct:production
signed-off-by: dependabot[bot] support@github.com
Bump aiohttp from 3.8.6 to 3.9.2 in /requirements. 4b2a9df
Bumps aiohttp from 3.8.6 to 3.9.2. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: aiohttp dependency-type: direct:production
signed-off-by: dependabot[bot] support@github.com
get_context_for_layer from utils.py to composition.py. 6641a91get_template_name tests. 1c0c054[pre-commit.ci] pre-commit autoupdate. db151ef
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.287 \u2192 v0.0.290
[pre-commit.ci] pre-commit autoupdate. 7335d97
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.287 \u2192 v0.0.292
Bump urllib3 from 2.0.4 to 2.0.7 in /requirements. 6f5dd07
Bumps urllib3 from 2.0.4 to 2.0.7. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: urllib3 dependency-type: direct:production
signed-off-by: dependabot[bot] support@github.com
[pre-commit.ci] pre-commit autoupdate. 94b1833
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.287 \u2192 v0.1.3
[pre-commit.ci] pre-commit autoupdate. bc33fbd
updates: - https://github.com/charliermarsh/ruff-pre-commit \u2192 https://github.com/astral-sh/ruff-pre-commit
zipfile_repo.unzip to cache_source. 60a2393io module. 3c64a3eRefactored layers. e8af7d5
Template with LayerConfig - template attribute is now a Template instance - removed directory, checkout, password, and commit - renamed context to initial_context to distiguish it from the Template\u2019s contextRenderedLayer to use templates - renamed new_context to rendered_context to better describe it. - renamed latest_commit to rendered_commit for better clarity - added latest_commit convenience functionrender_layer using the new template functionsIt is now part of the template repo - Updated requirements to use Pydantic 2. b24a158
Compare the full difference.
"},{"location":"changelog/#fixes_2","title":"Fixes","text":"Added -o and --output-dir as an alias. 04f063d
It is now an alias for -d and --destination
Revert \u201c[pre-commit.ci] auto fixes from pre-commit.com hooks\u201d. 42d8704
This reverts commit 52772f1352d6130b2d6189bf632b26fb9732c13f. - [pre-commit.ci] auto fixes from pre-commit.com hooks. 52772f1
for more information, see https://pre-commit.ci - Migrated from setup.cfg to pyproject.toml. b3a39f0
Bump aiohttp from 3.8.3 to 3.8.5 in /requirements. 0392ef7
Bumps aiohttp from 3.8.3 to 3.8.5. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: aiohttp dependency-type: direct:production
signed-off-by: dependabot[bot] support@github.com
[pre-commit.ci] pre-commit autoupdate. 83d1217
updates: - github.com/psf/black: 23.3.0 \u2192 23.7.0
[pre-commit.ci] pre-commit autoupdate. c58fe42
updates: - github.com/psf/black: 23.3.0 \u2192 23.7.0
Compare the full difference.
"},{"location":"changelog/#new_2","title":"New","text":"Compare the full difference.
"},{"location":"changelog/#fixes_3","title":"Fixes","text":"Compare the full difference.
"},{"location":"changelog/#fixes_4","title":"Fixes","text":"Bump markdown-it-py from 2.1.0 to 2.2.0 in /requirements. 65a4863
Bumps markdown-it-py from 2.1.0 to 2.2.0. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: markdown-it-py dependency-type: indirect
signed-off-by: dependabot[bot] support@github.com
[pre-commit.ci] pre-commit autoupdate. 21eca93
updates: - github.com/psf/black: 23.1.0 \u2192 23.3.0
Compare the full difference.
"},{"location":"changelog/#new_3","title":"New","text":"Added relative directory support for compositions. 02fa5b8
., .., and relative paths (non-/ prefixed) are resolved with urllib.parse.urljoinCompare the full difference.
"},{"location":"changelog/#new_4","title":"New","text":"Modified CLI options and arguments. 02a4bf3
output_dir argument was moved to the --destination option.CONTEXT_PARAMS argument for initial contextCompare the full difference.
"},{"location":"changelog/#new_5","title":"New","text":"--version option. 4b1b9e1Compare the full difference.
"},{"location":"changelog/#fixes_5","title":"Fixes","text":"[pre-commit.ci] pre-commit autoupdate. 1f5320a
updates: - github.com/pycqa/pydocstyle: 6.1.1 \u2192 6.2.3
Compare the full difference.
"},{"location":"changelog/#fixes_6","title":"Fixes","text":"Bump wheel from 0.37.1 to 0.38.1 in /requirements. cab9b8e
Bumps wheel from 0.37.1 to 0.38.1. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: wheel dependency-type: indirect
signed-off-by: dependabot[bot] support@github.com
[pre-commit.ci] pre-commit autoupdate. 45e8596
updates: - github.com/PyCQA/isort: v5.11.3 \u2192 5.11.4
[pre-commit.ci] pre-commit autoupdate. 550e0cb
updates: - github.com/PyCQA/isort: 5.10.1 \u2192 v5.11.3
Compare the full difference.
"},{"location":"changelog/#fixes_7","title":"Fixes","text":"[pre-commit.ci] pre-commit autoupdate. 5b21a40
updates: - github.com/psf/black: 22.10.0 \u2192 22.12.0
[pre-commit.ci] pre-commit autoupdate. 0f5c7a5
updates: - github.com/pre-commit/pre-commit-hooks: v4.3.0 \u2192 v4.4.0
Changed JSON library to orjson. c857a2f
Compare the full difference.
"},{"location":"changelog/#fixes_8","title":"Fixes","text":"Compare the full difference.
"},{"location":"changelog/#new_7","title":"New","text":"[pre-commit.ci] pre-commit autoupdate. a31eeef
updates: - github.com/psf/black: 22.8.0 \u2192 22.10.0
Compare the full difference.
"},{"location":"changelog/#fixes_9","title":"Fixes","text":"git diff and git apply. d4bc14fCompare the full difference.
"},{"location":"changelog/#new_9","title":"New","text":"Added the update subcommand. 6696589
[pre-commit.ci] auto fixes from pre-commit.com hooks. e5425d5
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. dbfde0a
updates: - github.com/psf/black: 22.6.0 \u2192 22.8.0
Compare the full difference.
"},{"location":"changelog/#new_10","title":"New","text":"[pre-commit.ci] pre-commit autoupdate. e516a18
updates: - github.com/PyCQA/flake8: 4.0.1 \u2192 5.0.4
[pre-commit.ci] pre-commit autoupdate. 3e6f695
updates: - github.com/psf/black: 22.3.0 \u2192 22.6.0
Compare the full difference.
"},{"location":"changelog/#fixes_10","title":"Fixes","text":"Compare the full difference.
"},{"location":"changelog/#new_11","title":"New","text":"Compare the full difference.
"},{"location":"changelog/#fixes_11","title":"Fixes","text":"Compare the full difference.
"},{"location":"changelog/#fixes_12","title":"Fixes","text":"Fixed add command requiring destination. 15cbd16
The destination of the add command is now optional and defaults to the current working directory. - Fixed error not writing commit to composition file. 8fd7bbe
Fixed a bug when two templates have _copy_without_render. 9e89347
_copy_without_render is template-specific and attempting to override it raises an error in cookiecutter. Now that key is deleted for the default context and full context when generating each layer. - Fixed configurations. df365df
Added git commands. 291b9aa
This allows for detection of multiple rendered directories, and proper writing of the composition file. - Added release tooling. d0646d3
[pre-commit.ci] auto fixes from pre-commit.com hooks. 2dae846
for more information, see https://pre-commit.ci - Excluding test fixtures from requirement fixing. 40293a9
[pre-commit.ci] auto fixes from pre-commit.com hooks. b774ad1
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. 5098fde
updates: - github.com/pre-commit/pre-commit-hooks: v4.2.0 \u2192 v4.3.0
[pre-commit.ci] auto fixes from pre-commit.com hooks. 63f2d7d
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. 8f6d661
updates: - https://github.com/timothycrosley/isort \u2192 https://github.com/PyCQA/isort
Changed dependency management. 4cf52ba
Uses pip-tools to compile and maintain dependency information. - Updated tests. 7c81df5
Compare the full difference.
"},{"location":"changelog/#other_12","title":"Other","text":"Compare the full difference.
"},{"location":"changelog/#fixes_13","title":"Fixes","text":"Fixed git worktree issue. e27636c
Fixed issue with determining rendered layer names. 06bad39
Added get_template_rendered_name to proactively determine the name of the rendered template. - Fixed resiliency issue with git template repos. a9bb80d
Provided better error checking for bad cached repos. - Fixed issue with relative paths in local files. 7f1b354
You can pass a local_path to use to resolve relative local paths for I/O and template determination. - Fixed data merge organization. 4bba0f4
get_context_for_layer from utils.py to composition.py. 6641a91get_template_name tests. 1c0c054[pre-commit.ci] pre-commit autoupdate. db151ef
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.287 \u2192 v0.0.290
[pre-commit.ci] pre-commit autoupdate. 7335d97
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.287 \u2192 v0.0.292
Bump urllib3 from 2.0.4 to 2.0.7 in /requirements. 6f5dd07
Bumps urllib3 from 2.0.4 to 2.0.7. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: urllib3 dependency-type: direct:production
signed-off-by: dependabot[bot] support@github.com
[pre-commit.ci] pre-commit autoupdate. 94b1833
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.287 \u2192 v0.1.3
[pre-commit.ci] pre-commit autoupdate. bc33fbd
updates: - https://github.com/charliermarsh/ruff-pre-commit \u2192 https://github.com/astral-sh/ruff-pre-commit
zipfile_repo.unzip to cache_source. 60a2393io module. 3c64a3eRefactored layers. e8af7d5
Template with LayerConfig - template attribute is now a Template instance - removed directory, checkout, password, and commit - renamed context to initial_context to distiguish it from the Template\u2019s contextRenderedLayer to use templates - renamed new_context to rendered_context to better describe it. - renamed latest_commit to rendered_commit for better clarity - added latest_commit convenience functionrender_layer using the new template functionsIt is now part of the template repo - Updated requirements to use Pydantic 2. b24a158
Compare the full difference.
"},{"location":"changelog/#fixes_14","title":"Fixes","text":"Added -o and --output-dir as an alias. 04f063d
It is now an alias for -d and --destination
Revert \u201c[pre-commit.ci] auto fixes from pre-commit.com hooks\u201d. 42d8704
This reverts commit 52772f1352d6130b2d6189bf632b26fb9732c13f. - [pre-commit.ci] auto fixes from pre-commit.com hooks. 52772f1
for more information, see https://pre-commit.ci - Migrated from setup.cfg to pyproject.toml. b3a39f0
Bump aiohttp from 3.8.3 to 3.8.5 in /requirements. 0392ef7
Bumps aiohttp from 3.8.3 to 3.8.5. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: aiohttp dependency-type: direct:production
signed-off-by: dependabot[bot] support@github.com
[pre-commit.ci] pre-commit autoupdate. 83d1217
updates: - github.com/psf/black: 23.3.0 \u2192 23.7.0
[pre-commit.ci] pre-commit autoupdate. c58fe42
updates: - github.com/psf/black: 23.3.0 \u2192 23.7.0
Compare the full difference.
"},{"location":"changelog/#new_15","title":"New","text":"Compare the full difference.
"},{"location":"changelog/#fixes_15","title":"Fixes","text":"Compare the full difference.
"},{"location":"changelog/#fixes_16","title":"Fixes","text":"Bump markdown-it-py from 2.1.0 to 2.2.0 in /requirements. 65a4863
Bumps markdown-it-py from 2.1.0 to 2.2.0. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: markdown-it-py dependency-type: indirect
signed-off-by: dependabot[bot] support@github.com
[pre-commit.ci] pre-commit autoupdate. 21eca93
updates: - github.com/psf/black: 23.1.0 \u2192 23.3.0
Compare the full difference.
"},{"location":"changelog/#new_16","title":"New","text":"Added relative directory support for compositions. 02fa5b8
., .., and relative paths (non-/ prefixed) are resolved with urllib.parse.urljoinCompare the full difference.
"},{"location":"changelog/#new_17","title":"New","text":"Modified CLI options and arguments. 02a4bf3
output_dir argument was moved to the --destination option.CONTEXT_PARAMS argument for initial contextCompare the full difference.
"},{"location":"changelog/#new_18","title":"New","text":"--version option. 4b1b9e1Compare the full difference.
"},{"location":"changelog/#fixes_17","title":"Fixes","text":"[pre-commit.ci] pre-commit autoupdate. 1f5320a
updates: - github.com/pycqa/pydocstyle: 6.1.1 \u2192 6.2.3
Compare the full difference.
"},{"location":"changelog/#fixes_18","title":"Fixes","text":"Bump wheel from 0.37.1 to 0.38.1 in /requirements. cab9b8e
Bumps wheel from 0.37.1 to 0.38.1. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: wheel dependency-type: indirect
signed-off-by: dependabot[bot] support@github.com
[pre-commit.ci] pre-commit autoupdate. 45e8596
updates: - github.com/PyCQA/isort: v5.11.3 \u2192 5.11.4
[pre-commit.ci] pre-commit autoupdate. 550e0cb
updates: - github.com/PyCQA/isort: 5.10.1 \u2192 v5.11.3
Compare the full difference.
"},{"location":"changelog/#fixes_19","title":"Fixes","text":"[pre-commit.ci] pre-commit autoupdate. 5b21a40
updates: - github.com/psf/black: 22.10.0 \u2192 22.12.0
[pre-commit.ci] pre-commit autoupdate. 0f5c7a5
updates: - github.com/pre-commit/pre-commit-hooks: v4.3.0 \u2192 v4.4.0
Changed JSON library to orjson. c857a2f
Compare the full difference.
"},{"location":"changelog/#fixes_20","title":"Fixes","text":"Compare the full difference.
"},{"location":"changelog/#new_20","title":"New","text":"[pre-commit.ci] pre-commit autoupdate. a31eeef
updates: - github.com/psf/black: 22.8.0 \u2192 22.10.0
Compare the full difference.
"},{"location":"changelog/#fixes_21","title":"Fixes","text":"git diff and git apply. d4bc14fCompare the full difference.
"},{"location":"changelog/#new_22","title":"New","text":"Added the update subcommand. 6696589
[pre-commit.ci] auto fixes from pre-commit.com hooks. e5425d5
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. dbfde0a
updates: - github.com/psf/black: 22.6.0 \u2192 22.8.0
Compare the full difference.
"},{"location":"changelog/#new_23","title":"New","text":"[pre-commit.ci] pre-commit autoupdate. e516a18
updates: - github.com/PyCQA/flake8: 4.0.1 \u2192 5.0.4
[pre-commit.ci] pre-commit autoupdate. 3e6f695
updates: - github.com/psf/black: 22.3.0 \u2192 22.6.0
Compare the full difference.
"},{"location":"changelog/#fixes_22","title":"Fixes","text":"Compare the full difference.
"},{"location":"changelog/#new_24","title":"New","text":"Compare the full difference.
"},{"location":"changelog/#fixes_23","title":"Fixes","text":"Compare the full difference.
"},{"location":"changelog/#fixes_24","title":"Fixes","text":"Fixed add command requiring destination. 15cbd16
The destination of the add command is now optional and defaults to the current working directory. - Fixed error not writing commit to composition file. 8fd7bbe
Fixed a bug when two templates have _copy_without_render. 9e89347
_copy_without_render is template-specific and attempting to override it raises an error in cookiecutter. Now that key is deleted for the default context and full context when generating each layer. - Fixed configurations. df365df
Added git commands. 291b9aa
This allows for detection of multiple rendered directories, and proper writing of the composition file. - Added release tooling. d0646d3
[pre-commit.ci] auto fixes from pre-commit.com hooks. 2dae846
for more information, see https://pre-commit.ci - Excluding test fixtures from requirement fixing. 40293a9
[pre-commit.ci] auto fixes from pre-commit.com hooks. b774ad1
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. 5098fde
updates: - github.com/pre-commit/pre-commit-hooks: v4.2.0 \u2192 v4.3.0
[pre-commit.ci] auto fixes from pre-commit.com hooks. 63f2d7d
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. 8f6d661
updates: - https://github.com/timothycrosley/isort \u2192 https://github.com/PyCQA/isort
Changed dependency management. 4cf52ba
Uses pip-tools to compile and maintain dependency information. - Updated tests. 7c81df5
There are several ways to create your isolated environment. This is the default method.
Run the following in a terminal:
# Clone the repository\ngit clone https://github.com/coordt/cookie-composer.git\n\n# Enter the repository\ncd cookie-composer\n\n# Create then activate a virtual environment\npython -m venv venv\nsource venv/bin/activate\n\n# Install the development requirements\npython -m pip install -r requirements/dev.txt\nOnce setup, you should be able to run tests:
pytest\nPre-commit hooks are scripts that run every time you make a commit. If any of the scripts fail, it stops the commit. You can see a listing of the checks in the .pre-commit-config.yaml file.
pre-commit install\nThis is the recommended method for installing cookie composer because it works on all platforms and should require minimal effort.\npipx is a tool to help you install and run end-user applications written in Python. It\u2019s roughly similar to macOS\u2019s brew, JavaScript\u2019s npx, and Linux\u2019s apt. pipx installs the application in an isolated Python environment yet still makes the app available in your shell.
The full instructions for installing pipx are on its website.
With pipx installed, install cookie-composer by running:
$ pipx install cookie-composer\nThe cookie-composer command is available in your shell as any other command.
Installing cookie composer into a Python virtual environment, also known as a virtualenv or venv, means the command is only available while that environment is active.\nThe instructions assume you already have Python installed.\nThe full documentation on creating virtual environments gives a greater set of instructions. It will be something like running:
$ python3 -m venv /path/to/new/virtual/environment\nThe method of activating the environment depends on the shell and are listed in the documentation. For bash or zsh it is:
$ source </path/to/new/virtual/environment>/bin/activate\nOnce the virtual environment is activate, use pip to install cookie-composer:
$ python3 -m pip install cookie-composer\nCookie composer can integrate with some third-party services in order to access private repositories.
Note
Currently only GitHub is supported.
"},{"location":"how-to/access-private-templates/#github","title":"GitHub","text":"At your terminal, enter cookie-composer auth login:
$ cookie-composer auth login\nFirst copy your one-time code: A25E-0A58\nThen visit https://github.com/login/device in your browser, and paste the code when prompted.\nPress Enter to open github.com in your browser...\nCopy the one-time code (A25E-0A58 in this example), and press Enter or Return to open your browser to the correct page.
You will arrive at a page similar to this:
Paste the code (or enter each character individually) and press the continue button.
You will see an authorization page, similar to:
Press the \u201cAuthorize callowayproject\u201d button to allow cookie-composer read-only access to your repositories.
Then you will see:
And you can close the browser window.
Your terminal will now look like:
$ cookie-composer auth login\nFirst copy your one-time code: A25E-0A58\nThen visit https://github.com/login/device in your browser, and paste the code when prompted.\nPress Enter to open github.com in your browser...\nWaiting for authorization.............Authenticated to GitHub\nNow when you provide any GitHub template link, Cookie Composer is able to access them as you with read-only access.
"},{"location":"reference/cli/","title":"cookie-composer","text":"Render templates using composition.
Usage:
cookie-composer [OPTIONS] COMMAND [ARGS]...\nOptions:
Name Type Description Default--version boolean Show the version and exit. False --help boolean Show this message and exit. False Subcommands
Add the template or configuration PATH_OR_URL to an existing project.
Usage:
cookie-composer add [OPTIONS] PATH_OR_URL [CONTEXT_PARAMS]...\nOptions:
Name Type Description Default--verbosity, -v text Either CRITICAL, ERROR, WARNING, INFO or DEBUG INFO --no-input boolean Do not prompt for parameters and only use cookiecutter.json file content. Defaults to deleting any cached resources and redownloading them. False -c, --checkout text branch, tag or commit to checkout after git clone None --directory text Directory within repo that holds cookiecutter.json file for advanced repositories with multi templates in it None -f, --overwrite-if-exists boolean Overwrite the contents of the output directory if it already exists False -s, --skip-if-file-exists boolean Skip the files in the corresponding directories if they already exist False --default-config boolean Do not load a config file. Use the defaults instead False -d, --destination directory The directory to add the templates to. Defaults to the current working directory. <function <lambda> at 0x7f7bd452b0a0> --accept-hooks choice (yes | ask | no | first | last | all | none) Accept pre/host hooks all --help boolean Show this message and exit. False"},{"location":"reference/cli/#cookie-composer-auth","title":"cookie-composer auth","text":"Authenticate cookie-composer to a service.
Usage:
cookie-composer auth [OPTIONS] COMMAND [ARGS]...\nOptions:
Name Type Description Default--help boolean Show this message and exit. False Subcommands
Authenticate to a service.
Usage:
cookie-composer auth login [OPTIONS]\nOptions:
Name Type Description Default-p, --git-protocol choice (https | ssh) The protocol to use for git operations https -h, --service text The host name of the service to authenticate with github.com -s, --scopes text Additional authentication scopes to request None --with-token filename Read token from standard input None --help boolean Show this message and exit. False"},{"location":"reference/cli/#cookie-composer-auth-token","title":"cookie-composer auth token","text":"Print the auth token cookie-composer is configured to use.
Usage:
cookie-composer auth token [OPTIONS]\nOptions:
Name Type Description Default-h, --service text The host name of the service to authenticate with github.com --help boolean Show this message and exit. False"},{"location":"reference/cli/#cookie-composer-create","title":"cookie-composer create","text":"Create a project from the template or configuration PATH_OR_URL in using optional [CONTEXT_PARAMS].
Usage:
cookie-composer create [OPTIONS] PATH_OR_URL [CONTEXT_PARAMS]...\nOptions:
Name Type Description Default--verbosity, -v text Either CRITICAL, ERROR, WARNING, INFO or DEBUG INFO --no-input boolean Do not prompt for parameters and only use cookiecutter.json file content. Defaults to deleting any cached resources and redownloading them. False -c, --checkout text branch, tag or commit to checkout after git clone None --directory text Directory within repo that holds cookiecutter.json file for advanced repositories with multi templates in it None -f, --overwrite-if-exists boolean Overwrite the contents of the output directory if it already exists False -s, --skip-if-file-exists boolean Skip the files in the corresponding directories if they already exist False --default-config boolean Do not load a config file. Use the defaults instead False -d, --destination, -o, --output-dir directory The directory to render the templates to. Defaults to the current working directory. <function <lambda> at 0x7f7bd452af80> --accept-hooks choice (yes | ask | no | first | last | all | none) Accept pre/host hooks all --help boolean Show this message and exit. False"},{"location":"reference/cli/#cookie-composer-link","title":"cookie-composer link","text":"Link an existing git repo to the template or composition PATH_OR_URL using optional [CONTEXT_PARAMS].
Usage:
cookie-composer link [OPTIONS] PATH_OR_URL [CONTEXT_PARAMS]...\nOptions:
Name Type Description Default--no-input boolean Do not prompt for parameters and only use cookiecutter.json file content. Defaults to deleting any cached resources and redownloading them. False -c, --checkout text branch, tag or commit to checkout after git clone None --directory text Directory within repo that holds cookiecutter.json file for advanced repositories with multi templates in it None -f, --overwrite-if-exists boolean Overwrite the contents of the output directory if it already exists False -s, --skip-if-file-exists boolean Skip the files in the corresponding directories if they already exist False --default-config boolean Do not load a config file. Use the defaults instead False -d, --destination directory The directory to link the template to. Defaults to the current working directory. <function <lambda> at 0x7f7bd452b2e0> --help boolean Show this message and exit. False"},{"location":"reference/cli/#cookie-composer-update","title":"cookie-composer update","text":"Update the project to the latest version of each template.
Usage:
cookie-composer update [OPTIONS] [CONTEXT_PARAMS]...\nOptions:
Name Type Description Default--no-input boolean Do not prompt for parameters and only use cookiecutter.json file content. Defaults to deleting any cached resources and re-downloading them. False -d, --destination directory The directory to update. Defaults to the current working directory. <function <lambda> at 0x7f7bd452ad40> --help boolean Show this message and exit. False"},{"location":"reference/api/SUMMARY/","title":"SUMMARY","text":"OAuth2 authentication to access protected resources.
"},{"location":"reference/api/cookie_composer/authentication/#cookie_composer.authentication-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/authentication/#cookie_composer.authentication.add_auth_to_url","title":"add_auth_to_url","text":"add_auth_to_url(url: str) -> str\nAdd authentication information to a URL.
Parameters:
url The URL to add authentication information to.
TYPE: str
Returns:
str The URL with authentication information added, or the original URL if no token is cached
"},{"location":"reference/api/cookie_composer/authentication/#cookie_composer.authentication.get_cached_token","title":"get_cached_token","text":"get_cached_token(account_name: str) -> Optional[str]\nReturn the cached token for the account.
"},{"location":"reference/api/cookie_composer/authentication/#cookie_composer.authentication.get_hosts_file","title":"get_hosts_file","text":"get_hosts_file() -> Path\nReturn the path to the hosts file.
"},{"location":"reference/api/cookie_composer/authentication/#cookie_composer.authentication.github_auth_device","title":"github_auth_device","text":"github_auth_device(n_polls: int = 9999) -> Optional[str]\nAuthenticate with GitHub, polling up to n_polls times to wait for completion.
login_to_svc(\n service: Optional[str] = None,\n protocol: Optional[str] = None,\n scopes: Optional[str] = None,\n token: Optional[str] = None,\n) -> str\nLog in and cache token.
Parameters:
service The name of the service to authenticate with
TYPE: Optional[str]
DEFAULT: None
protocol The protocol to use for git operations
TYPE: Optional[str]
DEFAULT: None
scopes Additional authentication scopes to request
TYPE: Optional[str]
DEFAULT: None
token A specific token to use instead of logging in
TYPE: Optional[str]
DEFAULT: None
Returns:
str The token for the service
"},{"location":"reference/api/cookie_composer/cc_overrides/","title":"This overrides the default cookie cutter environment.
"},{"location":"reference/api/cookie_composer/cc_overrides/#cookie_composer.cc_overrides-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/cc_overrides/#cookie_composer.cc_overrides.CustomStrictEnvironment","title":"CustomStrictEnvironment","text":"CustomStrictEnvironment(**kwargs)\n Bases: StrictEnvironment
Create strict Jinja2 environment.
Jinja2 environment will raise error on undefined variable in template-rendering context.
Does not expect all the context to be under the cookiecutter key.
JsonifyContextExtension(environment: Environment)\n Bases: Extension
Jinja2 extension to convert a Python object to JSON.
"},{"location":"reference/api/cookie_composer/cc_overrides/#cookie_composer.cc_overrides-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/cc_overrides/#cookie_composer.cc_overrides.jsonify_context","title":"jsonify_context","text":"jsonify_context(value: Any) -> MutableMapping\nConvert a Context to a dict.
prompt_for_config(\n prompts: dict,\n aggregated_context: Context,\n layer_context: Optional[\n MutableMapping[str, Any]\n ] = None,\n no_input: bool = False,\n) -> MutableMapping[str, Any]\nPrompt user to enter a new config using an existing config as a basis.
Will not prompt for configurations already in the existing configuration.
Prompts can refer to items in the existing config.
Parameters:
prompts A dictionary of configuration prompts and default values
TYPE: dict
aggregated_context An existing configuration to use as a basis
TYPE: Context
layer_context A dictionary of defaults defined in the layer
TYPE: Optional[MutableMapping[str, Any]]
DEFAULT: None
no_input If True Don\u2019t prompt the user at command line for manual configuration
TYPE: bool
DEFAULT: False
Returns:
MutableMapping[str, Any] A new configuration context
"},{"location":"reference/api/cookie_composer/cc_overrides/#cookie_composer.cc_overrides.update_extensions","title":"update_extensions","text":"update_extensions(\n existing_config: MutableMapping[str, Any],\n prompts: MutableMapping[str, Any],\n) -> List[str]\nMerge extensions from prompts into existing config.
"},{"location":"reference/api/cookie_composer/cli/","title":"Command line setup.
"},{"location":"reference/api/cookie_composer/cli/#cookie_composer.cli-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/cli/#cookie_composer.cli-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/cli/#cookie_composer.cli.add","title":"add","text":"add(\n no_input: bool,\n checkout: str,\n directory: str,\n overwrite_if_exists: bool,\n skip_if_file_exists: bool,\n default_config: bool,\n destination: Path,\n accept_hooks: str,\n path_or_url: str,\n context_params: Optional[\n MutableMapping[str, Any]\n ] = None,\n) -> None\nAdd the template or configuration PATH_OR_URL to an existing project.
"},{"location":"reference/api/cookie_composer/cli/#cookie_composer.cli.cli","title":"cli","text":"cli() -> None\nRender templates using composition.
"},{"location":"reference/api/cookie_composer/cli/#cookie_composer.cli.create","title":"create","text":"create(\n no_input: bool,\n checkout: str,\n directory: str,\n overwrite_if_exists: bool,\n skip_if_file_exists: bool,\n default_config: bool,\n destination: Path,\n accept_hooks: str,\n path_or_url: str,\n context_params: Optional[\n MutableMapping[str, Any]\n ] = None,\n) -> None\nCreate a project from the template or configuration PATH_OR_URL in using optional [CONTEXT_PARAMS].
"},{"location":"reference/api/cookie_composer/cli/#cookie_composer.cli.link","title":"link","text":"link(\n no_input: bool,\n checkout: str,\n directory: str,\n overwrite_if_exists: bool,\n skip_if_file_exists: bool,\n default_config: bool,\n destination: Optional[Path],\n path_or_url: str,\n context_params: Optional[\n MutableMapping[str, Any]\n ] = None,\n) -> None\nLink an existing git repo to the template or composition PATH_OR_URL using optional [CONTEXT_PARAMS].
"},{"location":"reference/api/cookie_composer/cli/#cookie_composer.cli.update","title":"update","text":"update(\n no_input: bool,\n destination: Path,\n context_params: Optional[OrderedDict] = None,\n) -> None\nUpdate the project to the latest version of each template.
"},{"location":"reference/api/cookie_composer/cli/#cookie_composer.cli.validate_context_params","title":"validate_context_params","text":"validate_context_params(\n ctx: Any, param: Any, value: list\n) -> Optional[OrderedDict]\nValidate context parameters.
Convert a tuple to a dict
e.g.: ('program_name=foobar', 'startsecs=66') -> {'program_name': 'foobar', 'startsecs': '66'}
Parameters:
ctx Click context (unused)
TYPE: Any
param Click parameter (unused)
TYPE: Any
value Click parameter value
TYPE: list
Returns:
Optional[OrderedDict] An ordered dict of the parameter values or None if no parameters.
Raises:
BadParameter If the parameters are not key=value.
Project configuration and options.
"},{"location":"reference/api/cookie_composer/composition/#cookie_composer.composition-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/composition/#cookie_composer.composition.Composition","title":"Composition","text":" Bases: BaseModel
Composition of templates for a project.
"},{"location":"reference/api/cookie_composer/composition/#cookie_composer.composition.RenderedComposition","title":"RenderedComposition","text":" Bases: BaseModel
A rendered composition of templates for a project.
"},{"location":"reference/api/cookie_composer/composition/#cookie_composer.composition.RenderedComposition-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/composition/#cookie_composer.composition.RenderedComposition.layer_names","title":"layer_namesproperty","text":"layer_names: List[str]\nReturn a list of the names of all the layers.
"},{"location":"reference/api/cookie_composer/composition/#cookie_composer.composition.RenderedComposition.layers","title":"layersinstance-attribute","text":"layers: List[RenderedLayer]\nRendered layers.
"},{"location":"reference/api/cookie_composer/composition/#cookie_composer.composition.RenderedComposition.render_dir","title":"render_dirinstance-attribute","text":"render_dir: DirectoryPath\nThe directory in which the layers were rendered.
The render_dir + rendered_name is the location of the project.
instance-attribute","text":"rendered_name: str\nThe name of the rendered project.
"},{"location":"reference/api/cookie_composer/composition/#cookie_composer.composition-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/composition/#cookie_composer.composition.get_context_for_layer","title":"get_context_for_layer","text":"get_context_for_layer(\n composition: RenderedComposition,\n index: Optional[int] = None,\n) -> dict\nMerge the contexts for all layers up to index.
An index of None does all the layers.
Parameters:
composition The rendered composition
TYPE: RenderedComposition
index Merge the contexts of the layers up to this 0-based index. None to do all layers.
TYPE: Optional[int]
DEFAULT: None
Returns:
dict The comprehensively merged context
"},{"location":"reference/api/cookie_composer/data_merge/","title":"Tools for merging data.
"},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge.COMPREHENSIVE","title":"COMPREHENSIVEmodule-attribute","text":"COMPREHENSIVE = 'comprehensive'\nComprehensively merge the two data structures.
module-attribute","text":"DO_NOT_MERGE = 'do-not-merge'\nDo not merge the data, use the file path to determine what to do.
"},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge.NESTED_OVERWRITE","title":"NESTED_OVERWRITEmodule-attribute","text":"NESTED_OVERWRITE = 'nested-overwrite'\nMerge deeply nested structures and overwrite at the lowest level; A deep dict.update().
module-attribute","text":"OVERWRITE = 'overwrite'\nOverwrite at the top level like dict.update().
Bases: ChainMap
Provides merging and convenience functions for managing contexts.
"},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge.Context-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge.Context.is_empty","title":"is_emptyproperty","text":"is_empty: bool\nThe context has only one mapping and it is empty.
"},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge.Context-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge.Context.flatten","title":"flatten","text":"flatten() -> MutableMapping\nComprehensively merge all the maps into a single mapping.
"},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge.comprehensive_merge","title":"comprehensive_merge","text":"comprehensive_merge(*args: MutableMapping) -> Any\nMerges data comprehensively.
All arguments must be of the same type.
Parameters:
*args List of dicts to merge with the first one the base
TYPE: MutableMapping
DEFAULT: ()
Returns:
Any The merged data
"},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge.deep_merge","title":"deep_merge","text":"deep_merge(*dicts: dict) -> dict\nMerges dicts deeply.
Parameters:
*dicts List of dicts to merge with the first one as the base
TYPE: dict
DEFAULT: ()
Returns:
dict The merged dict
TYPE: dict
freeze_data(obj: Any) -> Any\nCheck type and recursively return a new read-only object.
"},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge.get_merge_strategy","title":"get_merge_strategy","text":"get_merge_strategy(\n path: Path, merge_strategies: Dict[str, str]\n) -> str\nReturn the merge strategy of the path based on the layer configured rules.
Files that are not mergable return DO_NOT_MERGE.
Parameters:
path The file path to evaluate.
TYPE: Path
merge_strategies The glob pattern->strategy mapping
TYPE: Dict[str, str]
Returns:
str The appropriate merge strategy.
"},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge.merge_iterables","title":"merge_iterables","text":"merge_iterables(iter1: Iterable, iter2: Iterable) -> set\nMerge and de-duplicate a bunch of lists into a single list.
Order is not guaranteed.
Parameters:
iter1 An Iterable
TYPE: Iterable
iter2 An Iterable
TYPE: Iterable
Returns:
set The merged, de-duplicated sequence as a set
"},{"location":"reference/api/cookie_composer/diff/","title":"Generating the difference between two directories.
Nabbed from Cruft: https://github.com/cruft/cruft/
"},{"location":"reference/api/cookie_composer/diff/#cookie_composer.diff-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/diff/#cookie_composer.diff-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/diff/#cookie_composer.diff.display_diff","title":"display_diff","text":"display_diff(repo0: Path, repo1: Path) -> None\nDisplays the diff between two repositories.
"},{"location":"reference/api/cookie_composer/diff/#cookie_composer.diff.get_diff","title":"get_diff","text":"get_diff(repo0: Path, repo1: Path) -> str\nCompute the raw diff between two repositories.
"},{"location":"reference/api/cookie_composer/diff/#cookie_composer.diff.replace_diff_prefixes","title":"replace_diff_prefixes","text":"replace_diff_prefixes(\n diff: str, repo0_path: str, repo1_path: str\n) -> str\nReplace the changed file prefixes in the diff output.
Our git diff --no-index command will output full paths like so::
--- upstream-template-old/tmp/tmpmp34g21y/remote/.coveragerc\n+++ upstream-template-new/tmp/tmpmp34g21y/local/.coveragerc\nThis isn\u2019t the format we need in order to apply the diff later on. The result of this command will change the paths to::
--- upstream-template-old/.coveragerc\n+++ upstream-template-new/.coveragerc\nNIX OPs have {prefix}/folder/file WIN OPS have {prefix}/c:/folder/file
More info on git-diff can be found here: http://git-scm.com/docs/git-diff
Parameters:
diff The diff output to change
TYPE: str
repo0_path The full string path to the source repo
TYPE: str
repo1_path The full string path to the destination repo
TYPE: str
Returns:
str The modified diff string
"},{"location":"reference/api/cookie_composer/exceptions/","title":"Exceptions raised when bad things happen.
"},{"location":"reference/api/cookie_composer/exceptions/#cookie_composer.exceptions-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/exceptions/#cookie_composer.exceptions.ChangesetUnicodeError","title":"ChangesetUnicodeError","text":"ChangesetUnicodeError()\n Bases: UsageError
Raised when cookie-composer update is unable to generate the diff.
EmptyZipRepositoryError(url: str)\n Bases: InvalidZipRepositoryError
Raised when a zip repository is empty.
"},{"location":"reference/api/cookie_composer/exceptions/#cookie_composer.exceptions.GitError","title":"GitError","text":" Bases: UsageError
There was a problem doing git operations.
"},{"location":"reference/api/cookie_composer/exceptions/#cookie_composer.exceptions.InvalidZipPasswordError","title":"InvalidZipPasswordError","text":"InvalidZipPasswordError()\n Bases: InvalidZipRepositoryError
Raised when a zip repository is password-protected.
"},{"location":"reference/api/cookie_composer/exceptions/#cookie_composer.exceptions.InvalidZipRepositoryError","title":"InvalidZipRepositoryError","text":"InvalidZipRepositoryError(message: str = '')\n Bases: UsageError
Raised when a zip repository is invalid.
"},{"location":"reference/api/cookie_composer/exceptions/#cookie_composer.exceptions.MergeError","title":"MergeError","text":"MergeError(\n origin: Optional[str] = None,\n destination: Optional[str] = None,\n strategy: Optional[str] = None,\n error_message: Optional[str] = \"\",\n)\n Bases: UsageError
There was a problem merging a file.
"},{"location":"reference/api/cookie_composer/exceptions/#cookie_composer.exceptions.MissingCompositionFileError","title":"MissingCompositionFileError","text":"MissingCompositionFileError(path_or_url: str)\n Bases: UsageError
The composition is missing or inaccessible.
"},{"location":"reference/api/cookie_composer/exceptions/#cookie_composer.exceptions.NoZipDirectoryError","title":"NoZipDirectoryError","text":"NoZipDirectoryError(url: str)\n Bases: InvalidZipRepositoryError
Raised when a zip repository does not contain a directory.
"},{"location":"reference/api/cookie_composer/git_commands/","title":"Functions for using git.
"},{"location":"reference/api/cookie_composer/git_commands/#cookie_composer.git_commands-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/git_commands/#cookie_composer.git_commands-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/git_commands/#cookie_composer.git_commands.apply_patch","title":"apply_patch","text":"apply_patch(repo: Repo, diff: str) -> None\nApply a patch to a destination directory.
A git 3 way merge is the best bet at applying patches.
Parameters:
repo The git repo to apply the patch to
TYPE: Repo
diff The previously calculated diff
TYPE: str
branch_exists(repo: Repo, branch_name: str) -> bool\nDoes the branch exist in the repo?
Parameters:
repo The repository to check
TYPE: Repo
branch_name The name of the branch to check for
TYPE: str
Returns:
bool True if the branch exists
checkout_branch(\n repo: Repo,\n branch_name: str,\n remote_name: str = \"origin\",\n) -> None\nCheckout a local or remote branch.
"},{"location":"reference/api/cookie_composer/git_commands/#cookie_composer.git_commands.checkout_ref","title":"checkout_ref","text":"checkout_ref(repo: Repo, ref: str) -> None\nCheckout a ref.
Parameters:
repo The repository to check out
TYPE: Repo
ref The ref to check out
TYPE: str
clone(\n repo_url: str, dest_path: Optional[Path] = None\n) -> Repo\nClone a repo.
Parameters:
repo_url Repo URL or local path.
TYPE: str
dest_path The path to clone to.
TYPE: Optional[Path]
DEFAULT: None
Returns:
Repo The repository.
"},{"location":"reference/api/cookie_composer/git_commands/#cookie_composer.git_commands.get_repo","title":"get_repo","text":"get_repo(\n project_dir: Union[str, Path],\n search_parent_directories: bool = False,\n ensure_clean: bool = False,\n) -> Repo\nGet the git Repo object for a directory.
Parameters:
project_dir The directory containing the .git folder
TYPE: Union[str, Path]
search_parent_directories if True, all parent directories will be searched for a valid repo as well.
TYPE: bool
DEFAULT: False
ensure_clean if True, raise an error if the repo is dirty
TYPE: bool
DEFAULT: False
Raises:
GitError If the directory is not a git repo
GitError If the directory git repository is dirty
Returns:
Repo The GitPython Repo object
"},{"location":"reference/api/cookie_composer/git_commands/#cookie_composer.git_commands.remote_branch_exists","title":"remote_branch_exists","text":"remote_branch_exists(\n repo: Repo,\n branch_name: str,\n remote_name: str = \"origin\",\n) -> bool\nDoes the branch exist in the remote repo?
Parameters:
repo The repository to check
TYPE: Repo
branch_name The name of the branch to check for
TYPE: str
remote_name The name of the remote reference. Defaults to origin
TYPE: str
DEFAULT: 'origin'
Returns:
bool True if the branch exists in the remote repository
temp_git_worktree_dir(\n repo_path: Path,\n worktree_path: Optional[Path] = None,\n branch: Optional[str] = None,\n commit: Optional[str] = None,\n) -> Iterator[Path]\nContext Manager for a temporary working directory of a branch in a git repo.
Inspired by https://github.com/thomasjahoda/cookiecutter_project_upgrader/blob/master/ cookiecutter_project_upgrader/logic.py
Logic for checking out a branch or commit:
Parameters:
repo_path The path to the template git repo
TYPE: Path
worktree_path The path put the worktree in. Defaults to a temporary directory.
TYPE: Optional[Path]
DEFAULT: None
branch The branch to check out
TYPE: Optional[str]
DEFAULT: None
commit The optional commit to check out
TYPE: Optional[str]
DEFAULT: None
Path The worktree_path
Raises:
GitError If the worktree could not be created
"},{"location":"reference/api/cookie_composer/io/","title":"Functions for handling input/output operations.
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/io/#cookie_composer.io-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.deserialize_composition","title":"deserialize_composition","text":"deserialize_composition(\n composition_info: List[dict],\n local_path: Optional[Path] = None,\n **kwargs\n) -> Composition\nDeserialize a composition from output.
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.deserialize_layer","title":"deserialize_layer","text":"deserialize_layer(\n layer_info: dict,\n local_path: Optional[Path] = None,\n **kwargs: Any\n) -> LayerConfig\nDeserialize a layer configuration from a rendered layer.
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.deserialize_rendered_composition","title":"deserialize_rendered_composition","text":"deserialize_rendered_composition(\n composition_info: List[dict], location: Path\n) -> RenderedComposition\nDeserialize a rendered composition from output.
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.deserialize_rendered_layer","title":"deserialize_rendered_layer","text":"deserialize_rendered_layer(\n rendered_layer_info: dict, location: Path\n) -> RenderedLayer\nDeserialize a rendered layer from output.
Parameters:
rendered_layer_info A dictionary containing the rendered layer information
TYPE: dict
location The location of the rendered layer, typically the parent directory of the parent directory of the .composition.yaml file
TYPE: Path
Returns:
RenderedLayer A rendered layer object
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.get_composition_from_path_or_url","title":"get_composition_from_path_or_url","text":"get_composition_from_path_or_url(\n path_or_url: str,\n checkout: Optional[str] = None,\n default_config: bool = False,\n directory: Optional[str] = None,\n no_input: bool = False,\n output_dir: Optional[Path] = None,\n overwrite_if_exists: bool = False,\n skip_if_file_exists: bool = False,\n initial_context: Optional[\n MutableMapping[str, Any]\n ] = None,\n) -> Composition\nGenerate a Composition from a path or URL.
Parameters:
path_or_url The path or url to the composition file or template
TYPE: str
checkout The branch, tag or commit to check out after git clone
TYPE: Optional[str]
DEFAULT: None
default_config Do not load a config file. Use the defaults instead
TYPE: bool
DEFAULT: False
directory Directory within repo that holds cookiecutter.json file
TYPE: Optional[str]
DEFAULT: None
no_input If True force each layer\u2019s no_input attribute to True
TYPE: bool
DEFAULT: False
output_dir Where to generate the project
TYPE: Optional[Path]
DEFAULT: None
overwrite_if_exists Overwrite the contents of the output directory if it already exists
TYPE: bool
DEFAULT: False
skip_if_file_exists Skip the files in the corresponding directories if they already exist
TYPE: bool
DEFAULT: False
initial_context The initial context for the composition
TYPE: Optional[MutableMapping[str, Any]]
DEFAULT: None
Returns:
Composition The composition object.
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.is_composition_file","title":"is_composition_file","text":"is_composition_file(path_or_url: Union[str, Path]) -> bool\nReturn True if the filename a composition file.
Parameters:
path_or_url The path or URL to check
TYPE: Union[str, Path]
Returns:
bool True if the path is a configuration file.
read_composition(\n path_or_url: Union[str, Path], **kwargs: Any\n) -> Composition\nRead a YAML file and return a Composition.
Parameters:
path_or_url The location of the configuration file
TYPE: Union[str, Path]
**kwargs Additional keyword arguments passed to the composition
TYPE: Any
DEFAULT: {}
Returns:
Composition A composition
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.read_rendered_composition","title":"read_rendered_composition","text":"read_rendered_composition(\n path: Path,\n) -> RenderedComposition\nRead a .composition.yaml from a rendered project.
Parameters:
path The path to the .composition.yaml file to read
TYPE: Path
Returns:
RenderedComposition The rendered composition information
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.read_yaml","title":"read_yaml","text":"read_yaml(path_or_url: Union[str, Path]) -> List[dict]\nRead a YAML file and return a list of dictionaries.
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.serialize_composition","title":"serialize_composition","text":"serialize_composition(\n layers: List[LayerConfig],\n) -> List[dict]\nSerialize a composition for output.
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.serialize_layer","title":"serialize_layer","text":"serialize_layer(layer: LayerConfig) -> dict\nSerialize the layer configuration for outputting in a rendered layer.
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.serialize_rendered_composition","title":"serialize_rendered_composition","text":"serialize_rendered_composition(\n composition: RenderedComposition,\n) -> List[dict]\nSerialize a rendered composition for output.
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.serialize_rendered_layer","title":"serialize_rendered_layer","text":"serialize_rendered_layer(\n rendered_layer: RenderedLayer,\n) -> dict\nSerialize a rendered layer for output.
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.write_rendered_composition","title":"write_rendered_composition","text":"write_rendered_composition(\n composition: RenderedComposition,\n) -> None\nWrite the composition file using the rendered layers to the appropriate place.
Parameters:
composition The rendered composition object to export
TYPE: RenderedComposition
write_yaml(path: Path, contents: List[dict]) -> None\nWrite a YAML file.
"},{"location":"reference/api/cookie_composer/layers/","title":"Layer management.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig","title":"LayerConfig","text":" Bases: BaseModel
Configuration for a layer of a composition.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.initial_context","title":"initial_contextclass-attribute instance-attribute","text":"initial_context: MutableMapping[str, Any] = Field(\n default_factory=dict\n)\nDictionary that will provide values for input.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.layer_name","title":"layer_nameproperty","text":"layer_name: str\nThe name of the template layer.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.merge_strategies","title":"merge_strategiesclass-attribute instance-attribute","text":"merge_strategies: Dict[str, str] = Field(\n default_factory=lambda: {\"*\": DO_NOT_MERGE}\n)\nThe method to merge specific paths or glob patterns.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.no_input","title":"no_inputclass-attribute instance-attribute","text":"no_input: bool = False\nDo not prompt for parameters and only use cookiecutter.json file content.
This is only used for initial generation. After initial generation, the results are stored in the context.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.overwrite","title":"overwriteclass-attribute instance-attribute","text":"overwrite: List[str] = Field(default_factory=list)\nPaths or glob patterns to always overwrite.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.overwrite_exclude","title":"overwrite_excludeclass-attribute instance-attribute","text":"overwrite_exclude: List[str] = Field(default_factory=list)\nPaths or glob patterns to exclude from overwriting.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.skip_generation","title":"skip_generationclass-attribute instance-attribute","text":"skip_generation: List[str] = Field(default_factory=list)\nPaths or glob patterns to skip attempting to generate.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.skip_hooks","title":"skip_hooksclass-attribute instance-attribute","text":"skip_hooks: bool = False\nSkip the template hooks.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.skip_if_file_exists","title":"skip_if_file_existsclass-attribute instance-attribute","text":"skip_if_file_exists: bool = True\nSkip the files in the corresponding directories if they already exist.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.template","title":"templateinstance-attribute","text":"template: Template\nInformation about the template.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.generate_context","title":"generate_context","text":"generate_context(\n default_context: MutableMapping[str, Any]\n) -> OrderedDict\nGet the context for prompting the user for values.
The order of precedence is:
initial_context from the composition or command-linedefault_context from the user_configraw context from the templateEquivalent to cookiecutter.generate.generate_context but with the following differences:
extra_context{\"cookiecutter\": ...}Parameters:
default_context The default context from the user_config
TYPE: MutableMapping[str, Any]
Returns:
OrderedDict A dict containing the context for prompting the user
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.RenderedLayer","title":"RenderedLayer","text":" Bases: BaseModel
Information about a rendered layer.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.RenderedLayer-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.RenderedLayer.latest_commit","title":"latest_commitproperty","text":"latest_commit: Optional[str]\nThe latest commit checked out if the layer source was a git repo.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.RenderedLayer.layer","title":"layerinstance-attribute","text":"layer: LayerConfig\nThe original layer configuration that was rendered.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.RenderedLayer.location","title":"locationinstance-attribute","text":"location: DirectoryPath\nThe directory where the layer was rendered.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.RenderedLayer.rendered_commit","title":"rendered_commitclass-attribute instance-attribute","text":"rendered_commit: Optional[str] = None\nIf a git template, this is the commit of the template that was rendered.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.RenderedLayer.rendered_context","title":"rendered_contextinstance-attribute","text":"rendered_context: MutableMapping[str, Any]\nThe context based on questions asked.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.RenderedLayer.rendered_name","title":"rendered_nameclass-attribute instance-attribute","text":"rendered_name: Optional[str] = None\nThe name of the rendered template directory.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.RenderedLayer-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.RenderedLayer.set_rendered_name","title":"set_rendered_nameclassmethod","text":"set_rendered_name(values: Dict[str, Any]) -> Dict[str, Any]\nSet the [cookie_composer.layers.RenderedLayer.layer_name] to the name of the rendered template directory.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.WriteStrategy","title":"WriteStrategy","text":" Bases: Enum
How to deal with a file.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.WriteStrategy-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.WriteStrategy.MERGE","title":"MERGEclass-attribute instance-attribute","text":"MERGE = 3\nMerge the file with an existing file, or write a new file.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.WriteStrategy.SKIP","title":"SKIPclass-attribute instance-attribute","text":"SKIP = 2\nSkip the file.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.WriteStrategy.WRITE","title":"WRITEclass-attribute instance-attribute","text":"WRITE = 1\nWrite or overwrite the file.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.get_accept_hooks_per_layer","title":"get_accept_hooks_per_layer","text":"get_accept_hooks_per_layer(\n accept_hooks: str, num_layers: int\n) -> list\nConvert a single accept_hooks value into a value for every layer based on num_layers.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.get_layer_context","title":"get_layer_context","text":"get_layer_context(\n template_repo_dir: Path,\n context_for_prompting: dict,\n initial_context: MutableMapping[str, Any],\n full_context: Context,\n no_input: bool = False,\n) -> dict\nGet the context for a layer pre-rendering values using previous layers contexts as defaults.
The layer context is the combination of several things:
Parameters:
template_repo_dir The location of the template repo to use for rendering
TYPE: Path
context_for_prompting The raw context from the cookiecutter.json file with user defaults applied
TYPE: dict
initial_context The initial context from the layer configuration
TYPE: MutableMapping[str, Any]
full_context A full context from previous layers.
TYPE: Context
no_input If False do not prompt for missing values and use defaults instead.
TYPE: bool
DEFAULT: False
Returns:
dict A dict containing the context for rendering the layer
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.get_template_rendered_name","title":"get_template_rendered_name","text":"get_template_rendered_name(\n template: Template, context: MutableMapping\n) -> str\nFind and render the template\u2019s root directory\u2019s name.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.get_write_strategy","title":"get_write_strategy","text":"get_write_strategy(\n origin: Path,\n destination: Path,\n rendered_layer: RenderedLayer,\n) -> WriteStrategy\nBased on the layer_config rules, determine if we should overwrite an existing path.
Parameters:
origin Path within the rendered layer that we are evaluating.
TYPE: Path
destination Path to which we would write this file (may not actually exist)
TYPE: Path
rendered_layer Rendered layer configuration.
TYPE: RenderedLayer
Returns:
WriteStrategy The appropriate way to handle writing this file.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.merge_layers","title":"merge_layers","text":"merge_layers(\n destination: Path, rendered_layer: RenderedLayer\n) -> None\nMerge a layer into another layer using the rules specified in the layer_config.
Parameters:
destination The root path to merge into.
TYPE: Path
rendered_layer The information about the rendered layer.
TYPE: RenderedLayer
render_layer(\n layer_config: LayerConfig,\n render_dir: Path,\n full_context: Optional[Context] = None,\n commit: Optional[str] = None,\n accept_hooks: str = \"yes\",\n) -> RenderedLayer\nProcess one layer of the template composition.
Renders the template using cookiecutter.
Parameters:
layer_config The configuration of the layer to render
TYPE: LayerConfig
render_dir Where to render the template
TYPE: Path
full_context The extra context from all layers in the composition
TYPE: Optional[Context]
DEFAULT: None
commit The commit to checkout if the template is a git repo
TYPE: Optional[str]
DEFAULT: None
accept_hooks Accept pre- and post-hooks if set to True
TYPE: str
DEFAULT: 'yes'
Returns:
RenderedLayer The rendered layer information
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.render_layers","title":"render_layers","text":"render_layers(\n layers: List[LayerConfig],\n destination: Path,\n initial_context: Optional[dict] = None,\n no_input: bool = False,\n accept_hooks: str = \"all\",\n) -> List[RenderedLayer]\nRender layers to a destination.
Parameters:
layers A list of LayerConfig to render
TYPE: List[LayerConfig]
destination The location to merge the rendered layers to
TYPE: Path
initial_context An initial context to pass to the rendering
TYPE: Optional[dict]
DEFAULT: None
no_input If True force each layer\u2019s no_input attribute to True
TYPE: bool
DEFAULT: False
accept_hooks How to process pre/post hooks.
TYPE: str
DEFAULT: 'all'
Returns:
List[RenderedLayer] A list of the rendered layer information
"},{"location":"reference/api/cookie_composer/matching/","title":"Matching files and patterns.
"},{"location":"reference/api/cookie_composer/matching/#cookie_composer.matching-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/matching/#cookie_composer.matching.matches_any_glob","title":"matches_any_glob","text":"matches_any_glob(\n path: Union[str, Path], patterns: List[str]\n) -> bool\nDoes the path match any of the glob patterns?
Parameters:
path Path to test
TYPE: Union[str, Path]
patterns A list of glob patterns
TYPE: List[str]
Returns:
bool True if it matches any of the patterns
rel_fnmatch(name: str, pat: str) -> bool\nForce a relative match of the pattern by prefixing a *.
Utilities not easily categorized.
"},{"location":"reference/api/cookie_composer/utils/#cookie_composer.utils-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/utils/#cookie_composer.utils.echo","title":"echo","text":"echo(\n message: Optional[Any] = None,\n file: Optional[IO] = None,\n nl: bool = True,\n err: bool = False,\n color: Optional[bool] = None,\n **styles: Any\n) -> None\nA local abstraction for printing messages.
Default behavior is that of click.secho.
This is to allow user feedback without every function requiring a click dependency. Especially during testing.
Parameters:
message The string or bytes to output. Other objects are converted to strings.
TYPE: Optional[Any]
DEFAULT: None
file The file to write to. Defaults to stdout.
TYPE: Optional[IO]
DEFAULT: None
nl Print a newline after the message. Enabled by default.
TYPE: bool
DEFAULT: True
err Write to stderr instead of stdout.
TYPE: bool
DEFAULT: False
color Force showing or hiding colors and other styles. By default Click will remove color if the output does not look like an interactive terminal.
TYPE: Optional[bool]
DEFAULT: None
**styles Style keyword arguments
TYPE: Any
DEFAULT: {}
get_deleted_files(\n template_dir: Path, project_dir: Path\n) -> Set[Path]\nGet a list of files in the rendered template that do not exist in the project.
This is to avoid introducing changes that won\u2019t apply cleanly to the current project.
Nabbed from Cruft: https://github.com/cruft/cruft/
Parameters:
template_dir The path to the directory rendered with the same context as the project
TYPE: Path
project_dir The path to the current project
TYPE: Path
Returns:
Set[Path] A set of paths that are missing
"},{"location":"reference/api/cookie_composer/utils/#cookie_composer.utils.remove_paths","title":"remove_paths","text":"remove_paths(\n root: Path, paths_to_remove: Set[Path]\n) -> None\nRemove all paths in paths_to_remove from root.
Nabbed from Cruft: https://github.com/cruft/cruft/
Parameters:
root The absolute path of the directory requiring path removal
TYPE: Path
paths_to_remove The set of relative paths to remove from root
TYPE: Set[Path]
remove_readonly_bit(\n func: Callable[[str], None], path: str, _: Any\n) -> None\nClear the readonly bit and reattempt the removal.
"},{"location":"reference/api/cookie_composer/utils/#cookie_composer.utils.remove_single_path","title":"remove_single_path","text":"remove_single_path(path: Path) -> None\nRemove a path with extra error handling for Windows.
Parameters:
path The path to remove
TYPE: Path
Raises:
IOError If the file could not be removed
"},{"location":"reference/api/cookie_composer/utils/#cookie_composer.utils.temporary_copy","title":"temporary_copy","text":"temporary_copy(original_path: Path) -> Iterator[Path]\nCreate a temporary copy of a file or directory.
Parameters:
original_path The path to the file or directory to copy
TYPE: Path
Path The path to the temporary copy
"},{"location":"reference/api/cookie_composer/commands/","title":"Index","text":"Commands for cookie composer.
"},{"location":"reference/api/cookie_composer/commands/add/","title":"The implementation of the add command.
"},{"location":"reference/api/cookie_composer/commands/add/#cookie_composer.commands.add-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/commands/add/#cookie_composer.commands.add.add_cmd","title":"add_cmd","text":"add_cmd(\n path_or_url: str,\n destination_dir: Optional[Path] = None,\n no_input: bool = False,\n checkout: Optional[str] = None,\n directory: Optional[str] = None,\n overwrite_if_exists: bool = False,\n skip_if_file_exists: bool = False,\n default_config: bool = False,\n accept_hooks: str = \"all\",\n initial_context: Optional[\n MutableMapping[str, Any]\n ] = None,\n) -> None\nAdd a template or configuration to an existing project.
Parameters:
path_or_url A URL or string to add the template or configuration
TYPE: str
destination_dir The project directory to add the layer to
TYPE: Optional[Path]
DEFAULT: None
no_input If True force each layer\u2019s no_input attribute to True
TYPE: bool
DEFAULT: False
checkout The branch, tag or commit to check out after git clone
TYPE: Optional[str]
DEFAULT: None
directory Directory within repo that holds cookiecutter.json file
TYPE: Optional[str]
DEFAULT: None
overwrite_if_exists Overwrite the contents of the output directory if it already exists
TYPE: bool
DEFAULT: False
skip_if_file_exists Skip the files in the corresponding directories if they already exist
TYPE: bool
DEFAULT: False
default_config Do not load a config file. Use the defaults instead
TYPE: bool
DEFAULT: False
accept_hooks How to deal with pre/post hooks
TYPE: str
DEFAULT: 'all'
initial_context The initial context for the composition layer
TYPE: Optional[MutableMapping[str, Any]]
DEFAULT: None
Raises:
GitError If the destination_dir is not a git repository
ValueError If there is not a .composition.yaml file in the destination directory
"},{"location":"reference/api/cookie_composer/commands/authn/","title":"Authentication subcommands.
"},{"location":"reference/api/cookie_composer/commands/authn/#cookie_composer.commands.authn-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/commands/authn/#cookie_composer.commands.authn.auth","title":"auth","text":"auth() -> None\nAuthenticate cookie-composer to a service.
"},{"location":"reference/api/cookie_composer/commands/authn/#cookie_composer.commands.authn.login","title":"login","text":"login(\n git_protocol: str,\n service: str,\n scopes: str,\n with_token: click.File,\n) -> None\nAuthenticate to a service.
"},{"location":"reference/api/cookie_composer/commands/authn/#cookie_composer.commands.authn.token","title":"token","text":"token(service: str) -> None\nPrint the auth token cookie-composer is configured to use.
"},{"location":"reference/api/cookie_composer/commands/create/","title":"Methods for generating projects.
"},{"location":"reference/api/cookie_composer/commands/create/#cookie_composer.commands.create-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/commands/create/#cookie_composer.commands.create-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/commands/create/#cookie_composer.commands.create.create_cmd","title":"create_cmd","text":"create_cmd(\n path_or_url: str,\n output_dir: Optional[Path] = None,\n no_input: bool = False,\n checkout: Optional[str] = None,\n directory: Optional[str] = None,\n overwrite_if_exists: bool = False,\n skip_if_file_exists: bool = False,\n default_config: bool = False,\n accept_hooks: str = \"all\",\n initial_context: Optional[\n MutableMapping[str, Any]\n ] = None,\n) -> Path\nGenerate a new project from a composition file, local template or remote template.
Parameters:
path_or_url The path or url to the composition file or template
TYPE: str
output_dir Where to generate the project
TYPE: Optional[Path]
DEFAULT: None
no_input If True force each layer\u2019s no_input attribute to True
TYPE: bool
DEFAULT: False
checkout The branch, tag or commit to check out after git clone
TYPE: Optional[str]
DEFAULT: None
directory Directory within repo that holds cookiecutter.json file
TYPE: Optional[str]
DEFAULT: None
overwrite_if_exists Overwrite the contents of the output directory if it already exists
TYPE: bool
DEFAULT: False
skip_if_file_exists Skip the files in the corresponding directories if they already exist
TYPE: bool
DEFAULT: False
default_config Do not load a config file. Use the defaults instead
TYPE: bool
DEFAULT: False
accept_hooks Which pre/post hooks should be applied?
TYPE: str
DEFAULT: 'all'
initial_context The initial context for the composition
TYPE: Optional[MutableMapping[str, Any]]
DEFAULT: None
Raises:
ClickException If there is a problem cloning the repository
Returns:
Path The path to the generated project.
"},{"location":"reference/api/cookie_composer/commands/link/","title":"The implementation of the link command.
"},{"location":"reference/api/cookie_composer/commands/link/#cookie_composer.commands.link-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/commands/link/#cookie_composer.commands.link.link_cmd","title":"link_cmd","text":"link_cmd(\n path_or_url: str,\n destination_dir: Optional[Path] = None,\n no_input: bool = False,\n checkout: Optional[str] = None,\n directory: Optional[str] = None,\n overwrite_if_exists: bool = False,\n skip_if_file_exists: bool = False,\n default_config: bool = False,\n initial_context: Optional[\n MutableMapping[str, Any]\n ] = None,\n) -> None\nLink a template or configuration to an existing project.
Parameters:
path_or_url A URL or string to add the template or configuration
TYPE: str
destination_dir The project directory to add the layer to
TYPE: Optional[Path]
DEFAULT: None
no_input If True force each layer\u2019s no_input attribute to True
TYPE: bool
DEFAULT: False
checkout The branch, tag or commit to check out after git clone
TYPE: Optional[str]
DEFAULT: None
directory Directory within repo that holds cookiecutter.json file
TYPE: Optional[str]
DEFAULT: None
overwrite_if_exists Overwrite the contents of the output directory if it already exists
TYPE: bool
DEFAULT: False
skip_if_file_exists Skip the files in the corresponding directories if they already exist
TYPE: bool
DEFAULT: False
default_config Do not load a config file. Use the defaults instead
TYPE: bool
DEFAULT: False
initial_context The initial context for the composition
TYPE: Optional[MutableMapping[str, Any]]
DEFAULT: None
Raises:
GitError If the destination_dir is not a git repository
GitError If the destination_dir git repository is dirty
ValueError If there is a .composition.yaml file in the destination directory
"},{"location":"reference/api/cookie_composer/commands/update/","title":"The implementation of the update command.
"},{"location":"reference/api/cookie_composer/commands/update/#cookie_composer.commands.update-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/commands/update/#cookie_composer.commands.update-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/commands/update/#cookie_composer.commands.update.update_cmd","title":"update_cmd","text":"update_cmd(\n project_dir: Optional[Path] = None,\n no_input: bool = False,\n) -> None\nUpdate the project with the latest versions of each layer.
Parameters:
project_dir The project directory to update. Defaults to current directory.
TYPE: Optional[Path]
DEFAULT: None
no_input If True force each layer\u2019s no_input attribute to True
TYPE: bool
DEFAULT: False
Raises:
GitError If the destination_dir is not a git repository
ValueError If there is not a .composition.yaml file in the destination directory
"},{"location":"reference/api/cookie_composer/commands/update/#cookie_composer.commands.update.update_rendered_composition_layers","title":"update_rendered_composition_layers","text":"update_rendered_composition_layers(\n base: RenderedComposition,\n updated_layers: List[RenderedLayer],\n) -> RenderedComposition\nUpdate base.layers with updated_layers where layer names match.
If, for some reason, a layer exists in updated_layers but not in base, it is discarded.
Parameters:
base The base composition whose layers are to be updated
TYPE: RenderedComposition
updated_layers The new rendered layers
TYPE: List[RenderedLayer]
Raises:
RuntimeError If a layer\u2019s location render_dir properties don\u2019t match
RuntimeError If the compositions\u2019 rendered_name properties don\u2019t match
Returns:
RenderedComposition A new composition with updated layers
"},{"location":"reference/api/cookie_composer/merge_files/","title":"Index","text":"Methods for merging data files.
The merging functions should look similar to the following:
def merge_generic_files(origin: Path, destination: Path, merge_strategy: str) -> None:\nThe function must write the file to destination.
The function must wrap any errors into a MergeError and raise it.
"},{"location":"reference/api/cookie_composer/merge_files/#cookie_composer.merge_files-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/merge_files/ini_file/","title":"Merge two .ini files into one.
"},{"location":"reference/api/cookie_composer/merge_files/ini_file/#cookie_composer.merge_files.ini_file-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/merge_files/ini_file/#cookie_composer.merge_files.ini_file-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/merge_files/ini_file/#cookie_composer.merge_files.ini_file-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/merge_files/ini_file/#cookie_composer.merge_files.ini_file.config_to_dict","title":"config_to_dict","text":"config_to_dict(config: configparser.ConfigParser) -> dict\nConvert a configparser object to a dictionary.
"},{"location":"reference/api/cookie_composer/merge_files/ini_file/#cookie_composer.merge_files.ini_file.dict_to_config","title":"dict_to_config","text":"dict_to_config(\n dictionary: dict,\n) -> configparser.ConfigParser\nConvert a dict to a configparser object.
"},{"location":"reference/api/cookie_composer/merge_files/ini_file/#cookie_composer.merge_files.ini_file.merge_ini_files","title":"merge_ini_files","text":"merge_ini_files(\n new_file: Path, existing_file: Path, merge_strategy: str\n) -> None\nMerge two INI files into one.
Raises:
MergeError If something goes wrong
Parameters:
new_file The path to the data file to merge
TYPE: Path
existing_file The path to the data file to merge into and write out.
TYPE: Path
merge_strategy How to do the merge
TYPE: str
Merge two json files into one.
"},{"location":"reference/api/cookie_composer/merge_files/json_file/#cookie_composer.merge_files.json_file-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/merge_files/json_file/#cookie_composer.merge_files.json_file-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/merge_files/json_file/#cookie_composer.merge_files.json_file-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/merge_files/json_file/#cookie_composer.merge_files.json_file.default","title":"default","text":"default(obj: Any) -> dict\nDefault JSON encoder.
"},{"location":"reference/api/cookie_composer/merge_files/json_file/#cookie_composer.merge_files.json_file.merge_json_files","title":"merge_json_files","text":"merge_json_files(\n new_file: Path, existing_file: Path, merge_strategy: str\n) -> None\nMerge two json files into one.
Parameters:
new_file The path to the data file to merge
TYPE: Path
existing_file The path to the data file to merge into and write out.
TYPE: Path
merge_strategy How to do the merge
TYPE: str
Raises:
MergeError If something goes wrong
"},{"location":"reference/api/cookie_composer/merge_files/toml_file/","title":"Merge two toml files into one.
"},{"location":"reference/api/cookie_composer/merge_files/toml_file/#cookie_composer.merge_files.toml_file-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/merge_files/toml_file/#cookie_composer.merge_files.toml_file-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/merge_files/toml_file/#cookie_composer.merge_files.toml_file-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/merge_files/toml_file/#cookie_composer.merge_files.toml_file.merge_toml_files","title":"merge_toml_files","text":"merge_toml_files(\n new_file: Path, existing_file: Path, merge_strategy: str\n) -> None\nMerge two toml files into one.
Parameters:
new_file The path to the data file to merge
TYPE: Path
existing_file The path to the data file to merge into and write out.
TYPE: Path
merge_strategy How to do the merge
TYPE: str
Raises:
MergeError If something goes wrong
"},{"location":"reference/api/cookie_composer/merge_files/yaml_file/","title":"Merge two json files into one.
"},{"location":"reference/api/cookie_composer/merge_files/yaml_file/#cookie_composer.merge_files.yaml_file-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/merge_files/yaml_file/#cookie_composer.merge_files.yaml_file-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/merge_files/yaml_file/#cookie_composer.merge_files.yaml_file-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/merge_files/yaml_file/#cookie_composer.merge_files.yaml_file.merge_yaml_files","title":"merge_yaml_files","text":"merge_yaml_files(\n new_file: Path, existing_file: Path, merge_strategy: str\n) -> None\nMerge two json files into one.
Parameters:
new_file The path to the data file to merge
TYPE: Path
existing_file The path to the data file to merge into and write out.
TYPE: Path
merge_strategy How to do the merge
TYPE: str
Raises:
MergeError If something goes wrong
"},{"location":"reference/api/cookie_composer/templates/","title":"Index","text":"Templates for cookie_composer.
"},{"location":"reference/api/cookie_composer/templates/git_repo/","title":"Utility functions for handling and fetching repo archives in git format.
"},{"location":"reference/api/cookie_composer/templates/git_repo/#cookie_composer.templates.git_repo-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/templates/git_repo/#cookie_composer.templates.git_repo-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/templates/git_repo/#cookie_composer.templates.git_repo.get_cached_remote","title":"get_cached_remote","text":"get_cached_remote(\n git_uri: str,\n cache_dir: Path,\n checkout: Optional[str] = None,\n) -> Repo\nReturn a cached remote repo.
This provides some error-checking for the cached repo, and will re-clone if the cached repo is in a detached head state.
Parameters:
git_uri The remote git URI
TYPE: str
cache_dir The directory to cache the repo in
TYPE: Path
checkout The optional checkout ref to use
TYPE: Optional[str]
DEFAULT: None
Returns:
Repo The cached repo
"},{"location":"reference/api/cookie_composer/templates/git_repo/#cookie_composer.templates.git_repo.get_repo_name","title":"get_repo_name","text":"get_repo_name(\n repo_url: str, checkout: Optional[str] = None\n) -> str\nConstruct the destination repo name from the repo URL and checkout.
"},{"location":"reference/api/cookie_composer/templates/git_repo/#cookie_composer.templates.git_repo.template_repo_from_git","title":"template_repo_from_git","text":"template_repo_from_git(\n git_uri: str,\n locality: Locality,\n cache_dir: Path,\n checkout: Optional[str] = None,\n) -> TemplateRepo\nReturn a template repo from a git URI.
mytemplate_main. This allows for multiple versions of the same repo to be cached without a conflict.checkout, and the local path is returned.Entry point for cookiecutter templates.
"},{"location":"reference/api/cookie_composer/templates/source/#cookie_composer.templates.source-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/templates/source/#cookie_composer.templates.source-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/templates/source/#cookie_composer.templates.source.get_template_repo","title":"get_template_repo","text":"get_template_repo(\n url: str,\n local_path: Optional[Path] = None,\n checkout: Optional[str] = None,\n password: Optional[str] = None,\n) -> TemplateRepo\nGet a template repository from a URL.
Parameters:
url The string from the template field in the composition file.
TYPE: str
local_path Used to resolve local paths.
TYPE: Optional[Path]
DEFAULT: None
checkout The branch, tag or commit to check out after git clone
TYPE: Optional[str]
DEFAULT: None
password The password to use if template is a password-protected Zip archive.
TYPE: Optional[str]
DEFAULT: None
Returns:
TemplateRepo A TemplateRepo object.
"},{"location":"reference/api/cookie_composer/templates/source/#cookie_composer.templates.source.identify_repo","title":"identify_repo","text":"identify_repo(\n url: str, local_path: Optional[Path] = None\n) -> Tuple[TemplateFormat, Locality]\nIdentify the repo format and locality from the URL.
"},{"location":"reference/api/cookie_composer/templates/source/#cookie_composer.templates.source.resolve_local_path","title":"resolve_local_path","text":"resolve_local_path(\n url: str, local_path: Optional[Path] = None\n) -> Path\nResolve a local path.
Parameters:
url The string from the template field in the composition file.
TYPE: str
local_path An optional path to resolve the URL against.
TYPE: Optional[Path]
DEFAULT: None
Returns:
Path The resolved path.
"},{"location":"reference/api/cookie_composer/templates/types/","title":"Datatypes for templates.
Templates are a representation of source templates used to generate projects.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Locality","title":"Locality","text":" Bases: str, Enum
The locality of a template.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Template","title":"Templatedataclass","text":"Template(\n repo: TemplateRepo,\n directory: str = \"\",\n _context: Optional[OrderedDict] = None,\n)\nA template is the combination of a template repository and a directory containing a cookiecutter.json file.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Template-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Template.cached_path","title":"cached_pathproperty","text":"cached_path: Path\nThe path to the cached template.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Template.context","title":"contextproperty","text":"context: dict\nThe context of the template.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Template.context_file_path","title":"context_file_pathproperty","text":"context_file_path: Path\nThe path to the template\u2019s context file.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Template.directory","title":"directoryclass-attribute instance-attribute","text":"directory: str = ''\nThe directory within the repository that contains the cookiecutter.json file.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Template.name","title":"nameproperty","text":"name: str\nThe name of the template.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Template.repo","title":"repoinstance-attribute","text":"repo: TemplateRepo\nThe source of the template.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Template-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Template.cleanup","title":"cleanup","text":"cleanup() -> None\nRemove the cached template if it is a Zipfile.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateFormat","title":"TemplateFormat","text":" Bases: str, Enum
The format of a template.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateFormat-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateFormat.PLAIN","title":"PLAINclass-attribute instance-attribute","text":"PLAIN = 'plain'\nA plain directory that isn\u2019t under version control.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo","title":"TemplateRepodataclass","text":"TemplateRepo(\n source: str,\n cached_source: Path,\n format: TemplateFormat,\n locality: Locality,\n checkout: Optional[str] = None,\n password: Optional[str] = None,\n)\nA template repository is a source of one or more templates.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo.cached_source","title":"cached_sourceinstance-attribute","text":"cached_source: Path\nThe path to the locally cached template.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo.checkout","title":"checkoutclass-attribute instance-attribute","text":"checkout: Optional[str] = None\nThe branch, tag or commit for the template to track.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo.current_sha","title":"current_shaproperty","text":"current_sha: Optional[str]\nIf the template is a git repository, return the current commit hash.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo.format","title":"formatinstance-attribute","text":"format: TemplateFormat\nThe format of the template.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo.latest_sha","title":"latest_shaproperty","text":"latest_sha: Optional[str]\nReturn the latest SHA of this template\u2019s repo.
If the template is not a git repository, it will always return None.
Returns:
Optional[str] The latest hexsha of the template or None if the template isn\u2019t a git repo
instance-attribute","text":"locality: Locality\nIs the template local or remote?
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo.password","title":"passwordclass-attribute instance-attribute","text":"password: Optional[str] = None\nThe password to use if template is a password-protected Zip archive.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo.source","title":"sourceinstance-attribute","text":"source: str\nThe original path or URL to the template.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo.render_source","title":"render_source","text":"render_source(\n output_dir: Optional[Path] = None,\n commit: Optional[str] = None,\n) -> Iterator[Path]\nA context manager that provides the source from which to render the template.
For git repositories, this will create a temporary working tree of the repository and yield the path to the working tree.
For Zip archives, this will extract the archive to a temporary directory and yield the path
For plain repos, it will yield the path to the directory.
Parameters:
output_dir The directory to extract the template to. If not provided, a temporary directory will be used.
TYPE: Optional[Path]
DEFAULT: None
commit The commit to checkout if the template is a git repository.
TYPE: Optional[str]
DEFAULT: None
Path The path to the rendered template
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.get_template_name","title":"get_template_name","text":"get_template_name(\n path_or_url: str,\n directory: Optional[str] = None,\n checkout: Optional[str] = None,\n) -> str\nGet the name of the template using the path or URL.
Parameters:
path_or_url The URL or path to the template
TYPE: str
directory Directory within a git repository template that holds the cookiecutter.json file.
TYPE: Optional[str]
DEFAULT: None
checkout The branch, tag or commit to use if template is a git repository.
TYPE: Optional[str]
DEFAULT: None
Raises:
ValueError If the path_or_url is not parsable
Returns:
str The name of the template without extensions
"},{"location":"reference/api/cookie_composer/templates/zipfile_repo/","title":"Utility functions for handling and fetching repo archives in zip format.
"},{"location":"reference/api/cookie_composer/templates/zipfile_repo/#cookie_composer.templates.zipfile_repo-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/templates/zipfile_repo/#cookie_composer.templates.zipfile_repo-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/templates/zipfile_repo/#cookie_composer.templates.zipfile_repo.cache_source","title":"cache_source","text":"cache_source(\n zip_uri: str,\n is_remote: bool,\n cache_dir: Path,\n no_input: bool = False,\n) -> Path\nDownload and unpack a zipfile at a given URI.
This will download the zipfile to the cookiecutter repository, and unpack into a temporary directory.
Parameters:
zip_uri The URI for the zipfile.
TYPE: str
is_remote Is the zip URI a URL or a file?
TYPE: bool
cache_dir The cookiecutter repository directory to put the archive into.
TYPE: Path
no_input Do not prompt for user input and eventually force a refresh of cached resources.
TYPE: bool
DEFAULT: False
Returns:
Path The path to the unpacked zipfile.
"},{"location":"reference/api/cookie_composer/templates/zipfile_repo/#cookie_composer.templates.zipfile_repo.download_zipfile","title":"download_zipfile","text":"download_zipfile(\n url: str, cache_dir: Path, no_input: bool = False\n) -> Path\nDownload a zipfile from a URL into the cache_dir.
"},{"location":"reference/api/cookie_composer/templates/zipfile_repo/#cookie_composer.templates.zipfile_repo.extract_zipfile","title":"extract_zipfile","text":"extract_zipfile(\n zip_path: Path,\n output_dir: Optional[Path] = None,\n password: Optional[str] = None,\n) -> Path\nExtract a zipfile into a temporary directory.
Parameters:
zip_path The path to the zipfile.
TYPE: Path
output_dir Optional path to extract the zipfile to. Defaults to a temporary directory.
TYPE: Optional[Path]
DEFAULT: None
password The password for a password-protected zipfile.
TYPE: Optional[str]
DEFAULT: None
Raises:
InvalidZipPasswordError If the zipfile is password-protected and the user provides an incorrect password.
Returns:
Path The temporary directory containing the unpacked zipfile.
"},{"location":"reference/api/cookie_composer/templates/zipfile_repo/#cookie_composer.templates.zipfile_repo.template_repo_from_zipfile","title":"template_repo_from_zipfile","text":"template_repo_from_zipfile(\n zip_uri: str,\n locality: Locality,\n cache_dir: Path,\n no_input: bool = False,\n password: Optional[str] = None,\n) -> TemplateRepo\nReturn a template repo from a zipfile URI.
"},{"location":"reference/api/cookie_composer/templates/zipfile_repo/#cookie_composer.templates.zipfile_repo.validate_zipfile","title":"validate_zipfile","text":"validate_zipfile(zip_path: Path, zip_uri: str) -> None\nValidate that a zipfile exists and is not empty.
Parameters:
zip_path The path to the zipfile.
TYPE: Path
zip_uri The origin URI of the zipfile.
TYPE: str
Raises:
EmptyZipRepositoryError If the zipfile is empty.
NoZipDirectoryError If the zipfile does not contain a top-level directory.
"},{"location":"topic-guides/","title":"Topic Guides","text":""},{"location":"topic-guides/composition-files/","title":"Composition files","text":"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 compositiontemplate: \"https://github.com/coordt/cookiecomposer-templates\"\ndirectory: \"cookiecutter-boilerplate\"\nmerge_strategies:\n '*.json': \"comprehensive\"\n '*.yaml': \"comprehensive\"\n '*.yml': \"comprehensive\"\n---\ntemplate: \"https://github.com/coordt/cookiecomposer-templates\"\ndirectory: \"cookiecutter-package\"\nmerge_strategies:\n '*.json': \"comprehensive\"\n '*.yaml': \"comprehensive\"\n '*.yml': \"comprehensive\"\n---\ntemplate: \"https://github.com/coordt/cookiecomposer-templates\"\ndirectory: \"cookiecutter-docs\"\nmerge_strategies:\n '*.json': \"comprehensive\"\n '*.yaml': \"comprehensive\"\n '*.yml': \"comprehensive\"\nWhen 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\nproject_name [python-boilerplate]: my-test-project\nproject_slug [my_test_project]:\nfriendly_name [My Test Project]:\nproject_short_description []:\nversion [0.1.0]:\nauthor [Who am I?]:\nemail [whoami@existential-crisis.doom]:\ngithub_user [whoami]:\nThe composition file saved in the new project (named my-test-project in this example) as .composition.yaml would look like:
checkout: null\ncommit: 3391f60471939dd412e93e9853e3328e7a5a8c44\ncontext:\n _copy_without_render: [.github/**/*.jinja]\n _dev_requirements: {bump2version: '>=1.0.1', generate-changelog: '>=0.7.6', git-fame: '>=1.12.2',\n pip-tools: ''}\n _prod_requirements: {environs: '>=9.3.5'}\n _test_requirements: {black: '>=19.10b0', coverage: '>=6.1.2', flake8: '>=4.0.1',\n pre-commit: '>=2.15.0', pytest: '>=6.0.0', pytest-cov: '>=3.0.0'}\n author: Who am I?\n email: whoami@existential-crisis.doom\n friendly_name: My Test Project\n github_user: whoami\n project_name: my-test-project\n project_short_description: ''\n project_slug: my_test_project\n version: 0.1.0\ndirectory: cookiecutter-boilerplate\nmerge_strategies: {'*.json': comprehensive, '*.yaml': comprehensive, '*.yml': comprehensive}\nno_input: false\noverwrite: []\noverwrite_exclude: []\npassword: null\nskip_generation: []\nskip_hooks: false\nskip_if_file_exists: true\ntemplate: https://github.com/coordt/cookiecomposer-templates\n---\ncheckout: null\ncommit: 3391f60471939dd412e93e9853e3328e7a5a8c44\ncontext: {friendly_name: My Test Project, project_name: my-test-project, project_short_description: '',\n project_slug: my_test_project, version: 0.1.0}\ndirectory: cookiecutter-package\nmerge_strategies: {'*.json': comprehensive, '*.yaml': comprehensive, '*.yml': comprehensive}\nno_input: false\noverwrite: []\noverwrite_exclude: []\npassword: null\nskip_generation: []\nskip_hooks: false\nskip_if_file_exists: true\ntemplate: https://github.com/coordt/cookiecomposer-templates\n---\ncheckout: null\ncommit: 3391f60471939dd412e93e9853e3328e7a5a8c44\ncontext:\n _copy_without_render: [docsrc/**/*.rst]\n _dev_requirements: {bump2version: '>=1.0.1', generate-changelog: '>=0.7.6', git-fame: '>=1.12.2',\n pip-tools: ''}\n _docs_requirements: {Sphinx: '>=4.3.0', furo: '', ghp-import: '', linkify-it-py: '',\n myst-parser: '', sphinx-autodoc-typehints: '', sphinx-click: '', sphinx-copybutton: ''}\n _prod_requirements: {environs: '>=9.3.5'}\n friendly_name: My Test Project\n github_user: whoami\n project_name: my-test-project\n project_slug: my_test_project\ndirectory: cookiecutter-docs\nmerge_strategies: {'*.json': comprehensive, '*.yaml': comprehensive, '*.yml': comprehensive}\nno_input: false\noverwrite: []\noverwrite_exclude: []\npassword: null\nskip_generation: []\nskip_hooks: false\nskip_if_file_exists: true\ntemplate: https://github.com/coordt/cookiecomposer-templates\nIf you look closely you\u2019ll see that .composition.yaml contains the contents of package-composition.yaml. Internally the .composition.yaml file is termed a \u201crendered composition\u201d because it contains all the parameters used to render this specific project. This rendered composition is used when applying updates of the templates.
Composition files are technically YAML streams consisting of one or more documents describing a layer configuration.
"},{"location":"tutorial/","title":"Tutorial","text":""},{"location":"tutorial/composable-templates/","title":"Designing composable templates","text":""},{"location":"tutorial/compositions/","title":"Building a project from a composition","text":"Do the same thing as incrementally layering, but use a composition to alleviate the issues.
Issues to resolve:
A composition is a series of template layers. We can reproduce the results of the previous tutorial using this file:
my-package-composition.yamltemplate: https://github.com/rwxd/cookiecutter-github-project\n---\ntemplate: https://github.com/kragniz/cookiecutter-pypackage-minimal\nWe didn\u2019t change the default for the project_slug, topics or open_source_license prompts. You don\u2019t have to change all the prompts or include all the prompts in the composition.
Then run:
$ cookie-composer create /path/to/my-package-composition.yaml\n\nfull_name [rwxd]: Demo User\nemail [rwxd@pm.me]: demo_user@example.com\ngithub_username [rwxd]: demo_user\nproject_name [Python Boilerplate]: Cookie Composer Demo\nproject_slug [composer_demo]:\nproject_short_description [Python Boilerplate contains all the boilerplate you need to create a Python package.]: Cookie Composer Demo\nhomepage [https://rwxd.github.io/composer_demo/]: https://demo_user.github.io/composer_demo/\nSelect project_type:\n1 - python\n2 - go\n3 - ansible\n4 - other\nChoose from 1, 2, 3, 4 [1]:\ntopics []:\nSelect open_source_license:\n1 - MIT license\n2 - BSD license\n3 - ISC license\n4 - Apache Software License 2.0\n5 - GNU General Public License v3\n6 - Not open source\nChoose from 1, 2, 3, 4, 5, 6 [1]:\nauthor_name [Louis Taylor]: Demo User\nauthor_email [louis@kragniz.eu]: demo_user@example.com\npackage_name [cookiecutter_pypackage_minimal]: composer_demo\npackage_version [0.1.0]:\npackage_description [An opinionated, minimal cookiecutter template for Python packages]: Cookie Composer Demo\npackage_url [https://github.com/kragniz/cookiecutter-pypackage-minimal]: https://github.com/demo_user/composer_demo\nreadme_pypi_badge [True]:\nreadme_travis_badge [True]:\nreadme_travis_url [https://travis-ci.org/kragniz/cookiecutter-pypackage-minimal]: https://travis-ci.org/demouser/composer_demo\nBoth layers are applied without requiring a git repository or multiple commands.
"},{"location":"tutorial/compositions/#providing-better-defaults","title":"Providing better defaults","text":"The composition can also improve the defaults for the template prompts by:
Let\u2019s start by changing some defaults to the first template. You can find the original prompt in this template\u2019s cookiecutter.json file.
my-package-composition.yamltemplate: https://github.com/rwxd/cookiecutter-github-project\ncontext:\n full_name: Your Name\n email: \"{{ cookiecutter.full_name.lower().replace(' ', '_') }}@example.com\"\n github_username: \"{{ cookiecutter.full_name.lower().replace(' ', '_') }}\"\n homepage: \"https://{{ cookiecutter.github_username }}.github.io/{{ cookiecutter.project_slug }}\"\n project_short_description: \"\"\n project_type: python\n---\ntemplate: https://github.com/kragniz/cookiecutter-pypackage-minimal\nThe new defaults provide better suggestions based on previous prompt answers.
"},{"location":"tutorial/compositions/#using-values-from-previous-templates","title":"Using values from previous templates","text":"The second template has several prompts that simply synonymns of promts from the previous template. It would be nice if we could use our answers from that template here.
Let\u2019s do that. You can find the original prompts in this template\u2019s cookiecutter.json file.
my-package-composition.yamltemplate: https://github.com/rwxd/cookiecutter-github-project\ncontext:\n full_name: Your Name\n email: \"{{ cookiecutter.full_name.lower().replace(' ', '_') }}@example.com\"\n github_username: \"{{ cookiecutter.full_name.lower().replace(' ', '_') }}\"\n homepage: \"https://{{ cookiecutter.github_username }}.github.io/{{ cookiecutter.project_slug }}\"\n project_short_description: \"\"\n project_type: python\n---\ntemplate: https://github.com/kragniz/cookiecutter-pypackage-minimal\ncontext:\n author_name: \"{{ cookiecutter.full_name }}\"\n author_email: \"{{ cookiecutter.email }}\"\n package_name: \"{{ cookiecutter.project_slug }}\"\n package_description: \"{{ cookiecutter.project_short_description }}\"\n package_url: \"https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}\"\n readme_travis_badge: false\n readme_travis_url: \"\"\nNow:
author_name defaults to full_name\u2019s valueauthor_email defaults to email\u2019s valuepackage_name defaults to project_slug\u2019s valuepackage_description defaults to project_short_description\u2019s valuepackage_url references both github_username\u2019s and project_slug\u2019s values$ cookie-composer create /path/to/tutorial-composition-3.yaml\n\nfull_name [Your Name]: Demo User\nemail [demo_user@example.com]:\ngithub_username [demo_user]:\nproject_name [Python Boilerplate]: Composer Demo\nproject_slug [composer_demo]:\nproject_short_description []: Cookie Composer Demo\nhomepage [https://demo_user.github.io/composer_demo]:\nSelect project_type:\n1 - python\n2 - go\n3 - ansible\n4 - other\nChoose from 1, 2, 3, 4 [1]:\ntopics []:\nSelect open_source_license:\n1 - MIT license\n2 - BSD license\n3 - ISC license\n4 - Apache Software License 2.0\n5 - GNU General Public License v3\n6 - Not open source\nChoose from 1, 2, 3, 4, 5, 6 [1]:\nauthor_name [Demo User]:\nauthor_email [demo_user@example.com]:\npackage_name [composer_demo]:\npackage_version [0.1.0]:\npackage_description [Cookie Composer Demo]:\npackage_url [https://github.com/demo_user/composer_demo]:\nreadme_pypi_badge [True]:\nreadme_travis_badge [False]:\nreadme_travis_url []:\nNotice how the better defaults allow less typing and more consistency.
"},{"location":"tutorial/incrementally-layering/","title":"Building a project layer by layer","text":""},{"location":"tutorial/incrementally-layering/#create-a-project-from-a-template","title":"Create a project from a template","text":"https://github.com/rwxd/cookiecutter-github-project
$ cookie-composer create https://github.com/rwxd/cookiecutter-github-project\nfull_name [rwxd]: Demo User\nemail [rwxd@pm.me]: demo_user@example.com\ngithub_username [rwxd]: demo_user\nproject_name [Python Boilerplate]: Composer Demo\nproject_slug [composer_demo]:\nproject_short_description [Python Boilerplate contains all the boilerplate you need to create a Python package.]: A Cookie Composer demo\nhomepage [https://rwxd.github.io/composer_demo/]: https://demo_user.github.io/composer_demo/\nSelect project_type:\n1 - python\n2 - go\n3 - ansible\n4 - other\nChoose from 1, 2, 3, 4 [1]:\ntopics []:\nSelect open_source_license:\n1 - MIT license\n2 - BSD license\n3 - ISC license\n4 - Apache Software License 2.0\n5 - GNU General Public License v3\n6 - Not open source\nChoose from 1, 2, 3, 4, 5, 6 [1]:\n$ cd composer_demo\n$ cookie-composer add https://github.com/kragniz/cookiecutter-pypackage-minimal\nUsage: cookie-composer add [OPTIONS] PATH_OR_URL [DESTINATION]\nTry 'cookie-composer add --help' for help.\n\u256d\u2500 Error \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Some cookie composer commands only work on git repositories. Please make the destination directory a \u2502\n\u2502 git repo. \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n$ git add -A\n$ git commit -m\"Initial commit\"\n[master (root-commit) 90a6a74] Initial commit\n 15 files changed, 352 insertions(+)\n create mode 100644 .composition.yaml\n create mode 100644 .github/ISSUE_TEMPLATE/bug_report_md\n create mode 100644 .github/ISSUE_TEMPLATE/config.yml\n create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md\n create mode 100644 .github/dependabot.yml\n create mode 100644 .github/settings.yml\n create mode 100644 .github/workflows/semantic-release.yml\n create mode 100644 .gitignore\n create mode 100644 .pre-commit-config.yaml\n create mode 100644 .releaserc.yml\n create mode 100644 LICENSE\n create mode 100644 Makefile\n create mode 100644 README.md\n create mode 100644 renovate.json\n create mode 100644 requirements-dev.txt\n ```\n\n```console\ncookie-composer add https://github.com/kragniz/cookiecutter-pypackage-minimal\nauthor_name [Louis Taylor]: Demo User\nauthor_email [louis@kragniz.eu]: demo_user@example.com\npackage_name [cookiecutter_pypackage_minimal]: composer_demo\npackage_version [0.1.0]:\npackage_description [An opinionated, minimal cookiecutter template for Python packages]: A Cookie Composer demo\npackage_url [https://github.com/kragniz/cookiecutter-pypackage-minimal]: https://github.com/demo_user/composer_demo\nreadme_pypi_badge [True]:\nreadme_travis_badge [True]: \nreadme_travis_url [https://travis-ci.org/kragniz/cookiecutter-pypackage-minimal]: https://travis-ci.org/demouser/composer_demo\nNow on branch add_layer_cookiecutter-pypackage-minimal
$ git status\nOn branch add_layer_cookiecutter-pypackage-minimal\nChanges not staged for commit:\n (use \"git add <file>...\" to update what will be committed)\n (use \"git restore <file>...\" to discard changes in working directory)\n modified: .composition.yaml\n\nUntracked files:\n (use \"git add <file>...\" to include in what will be committed)\n README.rst\n python_boilerplate/\n setup.py\n tests/\n tox.ini\nThe modified .composition.yaml file includes the new layer information.
Let\u2019s commit the new files
$ git add -A\n$ git commit -m\"Added layer cookiecutter-pypackage-minimal\"\n[add_layer_cookiecutter-pypackage-minimal dc62ba1] Added layer cookiecutter-pypackage-minimal\n 6 files changed, 115 insertions(+)\n create mode 100644 README.rst\n create mode 100644 python_boilerplate/__init__.py\n create mode 100644 setup.py\n create mode 100644 tests/test_sample.py\n create mode 100644 tox.ini\nNow the new branch is ready to merge.
$ git checkout master\n$ git merge add_layer_cookiecutter-pypackage-minimal\nUpdating aa3f701..dc62ba1\nFast-forward\n .composition.yaml | 24 ++++++++++++++++++++++++\n README.rst | 32 ++++++++++++++++++++++++++++++++\n python_boilerplate/__init__.py | 5 +++++\n setup.py | 44 ++++++++++++++++++++++++++++++++++++++++++++\n tests/test_sample.py | 4 ++++\n tox.ini | 6 ++++++\n 6 files changed, 115 insertions(+)\n create mode 100644 README.rst\n create mode 100644 python_boilerplate/__init__.py\n create mode 100644 setup.py\n create mode 100644 tests/test_sample.py\n create mode 100644 tox.ini\n$ git branch -d add_layer_cookiecutter-pypackage-minimal\nDeleted branch add_layer_cookiecutter-pypackage-minimal (was dc62ba1).\nCookie composer builds on the cookie cutter project to generate projects based on one or more cookiecutter templates.
"},{"location":"#goals","title":"Goals","text":"Cookie Cutter treats templates like sandwiches. There are templates for hamburgers, clubs, and any other kind of sandwich you can dream up. You might have options and defaults on a template, like Hold the mustard?[False]: or Mustard type [dijon]:, but those are decided by the template author.
If you look closely at the sandwiches (templates), there is usually many things in common. What if we treated the templates as compositions of other templates:
You now can manage several smaller and specialized templates that provide functionality. Each template\u2019s options will be specific to what that template needs.
Cookie Composer uses a composition file to describe the layers required, and even override a template\u2019s default answers.
template: bottom-bun\ncontext:\n toasting_level: light\n buttered: False\n---\ntemplate: burger\n---\ntemplate: cheese\ncontext:\n kind: swiss\n---\ntemplate: bacon\ncontext:\n cooking_level: crispy\n---\ntemplate: ketchup\n---\ntemplate: mustard\ncontext:\n type: yellow\n---\ntemplate: top-bun\ncontext:\n toasting_level: light\n buttered: False\nWe have created a repo of highly composable templates as examples or reference. However, Cookie Composer is designed to handle any Cookie Cutter template.
"},{"location":"#purpose","title":"Purpose","text":"Compare the full difference.
"},{"location":"changelog/#fixes","title":"Fixes","text":"Fixed parseurl with windows path. 9d14ae4
Was making the drive letter the scheme. - Fixed test PyPI upload. 7c59fc2
Fixed cookiecutter update incompatibilities. 9132c3c
Bump aiohttp from 3.9.2 to 3.9.4 in /requirements. 9eb6f0c
Bumps aiohttp from 3.9.2 to 3.9.4. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: aiohttp dependency-type: direct:production
signed-off-by: dependabot[bot] support@github.com
Bump idna from 3.4 to 3.7 in /requirements. 61297b5
Bumps idna from 3.4 to 3.7. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: idna dependency-type: direct:production
signed-off-by: dependabot[bot] support@github.com
Bump tqdm from 4.66.1 to 4.66.3 in /requirements. 94421a6
Bumps tqdm from 4.66.1 to 4.66.3. - Release notes - Commits
updated-dependencies: - dependency-name: tqdm dependency-type: direct:development
signed-off-by: dependabot[bot] support@github.com
Bump orjson from 3.9.9 to 3.9.15 in /requirements. ff8a8d6
Bumps orjson from 3.9.9 to 3.9.15. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: orjson dependency-type: direct:production
signed-off-by: dependabot[bot] support@github.com
[pre-commit.ci] pre-commit autoupdate. 8a67e75
updates: - github.com/astral-sh/ruff-pre-commit: v0.3.5 \u2192 v0.4.2
[pre-commit.ci] pre-commit autoupdate. e610733
updates: - github.com/astral-sh/ruff-pre-commit: v0.2.0 \u2192 v0.3.5
Compare the full difference.
"},{"location":"changelog/#fixes_1","title":"Fixes","text":"Fixed git worktree issue. e27636c
Fixed issue with determining rendered layer names. 06bad39
Added get_template_rendered_name to proactively determine the name of the rendered template. - Fixed resiliency issue with git template repos. a9bb80d
Provided better error checking for bad cached repos. - Fixed issue with relative paths in local files. 7f1b354
You can pass a local_path to use to resolve relative local paths for I/O and template determination. - Fixed data merge organization. 4bba0f4
[pre-commit.ci] pre-commit autoupdate. 86a2c04
updates: - github.com/astral-sh/ruff-pre-commit: v0.1.3 \u2192 v0.2.0
Bump gitpython from 3.1.40 to 3.1.41 in /requirements. 119c786
Bumps gitpython from 3.1.40 to 3.1.41. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: gitpython dependency-type: direct:production
signed-off-by: dependabot[bot] support@github.com
Bump jinja2 from 3.1.2 to 3.1.3 in /requirements. 100a239
Bumps jinja2 from 3.1.2 to 3.1.3. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: jinja2 dependency-type: direct:production
signed-off-by: dependabot[bot] support@github.com
Bump aiohttp from 3.8.6 to 3.9.2 in /requirements. 4b2a9df
Bumps aiohttp from 3.8.6 to 3.9.2. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: aiohttp dependency-type: direct:production
signed-off-by: dependabot[bot] support@github.com
get_context_for_layer from utils.py to composition.py. 6641a91get_template_name tests. 1c0c054[pre-commit.ci] pre-commit autoupdate. db151ef
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.287 \u2192 v0.0.290
[pre-commit.ci] pre-commit autoupdate. 7335d97
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.287 \u2192 v0.0.292
Bump urllib3 from 2.0.4 to 2.0.7 in /requirements. 6f5dd07
Bumps urllib3 from 2.0.4 to 2.0.7. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: urllib3 dependency-type: direct:production
signed-off-by: dependabot[bot] support@github.com
[pre-commit.ci] pre-commit autoupdate. 94b1833
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.287 \u2192 v0.1.3
[pre-commit.ci] pre-commit autoupdate. bc33fbd
updates: - https://github.com/charliermarsh/ruff-pre-commit \u2192 https://github.com/astral-sh/ruff-pre-commit
zipfile_repo.unzip to cache_source. 60a2393io module. 3c64a3eRefactored layers. e8af7d5
Template with LayerConfig - template attribute is now a Template instance - removed directory, checkout, password, and commit - renamed context to initial_context to distiguish it from the Template\u2019s contextRenderedLayer to use templates - renamed new_context to rendered_context to better describe it. - renamed latest_commit to rendered_commit for better clarity - added latest_commit convenience functionrender_layer using the new template functionsIt is now part of the template repo - Updated requirements to use Pydantic 2. b24a158
Compare the full difference.
"},{"location":"changelog/#fixes_2","title":"Fixes","text":"Added -o and --output-dir as an alias. 04f063d
It is now an alias for -d and --destination
Revert \u201c[pre-commit.ci] auto fixes from pre-commit.com hooks\u201d. 42d8704
This reverts commit 52772f1352d6130b2d6189bf632b26fb9732c13f. - [pre-commit.ci] auto fixes from pre-commit.com hooks. 52772f1
for more information, see https://pre-commit.ci - Migrated from setup.cfg to pyproject.toml. b3a39f0
Bump aiohttp from 3.8.3 to 3.8.5 in /requirements. 0392ef7
Bumps aiohttp from 3.8.3 to 3.8.5. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: aiohttp dependency-type: direct:production
signed-off-by: dependabot[bot] support@github.com
[pre-commit.ci] pre-commit autoupdate. 83d1217
updates: - github.com/psf/black: 23.3.0 \u2192 23.7.0
[pre-commit.ci] pre-commit autoupdate. c58fe42
updates: - github.com/psf/black: 23.3.0 \u2192 23.7.0
Compare the full difference.
"},{"location":"changelog/#new_2","title":"New","text":"Compare the full difference.
"},{"location":"changelog/#fixes_3","title":"Fixes","text":"Compare the full difference.
"},{"location":"changelog/#fixes_4","title":"Fixes","text":"Bump markdown-it-py from 2.1.0 to 2.2.0 in /requirements. 65a4863
Bumps markdown-it-py from 2.1.0 to 2.2.0. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: markdown-it-py dependency-type: indirect
signed-off-by: dependabot[bot] support@github.com
[pre-commit.ci] pre-commit autoupdate. 21eca93
updates: - github.com/psf/black: 23.1.0 \u2192 23.3.0
Compare the full difference.
"},{"location":"changelog/#new_3","title":"New","text":"Added relative directory support for compositions. 02fa5b8
., .., and relative paths (non-/ prefixed) are resolved with urllib.parse.urljoinCompare the full difference.
"},{"location":"changelog/#new_4","title":"New","text":"Modified CLI options and arguments. 02a4bf3
output_dir argument was moved to the --destination option.CONTEXT_PARAMS argument for initial contextCompare the full difference.
"},{"location":"changelog/#new_5","title":"New","text":"--version option. 4b1b9e1Compare the full difference.
"},{"location":"changelog/#fixes_5","title":"Fixes","text":"[pre-commit.ci] pre-commit autoupdate. 1f5320a
updates: - github.com/pycqa/pydocstyle: 6.1.1 \u2192 6.2.3
Compare the full difference.
"},{"location":"changelog/#fixes_6","title":"Fixes","text":"Bump wheel from 0.37.1 to 0.38.1 in /requirements. cab9b8e
Bumps wheel from 0.37.1 to 0.38.1. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: wheel dependency-type: indirect
signed-off-by: dependabot[bot] support@github.com
[pre-commit.ci] pre-commit autoupdate. 45e8596
updates: - github.com/PyCQA/isort: v5.11.3 \u2192 5.11.4
[pre-commit.ci] pre-commit autoupdate. 550e0cb
updates: - github.com/PyCQA/isort: 5.10.1 \u2192 v5.11.3
Compare the full difference.
"},{"location":"changelog/#fixes_7","title":"Fixes","text":"[pre-commit.ci] pre-commit autoupdate. 5b21a40
updates: - github.com/psf/black: 22.10.0 \u2192 22.12.0
[pre-commit.ci] pre-commit autoupdate. 0f5c7a5
updates: - github.com/pre-commit/pre-commit-hooks: v4.3.0 \u2192 v4.4.0
Changed JSON library to orjson. c857a2f
Compare the full difference.
"},{"location":"changelog/#fixes_8","title":"Fixes","text":"Compare the full difference.
"},{"location":"changelog/#new_7","title":"New","text":"[pre-commit.ci] pre-commit autoupdate. a31eeef
updates: - github.com/psf/black: 22.8.0 \u2192 22.10.0
Compare the full difference.
"},{"location":"changelog/#fixes_9","title":"Fixes","text":"git diff and git apply. d4bc14fCompare the full difference.
"},{"location":"changelog/#new_9","title":"New","text":"Added the update subcommand. 6696589
[pre-commit.ci] auto fixes from pre-commit.com hooks. e5425d5
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. dbfde0a
updates: - github.com/psf/black: 22.6.0 \u2192 22.8.0
Compare the full difference.
"},{"location":"changelog/#new_10","title":"New","text":"[pre-commit.ci] pre-commit autoupdate. e516a18
updates: - github.com/PyCQA/flake8: 4.0.1 \u2192 5.0.4
[pre-commit.ci] pre-commit autoupdate. 3e6f695
updates: - github.com/psf/black: 22.3.0 \u2192 22.6.0
Compare the full difference.
"},{"location":"changelog/#fixes_10","title":"Fixes","text":"Compare the full difference.
"},{"location":"changelog/#new_11","title":"New","text":"Compare the full difference.
"},{"location":"changelog/#fixes_11","title":"Fixes","text":"Compare the full difference.
"},{"location":"changelog/#fixes_12","title":"Fixes","text":"Fixed add command requiring destination. 15cbd16
The destination of the add command is now optional and defaults to the current working directory. - Fixed error not writing commit to composition file. 8fd7bbe
Fixed a bug when two templates have _copy_without_render. 9e89347
_copy_without_render is template-specific and attempting to override it raises an error in cookiecutter. Now that key is deleted for the default context and full context when generating each layer. - Fixed configurations. df365df
Added git commands. 291b9aa
This allows for detection of multiple rendered directories, and proper writing of the composition file. - Added release tooling. d0646d3
[pre-commit.ci] auto fixes from pre-commit.com hooks. 2dae846
for more information, see https://pre-commit.ci - Excluding test fixtures from requirement fixing. 40293a9
[pre-commit.ci] auto fixes from pre-commit.com hooks. b774ad1
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. 5098fde
updates: - github.com/pre-commit/pre-commit-hooks: v4.2.0 \u2192 v4.3.0
[pre-commit.ci] auto fixes from pre-commit.com hooks. 63f2d7d
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. 8f6d661
updates: - https://github.com/timothycrosley/isort \u2192 https://github.com/PyCQA/isort
Changed dependency management. 4cf52ba
Uses pip-tools to compile and maintain dependency information. - Updated tests. 7c81df5
Compare the full difference.
"},{"location":"changelog/#other_12","title":"Other","text":"Compare the full difference.
"},{"location":"changelog/#fixes_13","title":"Fixes","text":"Fixed git worktree issue. e27636c
Fixed issue with determining rendered layer names. 06bad39
Added get_template_rendered_name to proactively determine the name of the rendered template. - Fixed resiliency issue with git template repos. a9bb80d
Provided better error checking for bad cached repos. - Fixed issue with relative paths in local files. 7f1b354
You can pass a local_path to use to resolve relative local paths for I/O and template determination. - Fixed data merge organization. 4bba0f4
get_context_for_layer from utils.py to composition.py. 6641a91get_template_name tests. 1c0c054[pre-commit.ci] pre-commit autoupdate. db151ef
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.287 \u2192 v0.0.290
[pre-commit.ci] pre-commit autoupdate. 7335d97
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.287 \u2192 v0.0.292
Bump urllib3 from 2.0.4 to 2.0.7 in /requirements. 6f5dd07
Bumps urllib3 from 2.0.4 to 2.0.7. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: urllib3 dependency-type: direct:production
signed-off-by: dependabot[bot] support@github.com
[pre-commit.ci] pre-commit autoupdate. 94b1833
updates: - github.com/astral-sh/ruff-pre-commit: v0.0.287 \u2192 v0.1.3
[pre-commit.ci] pre-commit autoupdate. bc33fbd
updates: - https://github.com/charliermarsh/ruff-pre-commit \u2192 https://github.com/astral-sh/ruff-pre-commit
zipfile_repo.unzip to cache_source. 60a2393io module. 3c64a3eRefactored layers. e8af7d5
Template with LayerConfig - template attribute is now a Template instance - removed directory, checkout, password, and commit - renamed context to initial_context to distiguish it from the Template\u2019s contextRenderedLayer to use templates - renamed new_context to rendered_context to better describe it. - renamed latest_commit to rendered_commit for better clarity - added latest_commit convenience functionrender_layer using the new template functionsIt is now part of the template repo - Updated requirements to use Pydantic 2. b24a158
Compare the full difference.
"},{"location":"changelog/#fixes_14","title":"Fixes","text":"Added -o and --output-dir as an alias. 04f063d
It is now an alias for -d and --destination
Revert \u201c[pre-commit.ci] auto fixes from pre-commit.com hooks\u201d. 42d8704
This reverts commit 52772f1352d6130b2d6189bf632b26fb9732c13f. - [pre-commit.ci] auto fixes from pre-commit.com hooks. 52772f1
for more information, see https://pre-commit.ci - Migrated from setup.cfg to pyproject.toml. b3a39f0
Bump aiohttp from 3.8.3 to 3.8.5 in /requirements. 0392ef7
Bumps aiohttp from 3.8.3 to 3.8.5. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: aiohttp dependency-type: direct:production
signed-off-by: dependabot[bot] support@github.com
[pre-commit.ci] pre-commit autoupdate. 83d1217
updates: - github.com/psf/black: 23.3.0 \u2192 23.7.0
[pre-commit.ci] pre-commit autoupdate. c58fe42
updates: - github.com/psf/black: 23.3.0 \u2192 23.7.0
Compare the full difference.
"},{"location":"changelog/#new_15","title":"New","text":"Compare the full difference.
"},{"location":"changelog/#fixes_15","title":"Fixes","text":"Compare the full difference.
"},{"location":"changelog/#fixes_16","title":"Fixes","text":"Bump markdown-it-py from 2.1.0 to 2.2.0 in /requirements. 65a4863
Bumps markdown-it-py from 2.1.0 to 2.2.0. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: markdown-it-py dependency-type: indirect
signed-off-by: dependabot[bot] support@github.com
[pre-commit.ci] pre-commit autoupdate. 21eca93
updates: - github.com/psf/black: 23.1.0 \u2192 23.3.0
Compare the full difference.
"},{"location":"changelog/#new_16","title":"New","text":"Added relative directory support for compositions. 02fa5b8
., .., and relative paths (non-/ prefixed) are resolved with urllib.parse.urljoinCompare the full difference.
"},{"location":"changelog/#new_17","title":"New","text":"Modified CLI options and arguments. 02a4bf3
output_dir argument was moved to the --destination option.CONTEXT_PARAMS argument for initial contextCompare the full difference.
"},{"location":"changelog/#new_18","title":"New","text":"--version option. 4b1b9e1Compare the full difference.
"},{"location":"changelog/#fixes_17","title":"Fixes","text":"[pre-commit.ci] pre-commit autoupdate. 1f5320a
updates: - github.com/pycqa/pydocstyle: 6.1.1 \u2192 6.2.3
Compare the full difference.
"},{"location":"changelog/#fixes_18","title":"Fixes","text":"Bump wheel from 0.37.1 to 0.38.1 in /requirements. cab9b8e
Bumps wheel from 0.37.1 to 0.38.1. - Release notes - Changelog - Commits
updated-dependencies: - dependency-name: wheel dependency-type: indirect
signed-off-by: dependabot[bot] support@github.com
[pre-commit.ci] pre-commit autoupdate. 45e8596
updates: - github.com/PyCQA/isort: v5.11.3 \u2192 5.11.4
[pre-commit.ci] pre-commit autoupdate. 550e0cb
updates: - github.com/PyCQA/isort: 5.10.1 \u2192 v5.11.3
Compare the full difference.
"},{"location":"changelog/#fixes_19","title":"Fixes","text":"[pre-commit.ci] pre-commit autoupdate. 5b21a40
updates: - github.com/psf/black: 22.10.0 \u2192 22.12.0
[pre-commit.ci] pre-commit autoupdate. 0f5c7a5
updates: - github.com/pre-commit/pre-commit-hooks: v4.3.0 \u2192 v4.4.0
Changed JSON library to orjson. c857a2f
Compare the full difference.
"},{"location":"changelog/#fixes_20","title":"Fixes","text":"Compare the full difference.
"},{"location":"changelog/#new_20","title":"New","text":"[pre-commit.ci] pre-commit autoupdate. a31eeef
updates: - github.com/psf/black: 22.8.0 \u2192 22.10.0
Compare the full difference.
"},{"location":"changelog/#fixes_21","title":"Fixes","text":"git diff and git apply. d4bc14fCompare the full difference.
"},{"location":"changelog/#new_22","title":"New","text":"Added the update subcommand. 6696589
[pre-commit.ci] auto fixes from pre-commit.com hooks. e5425d5
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. dbfde0a
updates: - github.com/psf/black: 22.6.0 \u2192 22.8.0
Compare the full difference.
"},{"location":"changelog/#new_23","title":"New","text":"[pre-commit.ci] pre-commit autoupdate. e516a18
updates: - github.com/PyCQA/flake8: 4.0.1 \u2192 5.0.4
[pre-commit.ci] pre-commit autoupdate. 3e6f695
updates: - github.com/psf/black: 22.3.0 \u2192 22.6.0
Compare the full difference.
"},{"location":"changelog/#fixes_22","title":"Fixes","text":"Compare the full difference.
"},{"location":"changelog/#new_24","title":"New","text":"Compare the full difference.
"},{"location":"changelog/#fixes_23","title":"Fixes","text":"Compare the full difference.
"},{"location":"changelog/#fixes_24","title":"Fixes","text":"Fixed add command requiring destination. 15cbd16
The destination of the add command is now optional and defaults to the current working directory. - Fixed error not writing commit to composition file. 8fd7bbe
Fixed a bug when two templates have _copy_without_render. 9e89347
_copy_without_render is template-specific and attempting to override it raises an error in cookiecutter. Now that key is deleted for the default context and full context when generating each layer. - Fixed configurations. df365df
Added git commands. 291b9aa
This allows for detection of multiple rendered directories, and proper writing of the composition file. - Added release tooling. d0646d3
[pre-commit.ci] auto fixes from pre-commit.com hooks. 2dae846
for more information, see https://pre-commit.ci - Excluding test fixtures from requirement fixing. 40293a9
[pre-commit.ci] auto fixes from pre-commit.com hooks. b774ad1
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. 5098fde
updates: - github.com/pre-commit/pre-commit-hooks: v4.2.0 \u2192 v4.3.0
[pre-commit.ci] auto fixes from pre-commit.com hooks. 63f2d7d
for more information, see https://pre-commit.ci - [pre-commit.ci] pre-commit autoupdate. 8f6d661
updates: - https://github.com/timothycrosley/isort \u2192 https://github.com/PyCQA/isort
Changed dependency management. 4cf52ba
Uses pip-tools to compile and maintain dependency information. - Updated tests. 7c81df5
There are several ways to create your isolated environment. This is the default method.
Run the following in a terminal:
# Clone the repository\ngit clone https://github.com/coordt/cookie-composer.git\n\n# Enter the repository\ncd cookie-composer\n\n# Create then activate a virtual environment\npython -m venv venv\nsource venv/bin/activate\n\n# Install the development requirements\npython -m pip install -r requirements/dev.txt\nOnce setup, you should be able to run tests:
pytest\nPre-commit hooks are scripts that run every time you make a commit. If any of the scripts fail, it stops the commit. You can see a listing of the checks in the .pre-commit-config.yaml file.
pre-commit install\nThis is the recommended method for installing cookie composer because it works on all platforms and should require minimal effort.\npipx is a tool to help you install and run end-user applications written in Python. It\u2019s roughly similar to macOS\u2019s brew, JavaScript\u2019s npx, and Linux\u2019s apt. pipx installs the application in an isolated Python environment yet still makes the app available in your shell.
The full instructions for installing pipx are on its website.
With pipx installed, install cookie-composer by running:
$ pipx install cookie-composer\nThe cookie-composer command is available in your shell as any other command.
Installing cookie composer into a Python virtual environment, also known as a virtualenv or venv, means the command is only available while that environment is active.\nThe instructions assume you already have Python installed.\nThe full documentation on creating virtual environments gives a greater set of instructions. It will be something like running:
$ python3 -m venv /path/to/new/virtual/environment\nThe method of activating the environment depends on the shell and are listed in the documentation. For bash or zsh it is:
$ source </path/to/new/virtual/environment>/bin/activate\nOnce the virtual environment is activate, use pip to install cookie-composer:
$ python3 -m pip install cookie-composer\nCookie composer can integrate with some third-party services in order to access private repositories.
Note
Currently only GitHub is supported.
"},{"location":"how-to/access-private-templates/#github","title":"GitHub","text":"At your terminal, enter cookie-composer auth login:
$ cookie-composer auth login\nFirst copy your one-time code: A25E-0A58\nThen visit https://github.com/login/device in your browser, and paste the code when prompted.\nPress Enter to open github.com in your browser...\nCopy the one-time code (A25E-0A58 in this example), and press Enter or Return to open your browser to the correct page.
You will arrive at a page similar to this:
Paste the code (or enter each character individually) and press the continue button.
You will see an authorization page, similar to:
Press the \u201cAuthorize callowayproject\u201d button to allow cookie-composer read-only access to your repositories.
Then you will see:
And you can close the browser window.
Your terminal will now look like:
$ cookie-composer auth login\nFirst copy your one-time code: A25E-0A58\nThen visit https://github.com/login/device in your browser, and paste the code when prompted.\nPress Enter to open github.com in your browser...\nWaiting for authorization.............Authenticated to GitHub\nNow when you provide any GitHub template link, Cookie Composer is able to access them as you with read-only access.
"},{"location":"reference/cli/","title":"cookie-composer","text":"Render templates using composition.
Usage:
cookie-composer [OPTIONS] COMMAND [ARGS]...\nOptions:
Name Type Description Default--version boolean Show the version and exit. False --help boolean Show this message and exit. False Subcommands
Add the template or configuration PATH_OR_URL to an existing project.
Usage:
cookie-composer add [OPTIONS] PATH_OR_URL [CONTEXT_PARAMS]...\nOptions:
Name Type Description Default--verbosity, -v text Either CRITICAL, ERROR, WARNING, INFO or DEBUG INFO --no-input boolean Do not prompt for parameters and only use cookiecutter.json file content. Defaults to deleting any cached resources and redownloading them. False -c, --checkout text branch, tag or commit to checkout after git clone None --directory text Directory within repo that holds cookiecutter.json file for advanced repositories with multi templates in it None -f, --overwrite-if-exists boolean Overwrite the contents of the output directory if it already exists False -s, --skip-if-file-exists boolean Skip the files in the corresponding directories if they already exist False --default-config boolean Do not load a config file. Use the defaults instead False -d, --destination directory The directory to add the templates to. Defaults to the current working directory. <function <lambda> at 0x7f0e92634550> --accept-hooks choice (yes | ask | no | first | last | all | none) Accept pre/host hooks all --help boolean Show this message and exit. False"},{"location":"reference/cli/#cookie-composer-auth","title":"cookie-composer auth","text":"Authenticate cookie-composer to a service.
Usage:
cookie-composer auth [OPTIONS] COMMAND [ARGS]...\nOptions:
Name Type Description Default--help boolean Show this message and exit. False Subcommands
Authenticate to a service.
Usage:
cookie-composer auth login [OPTIONS]\nOptions:
Name Type Description Default-p, --git-protocol choice (https | ssh) The protocol to use for git operations https -h, --service text The host name of the service to authenticate with github.com -s, --scopes text Additional authentication scopes to request None --with-token filename Read token from standard input None --help boolean Show this message and exit. False"},{"location":"reference/cli/#cookie-composer-auth-token","title":"cookie-composer auth token","text":"Print the auth token cookie-composer is configured to use.
Usage:
cookie-composer auth token [OPTIONS]\nOptions:
Name Type Description Default-h, --service text The host name of the service to authenticate with github.com --help boolean Show this message and exit. False"},{"location":"reference/cli/#cookie-composer-create","title":"cookie-composer create","text":"Create a project from the template or configuration PATH_OR_URL in using optional [CONTEXT_PARAMS].
Usage:
cookie-composer create [OPTIONS] PATH_OR_URL [CONTEXT_PARAMS]...\nOptions:
Name Type Description Default--verbosity, -v text Either CRITICAL, ERROR, WARNING, INFO or DEBUG INFO --no-input boolean Do not prompt for parameters and only use cookiecutter.json file content. Defaults to deleting any cached resources and redownloading them. False -c, --checkout text branch, tag or commit to checkout after git clone None --directory text Directory within repo that holds cookiecutter.json file for advanced repositories with multi templates in it None -f, --overwrite-if-exists boolean Overwrite the contents of the output directory if it already exists False -s, --skip-if-file-exists boolean Skip the files in the corresponding directories if they already exist False --default-config boolean Do not load a config file. Use the defaults instead False -d, --destination, -o, --output-dir directory The directory to render the templates to. Defaults to the current working directory. <function <lambda> at 0x7f0e92634430> --accept-hooks choice (yes | ask | no | first | last | all | none) Accept pre/host hooks all --help boolean Show this message and exit. False"},{"location":"reference/cli/#cookie-composer-link","title":"cookie-composer link","text":"Link an existing git repo to the template or composition PATH_OR_URL using optional [CONTEXT_PARAMS].
Usage:
cookie-composer link [OPTIONS] PATH_OR_URL [CONTEXT_PARAMS]...\nOptions:
Name Type Description Default--no-input boolean Do not prompt for parameters and only use cookiecutter.json file content. Defaults to deleting any cached resources and redownloading them. False -c, --checkout text branch, tag or commit to checkout after git clone None --directory text Directory within repo that holds cookiecutter.json file for advanced repositories with multi templates in it None -f, --overwrite-if-exists boolean Overwrite the contents of the output directory if it already exists False -s, --skip-if-file-exists boolean Skip the files in the corresponding directories if they already exist False --default-config boolean Do not load a config file. Use the defaults instead False -d, --destination directory The directory to link the template to. Defaults to the current working directory. <function <lambda> at 0x7f0e92634790> --help boolean Show this message and exit. False"},{"location":"reference/cli/#cookie-composer-update","title":"cookie-composer update","text":"Update the project to the latest version of each template.
Usage:
cookie-composer update [OPTIONS] [CONTEXT_PARAMS]...\nOptions:
Name Type Description Default--no-input boolean Do not prompt for parameters and only use cookiecutter.json file content. Defaults to deleting any cached resources and re-downloading them. False -d, --destination directory The directory to update. Defaults to the current working directory. <function <lambda> at 0x7f0e926341f0> --help boolean Show this message and exit. False"},{"location":"reference/api/SUMMARY/","title":"SUMMARY","text":"OAuth2 authentication to access protected resources.
"},{"location":"reference/api/cookie_composer/authentication/#cookie_composer.authentication-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/authentication/#cookie_composer.authentication.add_auth_to_url","title":"add_auth_to_url","text":"add_auth_to_url(url: str) -> str\nAdd authentication information to a URL.
Parameters:
url The URL to add authentication information to.
TYPE: str
Returns:
str The URL with authentication information added, or the original URL if no token is cached
"},{"location":"reference/api/cookie_composer/authentication/#cookie_composer.authentication.get_cached_token","title":"get_cached_token","text":"get_cached_token(account_name: str) -> Optional[str]\nReturn the cached token for the account.
"},{"location":"reference/api/cookie_composer/authentication/#cookie_composer.authentication.get_hosts_file","title":"get_hosts_file","text":"get_hosts_file() -> Path\nReturn the path to the hosts file.
"},{"location":"reference/api/cookie_composer/authentication/#cookie_composer.authentication.github_auth_device","title":"github_auth_device","text":"github_auth_device(n_polls: int = 9999) -> Optional[str]\nAuthenticate with GitHub, polling up to n_polls times to wait for completion.
login_to_svc(\n service: Optional[str] = None,\n protocol: Optional[str] = None,\n scopes: Optional[str] = None,\n token: Optional[str] = None,\n) -> str\nLog in and cache token.
Parameters:
service The name of the service to authenticate with
TYPE: Optional[str]
DEFAULT: None
protocol The protocol to use for git operations
TYPE: Optional[str]
DEFAULT: None
scopes Additional authentication scopes to request
TYPE: Optional[str]
DEFAULT: None
token A specific token to use instead of logging in
TYPE: Optional[str]
DEFAULT: None
Returns:
str The token for the service
"},{"location":"reference/api/cookie_composer/cc_overrides/","title":"This overrides the default cookie cutter environment.
"},{"location":"reference/api/cookie_composer/cc_overrides/#cookie_composer.cc_overrides-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/cc_overrides/#cookie_composer.cc_overrides.CustomStrictEnvironment","title":"CustomStrictEnvironment","text":"CustomStrictEnvironment(**kwargs)\n Bases: StrictEnvironment
Create strict Jinja2 environment.
Jinja2 environment will raise error on undefined variable in template-rendering context.
Does not expect all the context to be under the cookiecutter key.
JsonifyContextExtension(environment: Environment)\n Bases: Extension
Jinja2 extension to convert a Python object to JSON.
"},{"location":"reference/api/cookie_composer/cc_overrides/#cookie_composer.cc_overrides-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/cc_overrides/#cookie_composer.cc_overrides.jsonify_context","title":"jsonify_context","text":"jsonify_context(value: Any) -> MutableMapping\nConvert a Context to a dict.
prompt_for_config(\n prompts: dict,\n aggregated_context: Context,\n layer_context: Optional[\n MutableMapping[str, Any]\n ] = None,\n no_input: bool = False,\n) -> MutableMapping[str, Any]\nPrompt user to enter a new config using an existing config as a basis.
Will not prompt for configurations already in the existing configuration.
Prompts can refer to items in the existing config.
Parameters:
prompts A dictionary of configuration prompts and default values
TYPE: dict
aggregated_context An existing configuration to use as a basis
TYPE: Context
layer_context A dictionary of defaults defined in the layer
TYPE: Optional[MutableMapping[str, Any]]
DEFAULT: None
no_input If True Don\u2019t prompt the user at command line for manual configuration
TYPE: bool
DEFAULT: False
Returns:
MutableMapping[str, Any] A new configuration context
"},{"location":"reference/api/cookie_composer/cc_overrides/#cookie_composer.cc_overrides.update_extensions","title":"update_extensions","text":"update_extensions(\n existing_config: MutableMapping[str, Any],\n prompts: MutableMapping[str, Any],\n) -> List[str]\nMerge extensions from prompts into existing config.
"},{"location":"reference/api/cookie_composer/cli/","title":"Command line setup.
"},{"location":"reference/api/cookie_composer/cli/#cookie_composer.cli-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/cli/#cookie_composer.cli-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/cli/#cookie_composer.cli.add","title":"add","text":"add(\n no_input: bool,\n checkout: str,\n directory: str,\n overwrite_if_exists: bool,\n skip_if_file_exists: bool,\n default_config: bool,\n destination: Path,\n accept_hooks: str,\n path_or_url: str,\n context_params: Optional[\n MutableMapping[str, Any]\n ] = None,\n) -> None\nAdd the template or configuration PATH_OR_URL to an existing project.
"},{"location":"reference/api/cookie_composer/cli/#cookie_composer.cli.cli","title":"cli","text":"cli() -> None\nRender templates using composition.
"},{"location":"reference/api/cookie_composer/cli/#cookie_composer.cli.create","title":"create","text":"create(\n no_input: bool,\n checkout: str,\n directory: str,\n overwrite_if_exists: bool,\n skip_if_file_exists: bool,\n default_config: bool,\n destination: Path,\n accept_hooks: str,\n path_or_url: str,\n context_params: Optional[\n MutableMapping[str, Any]\n ] = None,\n) -> None\nCreate a project from the template or configuration PATH_OR_URL in using optional [CONTEXT_PARAMS].
"},{"location":"reference/api/cookie_composer/cli/#cookie_composer.cli.link","title":"link","text":"link(\n no_input: bool,\n checkout: str,\n directory: str,\n overwrite_if_exists: bool,\n skip_if_file_exists: bool,\n default_config: bool,\n destination: Optional[Path],\n path_or_url: str,\n context_params: Optional[\n MutableMapping[str, Any]\n ] = None,\n) -> None\nLink an existing git repo to the template or composition PATH_OR_URL using optional [CONTEXT_PARAMS].
"},{"location":"reference/api/cookie_composer/cli/#cookie_composer.cli.update","title":"update","text":"update(\n no_input: bool,\n destination: Path,\n context_params: Optional[OrderedDict] = None,\n) -> None\nUpdate the project to the latest version of each template.
"},{"location":"reference/api/cookie_composer/cli/#cookie_composer.cli.validate_context_params","title":"validate_context_params","text":"validate_context_params(\n ctx: Any, param: Any, value: list\n) -> Optional[OrderedDict]\nValidate context parameters.
Convert a tuple to a dict
e.g.: ('program_name=foobar', 'startsecs=66') -> {'program_name': 'foobar', 'startsecs': '66'}
Parameters:
ctx Click context (unused)
TYPE: Any
param Click parameter (unused)
TYPE: Any
value Click parameter value
TYPE: list
Returns:
Optional[OrderedDict] An ordered dict of the parameter values or None if no parameters.
Raises:
BadParameter If the parameters are not key=value.
Project configuration and options.
"},{"location":"reference/api/cookie_composer/composition/#cookie_composer.composition-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/composition/#cookie_composer.composition.Composition","title":"Composition","text":" Bases: BaseModel
Composition of templates for a project.
"},{"location":"reference/api/cookie_composer/composition/#cookie_composer.composition.RenderedComposition","title":"RenderedComposition","text":" Bases: BaseModel
A rendered composition of templates for a project.
"},{"location":"reference/api/cookie_composer/composition/#cookie_composer.composition.RenderedComposition-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/composition/#cookie_composer.composition.RenderedComposition.layer_names","title":"layer_namesproperty","text":"layer_names: List[str]\nReturn a list of the names of all the layers.
"},{"location":"reference/api/cookie_composer/composition/#cookie_composer.composition.RenderedComposition.layers","title":"layersinstance-attribute","text":"layers: List[RenderedLayer]\nRendered layers.
"},{"location":"reference/api/cookie_composer/composition/#cookie_composer.composition.RenderedComposition.render_dir","title":"render_dirinstance-attribute","text":"render_dir: DirectoryPath\nThe directory in which the layers were rendered.
The render_dir + rendered_name is the location of the project.
instance-attribute","text":"rendered_name: str\nThe name of the rendered project.
"},{"location":"reference/api/cookie_composer/composition/#cookie_composer.composition-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/composition/#cookie_composer.composition.get_context_for_layer","title":"get_context_for_layer","text":"get_context_for_layer(\n composition: RenderedComposition,\n index: Optional[int] = None,\n) -> dict\nMerge the contexts for all layers up to index.
An index of None does all the layers.
Parameters:
composition The rendered composition
TYPE: RenderedComposition
index Merge the contexts of the layers up to this 0-based index. None to do all layers.
TYPE: Optional[int]
DEFAULT: None
Returns:
dict The comprehensively merged context
"},{"location":"reference/api/cookie_composer/data_merge/","title":"Tools for merging data.
"},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge.COMPREHENSIVE","title":"COMPREHENSIVEmodule-attribute","text":"COMPREHENSIVE = 'comprehensive'\nComprehensively merge the two data structures.
module-attribute","text":"DO_NOT_MERGE = 'do-not-merge'\nDo not merge the data, use the file path to determine what to do.
"},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge.NESTED_OVERWRITE","title":"NESTED_OVERWRITEmodule-attribute","text":"NESTED_OVERWRITE = 'nested-overwrite'\nMerge deeply nested structures and overwrite at the lowest level; A deep dict.update().
module-attribute","text":"OVERWRITE = 'overwrite'\nOverwrite at the top level like dict.update().
Bases: ChainMap
Provides merging and convenience functions for managing contexts.
"},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge.Context-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge.Context.is_empty","title":"is_emptyproperty","text":"is_empty: bool\nThe context has only one mapping and it is empty.
"},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge.Context-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge.Context.flatten","title":"flatten","text":"flatten() -> MutableMapping\nComprehensively merge all the maps into a single mapping.
"},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge.comprehensive_merge","title":"comprehensive_merge","text":"comprehensive_merge(*args: MutableMapping) -> Any\nMerges data comprehensively.
All arguments must be of the same type.
Parameters:
*args List of dicts to merge with the first one the base
TYPE: MutableMapping
DEFAULT: ()
Returns:
Any The merged data
"},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge.deep_merge","title":"deep_merge","text":"deep_merge(*dicts: dict) -> dict\nMerges dicts deeply.
Parameters:
*dicts List of dicts to merge with the first one as the base
TYPE: dict
DEFAULT: ()
Returns:
dict The merged dict
TYPE: dict
freeze_data(obj: Any) -> Any\nCheck type and recursively return a new read-only object.
"},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge.get_merge_strategy","title":"get_merge_strategy","text":"get_merge_strategy(\n path: Path, merge_strategies: Dict[str, str]\n) -> str\nReturn the merge strategy of the path based on the layer configured rules.
Files that are not mergable return DO_NOT_MERGE.
Parameters:
path The file path to evaluate.
TYPE: Path
merge_strategies The glob pattern->strategy mapping
TYPE: Dict[str, str]
Returns:
str The appropriate merge strategy.
"},{"location":"reference/api/cookie_composer/data_merge/#cookie_composer.data_merge.merge_iterables","title":"merge_iterables","text":"merge_iterables(iter1: Iterable, iter2: Iterable) -> set\nMerge and de-duplicate a bunch of lists into a single list.
Order is not guaranteed.
Parameters:
iter1 An Iterable
TYPE: Iterable
iter2 An Iterable
TYPE: Iterable
Returns:
set The merged, de-duplicated sequence as a set
"},{"location":"reference/api/cookie_composer/diff/","title":"Generating the difference between two directories.
Nabbed from Cruft: https://github.com/cruft/cruft/
"},{"location":"reference/api/cookie_composer/diff/#cookie_composer.diff-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/diff/#cookie_composer.diff-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/diff/#cookie_composer.diff.display_diff","title":"display_diff","text":"display_diff(repo0: Path, repo1: Path) -> None\nDisplays the diff between two repositories.
"},{"location":"reference/api/cookie_composer/diff/#cookie_composer.diff.get_diff","title":"get_diff","text":"get_diff(repo0: Path, repo1: Path) -> str\nCompute the raw diff between two repositories.
"},{"location":"reference/api/cookie_composer/diff/#cookie_composer.diff.replace_diff_prefixes","title":"replace_diff_prefixes","text":"replace_diff_prefixes(\n diff: str, repo0_path: str, repo1_path: str\n) -> str\nReplace the changed file prefixes in the diff output.
Our git diff --no-index command will output full paths like so::
--- upstream-template-old/tmp/tmpmp34g21y/remote/.coveragerc\n+++ upstream-template-new/tmp/tmpmp34g21y/local/.coveragerc\nThis isn\u2019t the format we need in order to apply the diff later on. The result of this command will change the paths to::
--- upstream-template-old/.coveragerc\n+++ upstream-template-new/.coveragerc\nNIX OPs have {prefix}/folder/file WIN OPS have {prefix}/c:/folder/file
More info on git-diff can be found here: http://git-scm.com/docs/git-diff
Parameters:
diff The diff output to change
TYPE: str
repo0_path The full string path to the source repo
TYPE: str
repo1_path The full string path to the destination repo
TYPE: str
Returns:
str The modified diff string
"},{"location":"reference/api/cookie_composer/exceptions/","title":"Exceptions raised when bad things happen.
"},{"location":"reference/api/cookie_composer/exceptions/#cookie_composer.exceptions-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/exceptions/#cookie_composer.exceptions.ChangesetUnicodeError","title":"ChangesetUnicodeError","text":"ChangesetUnicodeError()\n Bases: UsageError
Raised when cookie-composer update is unable to generate the diff.
EmptyZipRepositoryError(url: str)\n Bases: InvalidZipRepositoryError
Raised when a zip repository is empty.
"},{"location":"reference/api/cookie_composer/exceptions/#cookie_composer.exceptions.GitError","title":"GitError","text":" Bases: UsageError
There was a problem doing git operations.
"},{"location":"reference/api/cookie_composer/exceptions/#cookie_composer.exceptions.InvalidZipPasswordError","title":"InvalidZipPasswordError","text":"InvalidZipPasswordError()\n Bases: InvalidZipRepositoryError
Raised when a zip repository is password-protected.
"},{"location":"reference/api/cookie_composer/exceptions/#cookie_composer.exceptions.InvalidZipRepositoryError","title":"InvalidZipRepositoryError","text":"InvalidZipRepositoryError(message: str = '')\n Bases: UsageError
Raised when a zip repository is invalid.
"},{"location":"reference/api/cookie_composer/exceptions/#cookie_composer.exceptions.MergeError","title":"MergeError","text":"MergeError(\n origin: Optional[str] = None,\n destination: Optional[str] = None,\n strategy: Optional[str] = None,\n error_message: Optional[str] = \"\",\n)\n Bases: UsageError
There was a problem merging a file.
"},{"location":"reference/api/cookie_composer/exceptions/#cookie_composer.exceptions.MissingCompositionFileError","title":"MissingCompositionFileError","text":"MissingCompositionFileError(path_or_url: str)\n Bases: UsageError
The composition is missing or inaccessible.
"},{"location":"reference/api/cookie_composer/exceptions/#cookie_composer.exceptions.NoZipDirectoryError","title":"NoZipDirectoryError","text":"NoZipDirectoryError(url: str)\n Bases: InvalidZipRepositoryError
Raised when a zip repository does not contain a directory.
"},{"location":"reference/api/cookie_composer/git_commands/","title":"Functions for using git.
"},{"location":"reference/api/cookie_composer/git_commands/#cookie_composer.git_commands-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/git_commands/#cookie_composer.git_commands-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/git_commands/#cookie_composer.git_commands.apply_patch","title":"apply_patch","text":"apply_patch(repo: Repo, diff: str) -> None\nApply a patch to a destination directory.
A git 3 way merge is the best bet at applying patches.
Parameters:
repo The git repo to apply the patch to
TYPE: Repo
diff The previously calculated diff
TYPE: str
branch_exists(repo: Repo, branch_name: str) -> bool\nDoes the branch exist in the repo?
Parameters:
repo The repository to check
TYPE: Repo
branch_name The name of the branch to check for
TYPE: str
Returns:
bool True if the branch exists
checkout_branch(\n repo: Repo,\n branch_name: str,\n remote_name: str = \"origin\",\n) -> None\nCheckout a local or remote branch.
"},{"location":"reference/api/cookie_composer/git_commands/#cookie_composer.git_commands.checkout_ref","title":"checkout_ref","text":"checkout_ref(repo: Repo, ref: str) -> None\nCheckout a ref.
Parameters:
repo The repository to check out
TYPE: Repo
ref The ref to check out
TYPE: str
clone(\n repo_url: str, dest_path: Optional[Path] = None\n) -> Repo\nClone a repo.
Parameters:
repo_url Repo URL or local path.
TYPE: str
dest_path The path to clone to.
TYPE: Optional[Path]
DEFAULT: None
Returns:
Repo The repository.
"},{"location":"reference/api/cookie_composer/git_commands/#cookie_composer.git_commands.get_repo","title":"get_repo","text":"get_repo(\n project_dir: Union[str, Path],\n search_parent_directories: bool = False,\n ensure_clean: bool = False,\n) -> Repo\nGet the git Repo object for a directory.
Parameters:
project_dir The directory containing the .git folder
TYPE: Union[str, Path]
search_parent_directories if True, all parent directories will be searched for a valid repo as well.
TYPE: bool
DEFAULT: False
ensure_clean if True, raise an error if the repo is dirty
TYPE: bool
DEFAULT: False
Raises:
GitError If the directory is not a git repo
GitError If the directory git repository is dirty
Returns:
Repo The GitPython Repo object
"},{"location":"reference/api/cookie_composer/git_commands/#cookie_composer.git_commands.remote_branch_exists","title":"remote_branch_exists","text":"remote_branch_exists(\n repo: Repo,\n branch_name: str,\n remote_name: str = \"origin\",\n) -> bool\nDoes the branch exist in the remote repo?
Parameters:
repo The repository to check
TYPE: Repo
branch_name The name of the branch to check for
TYPE: str
remote_name The name of the remote reference. Defaults to origin
TYPE: str
DEFAULT: 'origin'
Returns:
bool True if the branch exists in the remote repository
temp_git_worktree_dir(\n repo_path: Path,\n worktree_path: Optional[Path] = None,\n branch: Optional[str] = None,\n commit: Optional[str] = None,\n) -> Iterator[Path]\nContext Manager for a temporary working directory of a branch in a git repo.
Inspired by https://github.com/thomasjahoda/cookiecutter_project_upgrader/blob/master/ cookiecutter_project_upgrader/logic.py
Logic for checking out a branch or commit:
Parameters:
repo_path The path to the template git repo
TYPE: Path
worktree_path The path put the worktree in. Defaults to a temporary directory.
TYPE: Optional[Path]
DEFAULT: None
branch The branch to check out
TYPE: Optional[str]
DEFAULT: None
commit The optional commit to check out
TYPE: Optional[str]
DEFAULT: None
Path The worktree_path
Raises:
GitError If the worktree could not be created
"},{"location":"reference/api/cookie_composer/io/","title":"Functions for handling input/output operations.
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/io/#cookie_composer.io-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.deserialize_composition","title":"deserialize_composition","text":"deserialize_composition(\n composition_info: List[dict],\n local_path: Optional[Path] = None,\n **kwargs\n) -> Composition\nDeserialize a composition from output.
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.deserialize_layer","title":"deserialize_layer","text":"deserialize_layer(\n layer_info: dict,\n local_path: Optional[Path] = None,\n **kwargs: Any\n) -> LayerConfig\nDeserialize a layer configuration from a rendered layer.
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.deserialize_rendered_composition","title":"deserialize_rendered_composition","text":"deserialize_rendered_composition(\n composition_info: List[dict], location: Path\n) -> RenderedComposition\nDeserialize a rendered composition from output.
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.deserialize_rendered_layer","title":"deserialize_rendered_layer","text":"deserialize_rendered_layer(\n rendered_layer_info: dict, location: Path\n) -> RenderedLayer\nDeserialize a rendered layer from output.
Parameters:
rendered_layer_info A dictionary containing the rendered layer information
TYPE: dict
location The location of the rendered layer, typically the parent directory of the parent directory of the .composition.yaml file
TYPE: Path
Returns:
RenderedLayer A rendered layer object
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.get_composition_from_path_or_url","title":"get_composition_from_path_or_url","text":"get_composition_from_path_or_url(\n path_or_url: str,\n checkout: Optional[str] = None,\n default_config: bool = False,\n directory: Optional[str] = None,\n no_input: bool = False,\n output_dir: Optional[Path] = None,\n overwrite_if_exists: bool = False,\n skip_if_file_exists: bool = False,\n initial_context: Optional[\n MutableMapping[str, Any]\n ] = None,\n) -> Composition\nGenerate a Composition from a path or URL.
Parameters:
path_or_url The path or url to the composition file or template
TYPE: str
checkout The branch, tag or commit to check out after git clone
TYPE: Optional[str]
DEFAULT: None
default_config Do not load a config file. Use the defaults instead
TYPE: bool
DEFAULT: False
directory Directory within repo that holds cookiecutter.json file
TYPE: Optional[str]
DEFAULT: None
no_input If True force each layer\u2019s no_input attribute to True
TYPE: bool
DEFAULT: False
output_dir Where to generate the project
TYPE: Optional[Path]
DEFAULT: None
overwrite_if_exists Overwrite the contents of the output directory if it already exists
TYPE: bool
DEFAULT: False
skip_if_file_exists Skip the files in the corresponding directories if they already exist
TYPE: bool
DEFAULT: False
initial_context The initial context for the composition
TYPE: Optional[MutableMapping[str, Any]]
DEFAULT: None
Returns:
Composition The composition object.
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.is_composition_file","title":"is_composition_file","text":"is_composition_file(path_or_url: Union[str, Path]) -> bool\nReturn True if the filename a composition file.
Parameters:
path_or_url The path or URL to check
TYPE: Union[str, Path]
Returns:
bool True if the path is a configuration file.
read_composition(\n path_or_url: Union[str, Path], **kwargs: Any\n) -> Composition\nRead a YAML file and return a Composition.
Parameters:
path_or_url The location of the configuration file
TYPE: Union[str, Path]
**kwargs Additional keyword arguments passed to the composition
TYPE: Any
DEFAULT: {}
Returns:
Composition A composition
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.read_rendered_composition","title":"read_rendered_composition","text":"read_rendered_composition(\n path: Path,\n) -> RenderedComposition\nRead a .composition.yaml from a rendered project.
Parameters:
path The path to the .composition.yaml file to read
TYPE: Path
Returns:
RenderedComposition The rendered composition information
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.read_yaml","title":"read_yaml","text":"read_yaml(path_or_url: Union[str, Path]) -> List[dict]\nRead a YAML file and return a list of dictionaries.
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.serialize_composition","title":"serialize_composition","text":"serialize_composition(\n layers: List[LayerConfig],\n) -> List[dict]\nSerialize a composition for output.
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.serialize_layer","title":"serialize_layer","text":"serialize_layer(layer: LayerConfig) -> dict\nSerialize the layer configuration for outputting in a rendered layer.
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.serialize_rendered_composition","title":"serialize_rendered_composition","text":"serialize_rendered_composition(\n composition: RenderedComposition,\n) -> List[dict]\nSerialize a rendered composition for output.
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.serialize_rendered_layer","title":"serialize_rendered_layer","text":"serialize_rendered_layer(\n rendered_layer: RenderedLayer,\n) -> dict\nSerialize a rendered layer for output.
"},{"location":"reference/api/cookie_composer/io/#cookie_composer.io.write_rendered_composition","title":"write_rendered_composition","text":"write_rendered_composition(\n composition: RenderedComposition,\n) -> None\nWrite the composition file using the rendered layers to the appropriate place.
Parameters:
composition The rendered composition object to export
TYPE: RenderedComposition
write_yaml(path: Path, contents: List[dict]) -> None\nWrite a YAML file.
"},{"location":"reference/api/cookie_composer/layers/","title":"Layer management.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig","title":"LayerConfig","text":" Bases: BaseModel
Configuration for a layer of a composition.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.initial_context","title":"initial_contextclass-attribute instance-attribute","text":"initial_context: MutableMapping[str, Any] = Field(\n default_factory=dict\n)\nDictionary that will provide values for input.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.layer_name","title":"layer_nameproperty","text":"layer_name: str\nThe name of the template layer.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.merge_strategies","title":"merge_strategiesclass-attribute instance-attribute","text":"merge_strategies: Dict[str, str] = Field(\n default_factory=lambda: {\"*\": DO_NOT_MERGE}\n)\nThe method to merge specific paths or glob patterns.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.no_input","title":"no_inputclass-attribute instance-attribute","text":"no_input: bool = False\nDo not prompt for parameters and only use cookiecutter.json file content.
This is only used for initial generation. After initial generation, the results are stored in the context.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.overwrite","title":"overwriteclass-attribute instance-attribute","text":"overwrite: List[str] = Field(default_factory=list)\nPaths or glob patterns to always overwrite.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.overwrite_exclude","title":"overwrite_excludeclass-attribute instance-attribute","text":"overwrite_exclude: List[str] = Field(default_factory=list)\nPaths or glob patterns to exclude from overwriting.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.skip_generation","title":"skip_generationclass-attribute instance-attribute","text":"skip_generation: List[str] = Field(default_factory=list)\nPaths or glob patterns to skip attempting to generate.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.skip_hooks","title":"skip_hooksclass-attribute instance-attribute","text":"skip_hooks: bool = False\nSkip the template hooks.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.skip_if_file_exists","title":"skip_if_file_existsclass-attribute instance-attribute","text":"skip_if_file_exists: bool = True\nSkip the files in the corresponding directories if they already exist.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.template","title":"templateinstance-attribute","text":"template: Template\nInformation about the template.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.LayerConfig.generate_context","title":"generate_context","text":"generate_context(\n default_context: MutableMapping[str, Any]\n) -> OrderedDict\nGet the context for prompting the user for values.
The order of precedence is:
initial_context from the composition or command-linedefault_context from the user_configraw context from the templateEquivalent to cookiecutter.generate.generate_context but with the following differences:
extra_context{\"cookiecutter\": ...}Parameters:
default_context The default context from the user_config
TYPE: MutableMapping[str, Any]
Returns:
OrderedDict A dict containing the context for prompting the user
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.RenderedLayer","title":"RenderedLayer","text":" Bases: BaseModel
Information about a rendered layer.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.RenderedLayer-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.RenderedLayer.latest_commit","title":"latest_commitproperty","text":"latest_commit: Optional[str]\nThe latest commit checked out if the layer source was a git repo.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.RenderedLayer.layer","title":"layerinstance-attribute","text":"layer: LayerConfig\nThe original layer configuration that was rendered.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.RenderedLayer.location","title":"locationinstance-attribute","text":"location: DirectoryPath\nThe directory where the layer was rendered.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.RenderedLayer.rendered_commit","title":"rendered_commitclass-attribute instance-attribute","text":"rendered_commit: Optional[str] = None\nIf a git template, this is the commit of the template that was rendered.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.RenderedLayer.rendered_context","title":"rendered_contextinstance-attribute","text":"rendered_context: MutableMapping[str, Any]\nThe context based on questions asked.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.RenderedLayer.rendered_name","title":"rendered_nameclass-attribute instance-attribute","text":"rendered_name: Optional[str] = None\nThe name of the rendered template directory.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.RenderedLayer-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.RenderedLayer.set_rendered_name","title":"set_rendered_nameclassmethod","text":"set_rendered_name(values: Dict[str, Any]) -> Dict[str, Any]\nSet the [cookie_composer.layers.RenderedLayer.layer_name] to the name of the rendered template directory.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.WriteStrategy","title":"WriteStrategy","text":" Bases: Enum
How to deal with a file.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.WriteStrategy-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.WriteStrategy.MERGE","title":"MERGEclass-attribute instance-attribute","text":"MERGE = 3\nMerge the file with an existing file, or write a new file.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.WriteStrategy.SKIP","title":"SKIPclass-attribute instance-attribute","text":"SKIP = 2\nSkip the file.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.WriteStrategy.WRITE","title":"WRITEclass-attribute instance-attribute","text":"WRITE = 1\nWrite or overwrite the file.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.get_accept_hooks_per_layer","title":"get_accept_hooks_per_layer","text":"get_accept_hooks_per_layer(\n accept_hooks: str, num_layers: int\n) -> list\nConvert a single accept_hooks value into a value for every layer based on num_layers.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.get_layer_context","title":"get_layer_context","text":"get_layer_context(\n template_repo_dir: Path,\n context_for_prompting: dict,\n initial_context: MutableMapping[str, Any],\n full_context: Context,\n no_input: bool = False,\n) -> dict\nGet the context for a layer pre-rendering values using previous layers contexts as defaults.
The layer context is the combination of several things:
Parameters:
template_repo_dir The location of the template repo to use for rendering
TYPE: Path
context_for_prompting The raw context from the cookiecutter.json file with user defaults applied
TYPE: dict
initial_context The initial context from the layer configuration
TYPE: MutableMapping[str, Any]
full_context A full context from previous layers.
TYPE: Context
no_input If False do not prompt for missing values and use defaults instead.
TYPE: bool
DEFAULT: False
Returns:
dict A dict containing the context for rendering the layer
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.get_template_rendered_name","title":"get_template_rendered_name","text":"get_template_rendered_name(\n template: Template, context: MutableMapping\n) -> str\nFind and render the template\u2019s root directory\u2019s name.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.get_write_strategy","title":"get_write_strategy","text":"get_write_strategy(\n origin: Path,\n destination: Path,\n rendered_layer: RenderedLayer,\n) -> WriteStrategy\nBased on the layer_config rules, determine if we should overwrite an existing path.
Parameters:
origin Path within the rendered layer that we are evaluating.
TYPE: Path
destination Path to which we would write this file (may not actually exist)
TYPE: Path
rendered_layer Rendered layer configuration.
TYPE: RenderedLayer
Returns:
WriteStrategy The appropriate way to handle writing this file.
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.merge_layers","title":"merge_layers","text":"merge_layers(\n destination: Path, rendered_layer: RenderedLayer\n) -> None\nMerge a layer into another layer using the rules specified in the layer_config.
Parameters:
destination The root path to merge into.
TYPE: Path
rendered_layer The information about the rendered layer.
TYPE: RenderedLayer
render_layer(\n layer_config: LayerConfig,\n render_dir: Path,\n full_context: Optional[Context] = None,\n commit: Optional[str] = None,\n accept_hooks: str = \"yes\",\n) -> RenderedLayer\nProcess one layer of the template composition.
Renders the template using cookiecutter.
Parameters:
layer_config The configuration of the layer to render
TYPE: LayerConfig
render_dir Where to render the template
TYPE: Path
full_context The extra context from all layers in the composition
TYPE: Optional[Context]
DEFAULT: None
commit The commit to checkout if the template is a git repo
TYPE: Optional[str]
DEFAULT: None
accept_hooks Accept pre- and post-hooks if set to True
TYPE: str
DEFAULT: 'yes'
Returns:
RenderedLayer The rendered layer information
"},{"location":"reference/api/cookie_composer/layers/#cookie_composer.layers.render_layers","title":"render_layers","text":"render_layers(\n layers: List[LayerConfig],\n destination: Path,\n initial_context: Optional[dict] = None,\n no_input: bool = False,\n accept_hooks: str = \"all\",\n) -> List[RenderedLayer]\nRender layers to a destination.
Parameters:
layers A list of LayerConfig to render
TYPE: List[LayerConfig]
destination The location to merge the rendered layers to
TYPE: Path
initial_context An initial context to pass to the rendering
TYPE: Optional[dict]
DEFAULT: None
no_input If True force each layer\u2019s no_input attribute to True
TYPE: bool
DEFAULT: False
accept_hooks How to process pre/post hooks.
TYPE: str
DEFAULT: 'all'
Returns:
List[RenderedLayer] A list of the rendered layer information
"},{"location":"reference/api/cookie_composer/matching/","title":"Matching files and patterns.
"},{"location":"reference/api/cookie_composer/matching/#cookie_composer.matching-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/matching/#cookie_composer.matching.matches_any_glob","title":"matches_any_glob","text":"matches_any_glob(\n path: Union[str, Path], patterns: List[str]\n) -> bool\nDoes the path match any of the glob patterns?
Parameters:
path Path to test
TYPE: Union[str, Path]
patterns A list of glob patterns
TYPE: List[str]
Returns:
bool True if it matches any of the patterns
rel_fnmatch(name: str, pat: str) -> bool\nForce a relative match of the pattern by prefixing a *.
Utilities not easily categorized.
"},{"location":"reference/api/cookie_composer/utils/#cookie_composer.utils-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/utils/#cookie_composer.utils.echo","title":"echo","text":"echo(\n message: Optional[Any] = None,\n file: Optional[IO] = None,\n nl: bool = True,\n err: bool = False,\n color: Optional[bool] = None,\n **styles: Any\n) -> None\nA local abstraction for printing messages.
Default behavior is that of click.secho.
This is to allow user feedback without every function requiring a click dependency. Especially during testing.
Parameters:
message The string or bytes to output. Other objects are converted to strings.
TYPE: Optional[Any]
DEFAULT: None
file The file to write to. Defaults to stdout.
TYPE: Optional[IO]
DEFAULT: None
nl Print a newline after the message. Enabled by default.
TYPE: bool
DEFAULT: True
err Write to stderr instead of stdout.
TYPE: bool
DEFAULT: False
color Force showing or hiding colors and other styles. By default Click will remove color if the output does not look like an interactive terminal.
TYPE: Optional[bool]
DEFAULT: None
**styles Style keyword arguments
TYPE: Any
DEFAULT: {}
get_deleted_files(\n template_dir: Path, project_dir: Path\n) -> Set[Path]\nGet a list of files in the rendered template that do not exist in the project.
This is to avoid introducing changes that won\u2019t apply cleanly to the current project.
Nabbed from Cruft: https://github.com/cruft/cruft/
Parameters:
template_dir The path to the directory rendered with the same context as the project
TYPE: Path
project_dir The path to the current project
TYPE: Path
Returns:
Set[Path] A set of paths that are missing
"},{"location":"reference/api/cookie_composer/utils/#cookie_composer.utils.remove_paths","title":"remove_paths","text":"remove_paths(\n root: Path, paths_to_remove: Set[Path]\n) -> None\nRemove all paths in paths_to_remove from root.
Nabbed from Cruft: https://github.com/cruft/cruft/
Parameters:
root The absolute path of the directory requiring path removal
TYPE: Path
paths_to_remove The set of relative paths to remove from root
TYPE: Set[Path]
remove_readonly_bit(\n func: Callable[[str], None], path: str, _: Any\n) -> None\nClear the readonly bit and reattempt the removal.
"},{"location":"reference/api/cookie_composer/utils/#cookie_composer.utils.remove_single_path","title":"remove_single_path","text":"remove_single_path(path: Path) -> None\nRemove a path with extra error handling for Windows.
Parameters:
path The path to remove
TYPE: Path
Raises:
IOError If the file could not be removed
"},{"location":"reference/api/cookie_composer/utils/#cookie_composer.utils.temporary_copy","title":"temporary_copy","text":"temporary_copy(original_path: Path) -> Iterator[Path]\nCreate a temporary copy of a file or directory.
Parameters:
original_path The path to the file or directory to copy
TYPE: Path
Path The path to the temporary copy
"},{"location":"reference/api/cookie_composer/commands/","title":"Index","text":"Commands for cookie composer.
"},{"location":"reference/api/cookie_composer/commands/add/","title":"The implementation of the add command.
"},{"location":"reference/api/cookie_composer/commands/add/#cookie_composer.commands.add-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/commands/add/#cookie_composer.commands.add.add_cmd","title":"add_cmd","text":"add_cmd(\n path_or_url: str,\n destination_dir: Optional[Path] = None,\n no_input: bool = False,\n checkout: Optional[str] = None,\n directory: Optional[str] = None,\n overwrite_if_exists: bool = False,\n skip_if_file_exists: bool = False,\n default_config: bool = False,\n accept_hooks: str = \"all\",\n initial_context: Optional[\n MutableMapping[str, Any]\n ] = None,\n) -> None\nAdd a template or configuration to an existing project.
Parameters:
path_or_url A URL or string to add the template or configuration
TYPE: str
destination_dir The project directory to add the layer to
TYPE: Optional[Path]
DEFAULT: None
no_input If True force each layer\u2019s no_input attribute to True
TYPE: bool
DEFAULT: False
checkout The branch, tag or commit to check out after git clone
TYPE: Optional[str]
DEFAULT: None
directory Directory within repo that holds cookiecutter.json file
TYPE: Optional[str]
DEFAULT: None
overwrite_if_exists Overwrite the contents of the output directory if it already exists
TYPE: bool
DEFAULT: False
skip_if_file_exists Skip the files in the corresponding directories if they already exist
TYPE: bool
DEFAULT: False
default_config Do not load a config file. Use the defaults instead
TYPE: bool
DEFAULT: False
accept_hooks How to deal with pre/post hooks
TYPE: str
DEFAULT: 'all'
initial_context The initial context for the composition layer
TYPE: Optional[MutableMapping[str, Any]]
DEFAULT: None
Raises:
GitError If the destination_dir is not a git repository
ValueError If there is not a .composition.yaml file in the destination directory
"},{"location":"reference/api/cookie_composer/commands/authn/","title":"Authentication subcommands.
"},{"location":"reference/api/cookie_composer/commands/authn/#cookie_composer.commands.authn-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/commands/authn/#cookie_composer.commands.authn.auth","title":"auth","text":"auth() -> None\nAuthenticate cookie-composer to a service.
"},{"location":"reference/api/cookie_composer/commands/authn/#cookie_composer.commands.authn.login","title":"login","text":"login(\n git_protocol: str,\n service: str,\n scopes: str,\n with_token: click.File,\n) -> None\nAuthenticate to a service.
"},{"location":"reference/api/cookie_composer/commands/authn/#cookie_composer.commands.authn.token","title":"token","text":"token(service: str) -> None\nPrint the auth token cookie-composer is configured to use.
"},{"location":"reference/api/cookie_composer/commands/create/","title":"Methods for generating projects.
"},{"location":"reference/api/cookie_composer/commands/create/#cookie_composer.commands.create-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/commands/create/#cookie_composer.commands.create-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/commands/create/#cookie_composer.commands.create.create_cmd","title":"create_cmd","text":"create_cmd(\n path_or_url: str,\n output_dir: Optional[Path] = None,\n no_input: bool = False,\n checkout: Optional[str] = None,\n directory: Optional[str] = None,\n overwrite_if_exists: bool = False,\n skip_if_file_exists: bool = False,\n default_config: bool = False,\n accept_hooks: str = \"all\",\n initial_context: Optional[\n MutableMapping[str, Any]\n ] = None,\n) -> Path\nGenerate a new project from a composition file, local template or remote template.
Parameters:
path_or_url The path or url to the composition file or template
TYPE: str
output_dir Where to generate the project
TYPE: Optional[Path]
DEFAULT: None
no_input If True force each layer\u2019s no_input attribute to True
TYPE: bool
DEFAULT: False
checkout The branch, tag or commit to check out after git clone
TYPE: Optional[str]
DEFAULT: None
directory Directory within repo that holds cookiecutter.json file
TYPE: Optional[str]
DEFAULT: None
overwrite_if_exists Overwrite the contents of the output directory if it already exists
TYPE: bool
DEFAULT: False
skip_if_file_exists Skip the files in the corresponding directories if they already exist
TYPE: bool
DEFAULT: False
default_config Do not load a config file. Use the defaults instead
TYPE: bool
DEFAULT: False
accept_hooks Which pre/post hooks should be applied?
TYPE: str
DEFAULT: 'all'
initial_context The initial context for the composition
TYPE: Optional[MutableMapping[str, Any]]
DEFAULT: None
Raises:
ClickException If there is a problem cloning the repository
Returns:
Path The path to the generated project.
"},{"location":"reference/api/cookie_composer/commands/link/","title":"The implementation of the link command.
"},{"location":"reference/api/cookie_composer/commands/link/#cookie_composer.commands.link-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/commands/link/#cookie_composer.commands.link.link_cmd","title":"link_cmd","text":"link_cmd(\n path_or_url: str,\n destination_dir: Optional[Path] = None,\n no_input: bool = False,\n checkout: Optional[str] = None,\n directory: Optional[str] = None,\n overwrite_if_exists: bool = False,\n skip_if_file_exists: bool = False,\n default_config: bool = False,\n initial_context: Optional[\n MutableMapping[str, Any]\n ] = None,\n) -> None\nLink a template or configuration to an existing project.
Parameters:
path_or_url A URL or string to add the template or configuration
TYPE: str
destination_dir The project directory to add the layer to
TYPE: Optional[Path]
DEFAULT: None
no_input If True force each layer\u2019s no_input attribute to True
TYPE: bool
DEFAULT: False
checkout The branch, tag or commit to check out after git clone
TYPE: Optional[str]
DEFAULT: None
directory Directory within repo that holds cookiecutter.json file
TYPE: Optional[str]
DEFAULT: None
overwrite_if_exists Overwrite the contents of the output directory if it already exists
TYPE: bool
DEFAULT: False
skip_if_file_exists Skip the files in the corresponding directories if they already exist
TYPE: bool
DEFAULT: False
default_config Do not load a config file. Use the defaults instead
TYPE: bool
DEFAULT: False
initial_context The initial context for the composition
TYPE: Optional[MutableMapping[str, Any]]
DEFAULT: None
Raises:
GitError If the destination_dir is not a git repository
GitError If the destination_dir git repository is dirty
ValueError If there is a .composition.yaml file in the destination directory
"},{"location":"reference/api/cookie_composer/commands/update/","title":"The implementation of the update command.
"},{"location":"reference/api/cookie_composer/commands/update/#cookie_composer.commands.update-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/commands/update/#cookie_composer.commands.update-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/commands/update/#cookie_composer.commands.update.update_cmd","title":"update_cmd","text":"update_cmd(\n project_dir: Optional[Path] = None,\n no_input: bool = False,\n) -> None\nUpdate the project with the latest versions of each layer.
Parameters:
project_dir The project directory to update. Defaults to current directory.
TYPE: Optional[Path]
DEFAULT: None
no_input If True force each layer\u2019s no_input attribute to True
TYPE: bool
DEFAULT: False
Raises:
GitError If the destination_dir is not a git repository
ValueError If there is not a .composition.yaml file in the destination directory
"},{"location":"reference/api/cookie_composer/commands/update/#cookie_composer.commands.update.update_rendered_composition_layers","title":"update_rendered_composition_layers","text":"update_rendered_composition_layers(\n base: RenderedComposition,\n updated_layers: List[RenderedLayer],\n) -> RenderedComposition\nUpdate base.layers with updated_layers where layer names match.
If, for some reason, a layer exists in updated_layers but not in base, it is discarded.
Parameters:
base The base composition whose layers are to be updated
TYPE: RenderedComposition
updated_layers The new rendered layers
TYPE: List[RenderedLayer]
Raises:
RuntimeError If a layer\u2019s location render_dir properties don\u2019t match
RuntimeError If the compositions\u2019 rendered_name properties don\u2019t match
Returns:
RenderedComposition A new composition with updated layers
"},{"location":"reference/api/cookie_composer/merge_files/","title":"Index","text":"Methods for merging data files.
The merging functions should look similar to the following:
def merge_generic_files(origin: Path, destination: Path, merge_strategy: str) -> None:\nThe function must write the file to destination.
The function must wrap any errors into a MergeError and raise it.
"},{"location":"reference/api/cookie_composer/merge_files/#cookie_composer.merge_files-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/merge_files/ini_file/","title":"Merge two .ini files into one.
"},{"location":"reference/api/cookie_composer/merge_files/ini_file/#cookie_composer.merge_files.ini_file-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/merge_files/ini_file/#cookie_composer.merge_files.ini_file-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/merge_files/ini_file/#cookie_composer.merge_files.ini_file-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/merge_files/ini_file/#cookie_composer.merge_files.ini_file.config_to_dict","title":"config_to_dict","text":"config_to_dict(config: configparser.ConfigParser) -> dict\nConvert a configparser object to a dictionary.
"},{"location":"reference/api/cookie_composer/merge_files/ini_file/#cookie_composer.merge_files.ini_file.dict_to_config","title":"dict_to_config","text":"dict_to_config(\n dictionary: dict,\n) -> configparser.ConfigParser\nConvert a dict to a configparser object.
"},{"location":"reference/api/cookie_composer/merge_files/ini_file/#cookie_composer.merge_files.ini_file.merge_ini_files","title":"merge_ini_files","text":"merge_ini_files(\n new_file: Path, existing_file: Path, merge_strategy: str\n) -> None\nMerge two INI files into one.
Raises:
MergeError If something goes wrong
Parameters:
new_file The path to the data file to merge
TYPE: Path
existing_file The path to the data file to merge into and write out.
TYPE: Path
merge_strategy How to do the merge
TYPE: str
Merge two json files into one.
"},{"location":"reference/api/cookie_composer/merge_files/json_file/#cookie_composer.merge_files.json_file-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/merge_files/json_file/#cookie_composer.merge_files.json_file-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/merge_files/json_file/#cookie_composer.merge_files.json_file-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/merge_files/json_file/#cookie_composer.merge_files.json_file.default","title":"default","text":"default(obj: Any) -> dict\nDefault JSON encoder.
"},{"location":"reference/api/cookie_composer/merge_files/json_file/#cookie_composer.merge_files.json_file.merge_json_files","title":"merge_json_files","text":"merge_json_files(\n new_file: Path, existing_file: Path, merge_strategy: str\n) -> None\nMerge two json files into one.
Parameters:
new_file The path to the data file to merge
TYPE: Path
existing_file The path to the data file to merge into and write out.
TYPE: Path
merge_strategy How to do the merge
TYPE: str
Raises:
MergeError If something goes wrong
"},{"location":"reference/api/cookie_composer/merge_files/toml_file/","title":"Merge two toml files into one.
"},{"location":"reference/api/cookie_composer/merge_files/toml_file/#cookie_composer.merge_files.toml_file-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/merge_files/toml_file/#cookie_composer.merge_files.toml_file-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/merge_files/toml_file/#cookie_composer.merge_files.toml_file-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/merge_files/toml_file/#cookie_composer.merge_files.toml_file.merge_toml_files","title":"merge_toml_files","text":"merge_toml_files(\n new_file: Path, existing_file: Path, merge_strategy: str\n) -> None\nMerge two toml files into one.
Parameters:
new_file The path to the data file to merge
TYPE: Path
existing_file The path to the data file to merge into and write out.
TYPE: Path
merge_strategy How to do the merge
TYPE: str
Raises:
MergeError If something goes wrong
"},{"location":"reference/api/cookie_composer/merge_files/yaml_file/","title":"Merge two json files into one.
"},{"location":"reference/api/cookie_composer/merge_files/yaml_file/#cookie_composer.merge_files.yaml_file-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/merge_files/yaml_file/#cookie_composer.merge_files.yaml_file-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/merge_files/yaml_file/#cookie_composer.merge_files.yaml_file-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/merge_files/yaml_file/#cookie_composer.merge_files.yaml_file.merge_yaml_files","title":"merge_yaml_files","text":"merge_yaml_files(\n new_file: Path, existing_file: Path, merge_strategy: str\n) -> None\nMerge two json files into one.
Parameters:
new_file The path to the data file to merge
TYPE: Path
existing_file The path to the data file to merge into and write out.
TYPE: Path
merge_strategy How to do the merge
TYPE: str
Raises:
MergeError If something goes wrong
"},{"location":"reference/api/cookie_composer/templates/","title":"Index","text":"Templates for cookie_composer.
"},{"location":"reference/api/cookie_composer/templates/git_repo/","title":"Utility functions for handling and fetching repo archives in git format.
"},{"location":"reference/api/cookie_composer/templates/git_repo/#cookie_composer.templates.git_repo-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/templates/git_repo/#cookie_composer.templates.git_repo-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/templates/git_repo/#cookie_composer.templates.git_repo.get_cached_remote","title":"get_cached_remote","text":"get_cached_remote(\n git_uri: str,\n cache_dir: Path,\n checkout: Optional[str] = None,\n) -> Repo\nReturn a cached remote repo.
This provides some error-checking for the cached repo, and will re-clone if the cached repo is in a detached head state.
Parameters:
git_uri The remote git URI
TYPE: str
cache_dir The directory to cache the repo in
TYPE: Path
checkout The optional checkout ref to use
TYPE: Optional[str]
DEFAULT: None
Returns:
Repo The cached repo
"},{"location":"reference/api/cookie_composer/templates/git_repo/#cookie_composer.templates.git_repo.get_repo_name","title":"get_repo_name","text":"get_repo_name(\n repo_url: str, checkout: Optional[str] = None\n) -> str\nConstruct the destination repo name from the repo URL and checkout.
"},{"location":"reference/api/cookie_composer/templates/git_repo/#cookie_composer.templates.git_repo.template_repo_from_git","title":"template_repo_from_git","text":"template_repo_from_git(\n git_uri: str,\n locality: Locality,\n cache_dir: Path,\n checkout: Optional[str] = None,\n) -> TemplateRepo\nReturn a template repo from a git URI.
mytemplate_main. This allows for multiple versions of the same repo to be cached without a conflict.checkout, and the local path is returned.Entry point for cookiecutter templates.
"},{"location":"reference/api/cookie_composer/templates/source/#cookie_composer.templates.source-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/templates/source/#cookie_composer.templates.source-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/templates/source/#cookie_composer.templates.source.get_template_repo","title":"get_template_repo","text":"get_template_repo(\n url: str,\n local_path: Optional[Path] = None,\n checkout: Optional[str] = None,\n password: Optional[str] = None,\n) -> TemplateRepo\nGet a template repository from a URL.
Parameters:
url The string from the template field in the composition file.
TYPE: str
local_path Used to resolve local paths.
TYPE: Optional[Path]
DEFAULT: None
checkout The branch, tag or commit to check out after git clone
TYPE: Optional[str]
DEFAULT: None
password The password to use if template is a password-protected Zip archive.
TYPE: Optional[str]
DEFAULT: None
Returns:
TemplateRepo A TemplateRepo object.
"},{"location":"reference/api/cookie_composer/templates/source/#cookie_composer.templates.source.identify_repo","title":"identify_repo","text":"identify_repo(\n url: str, local_path: Optional[Path] = None\n) -> Tuple[TemplateFormat, Locality]\nIdentify the repo format and locality from the URL.
"},{"location":"reference/api/cookie_composer/templates/source/#cookie_composer.templates.source.resolve_local_path","title":"resolve_local_path","text":"resolve_local_path(\n url: str, local_path: Optional[Path] = None\n) -> Path\nResolve a local path.
Parameters:
url The string from the template field in the composition file.
TYPE: str
local_path An optional path to resolve the URL against.
TYPE: Optional[Path]
DEFAULT: None
Returns:
Path The resolved path.
"},{"location":"reference/api/cookie_composer/templates/types/","title":"Datatypes for templates.
Templates are a representation of source templates used to generate projects.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Locality","title":"Locality","text":" Bases: str, Enum
The locality of a template.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Template","title":"Templatedataclass","text":"Template(\n repo: TemplateRepo,\n directory: str = \"\",\n _context: Optional[OrderedDict] = None,\n)\nA template is the combination of a template repository and a directory containing a cookiecutter.json file.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Template-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Template.cached_path","title":"cached_pathproperty","text":"cached_path: Path\nThe path to the cached template.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Template.context","title":"contextproperty","text":"context: dict\nThe context of the template.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Template.context_file_path","title":"context_file_pathproperty","text":"context_file_path: Path\nThe path to the template\u2019s context file.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Template.directory","title":"directoryclass-attribute instance-attribute","text":"directory: str = ''\nThe directory within the repository that contains the cookiecutter.json file.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Template.name","title":"nameproperty","text":"name: str\nThe name of the template.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Template.repo","title":"repoinstance-attribute","text":"repo: TemplateRepo\nThe source of the template.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Template-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.Template.cleanup","title":"cleanup","text":"cleanup() -> None\nRemove the cached template if it is a Zipfile.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateFormat","title":"TemplateFormat","text":" Bases: str, Enum
The format of a template.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateFormat-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateFormat.PLAIN","title":"PLAINclass-attribute instance-attribute","text":"PLAIN = 'plain'\nA plain directory that isn\u2019t under version control.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo","title":"TemplateRepodataclass","text":"TemplateRepo(\n source: str,\n cached_source: Path,\n format: TemplateFormat,\n locality: Locality,\n checkout: Optional[str] = None,\n password: Optional[str] = None,\n)\nA template repository is a source of one or more templates.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo-attributes","title":"Attributes","text":""},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo.cached_source","title":"cached_sourceinstance-attribute","text":"cached_source: Path\nThe path to the locally cached template.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo.checkout","title":"checkoutclass-attribute instance-attribute","text":"checkout: Optional[str] = None\nThe branch, tag or commit for the template to track.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo.current_sha","title":"current_shaproperty","text":"current_sha: Optional[str]\nIf the template is a git repository, return the current commit hash.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo.format","title":"formatinstance-attribute","text":"format: TemplateFormat\nThe format of the template.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo.latest_sha","title":"latest_shaproperty","text":"latest_sha: Optional[str]\nReturn the latest SHA of this template\u2019s repo.
If the template is not a git repository, it will always return None.
Returns:
Optional[str] The latest hexsha of the template or None if the template isn\u2019t a git repo
instance-attribute","text":"locality: Locality\nIs the template local or remote?
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo.password","title":"passwordclass-attribute instance-attribute","text":"password: Optional[str] = None\nThe password to use if template is a password-protected Zip archive.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo.source","title":"sourceinstance-attribute","text":"source: str\nThe original path or URL to the template.
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.TemplateRepo.render_source","title":"render_source","text":"render_source(\n output_dir: Optional[Path] = None,\n commit: Optional[str] = None,\n) -> Iterator[Path]\nA context manager that provides the source from which to render the template.
For git repositories, this will create a temporary working tree of the repository and yield the path to the working tree.
For Zip archives, this will extract the archive to a temporary directory and yield the path
For plain repos, it will yield the path to the directory.
Parameters:
output_dir The directory to extract the template to. If not provided, a temporary directory will be used.
TYPE: Optional[Path]
DEFAULT: None
commit The commit to checkout if the template is a git repository.
TYPE: Optional[str]
DEFAULT: None
Path The path to the rendered template
"},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/templates/types/#cookie_composer.templates.types.get_template_name","title":"get_template_name","text":"get_template_name(\n path_or_url: str,\n directory: Optional[str] = None,\n checkout: Optional[str] = None,\n) -> str\nGet the name of the template using the path or URL.
Parameters:
path_or_url The URL or path to the template
TYPE: str
directory Directory within a git repository template that holds the cookiecutter.json file.
TYPE: Optional[str]
DEFAULT: None
checkout The branch, tag or commit to use if template is a git repository.
TYPE: Optional[str]
DEFAULT: None
Raises:
ValueError If the path_or_url is not parsable
Returns:
str The name of the template without extensions
"},{"location":"reference/api/cookie_composer/templates/zipfile_repo/","title":"Utility functions for handling and fetching repo archives in zip format.
"},{"location":"reference/api/cookie_composer/templates/zipfile_repo/#cookie_composer.templates.zipfile_repo-classes","title":"Classes","text":""},{"location":"reference/api/cookie_composer/templates/zipfile_repo/#cookie_composer.templates.zipfile_repo-functions","title":"Functions","text":""},{"location":"reference/api/cookie_composer/templates/zipfile_repo/#cookie_composer.templates.zipfile_repo.cache_source","title":"cache_source","text":"cache_source(\n zip_uri: str,\n is_remote: bool,\n cache_dir: Path,\n no_input: bool = False,\n) -> Path\nDownload and unpack a zipfile at a given URI.
This will download the zipfile to the cookiecutter repository, and unpack into a temporary directory.
Parameters:
zip_uri The URI for the zipfile.
TYPE: str
is_remote Is the zip URI a URL or a file?
TYPE: bool
cache_dir The cookiecutter repository directory to put the archive into.
TYPE: Path
no_input Do not prompt for user input and eventually force a refresh of cached resources.
TYPE: bool
DEFAULT: False
Returns:
Path The path to the unpacked zipfile.
"},{"location":"reference/api/cookie_composer/templates/zipfile_repo/#cookie_composer.templates.zipfile_repo.download_zipfile","title":"download_zipfile","text":"download_zipfile(\n url: str, cache_dir: Path, no_input: bool = False\n) -> Path\nDownload a zipfile from a URL into the cache_dir.
"},{"location":"reference/api/cookie_composer/templates/zipfile_repo/#cookie_composer.templates.zipfile_repo.extract_zipfile","title":"extract_zipfile","text":"extract_zipfile(\n zip_path: Path,\n output_dir: Optional[Path] = None,\n password: Optional[str] = None,\n) -> Path\nExtract a zipfile into a temporary directory.
Parameters:
zip_path The path to the zipfile.
TYPE: Path
output_dir Optional path to extract the zipfile to. Defaults to a temporary directory.
TYPE: Optional[Path]
DEFAULT: None
password The password for a password-protected zipfile.
TYPE: Optional[str]
DEFAULT: None
Raises:
InvalidZipPasswordError If the zipfile is password-protected and the user provides an incorrect password.
Returns:
Path The temporary directory containing the unpacked zipfile.
"},{"location":"reference/api/cookie_composer/templates/zipfile_repo/#cookie_composer.templates.zipfile_repo.template_repo_from_zipfile","title":"template_repo_from_zipfile","text":"template_repo_from_zipfile(\n zip_uri: str,\n locality: Locality,\n cache_dir: Path,\n no_input: bool = False,\n password: Optional[str] = None,\n) -> TemplateRepo\nReturn a template repo from a zipfile URI.
"},{"location":"reference/api/cookie_composer/templates/zipfile_repo/#cookie_composer.templates.zipfile_repo.validate_zipfile","title":"validate_zipfile","text":"validate_zipfile(zip_path: Path, zip_uri: str) -> None\nValidate that a zipfile exists and is not empty.
Parameters:
zip_path The path to the zipfile.
TYPE: Path
zip_uri The origin URI of the zipfile.
TYPE: str
Raises:
EmptyZipRepositoryError If the zipfile is empty.
NoZipDirectoryError If the zipfile does not contain a top-level directory.
"},{"location":"topic-guides/","title":"Topic Guides","text":""},{"location":"topic-guides/composition-files/","title":"Composition files","text":"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 compositiontemplate: \"https://github.com/coordt/cookiecomposer-templates\"\ndirectory: \"cookiecutter-boilerplate\"\nmerge_strategies:\n '*.json': \"comprehensive\"\n '*.yaml': \"comprehensive\"\n '*.yml': \"comprehensive\"\n---\ntemplate: \"https://github.com/coordt/cookiecomposer-templates\"\ndirectory: \"cookiecutter-package\"\nmerge_strategies:\n '*.json': \"comprehensive\"\n '*.yaml': \"comprehensive\"\n '*.yml': \"comprehensive\"\n---\ntemplate: \"https://github.com/coordt/cookiecomposer-templates\"\ndirectory: \"cookiecutter-docs\"\nmerge_strategies:\n '*.json': \"comprehensive\"\n '*.yaml': \"comprehensive\"\n '*.yml': \"comprehensive\"\nWhen 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\nproject_name [python-boilerplate]: my-test-project\nproject_slug [my_test_project]:\nfriendly_name [My Test Project]:\nproject_short_description []:\nversion [0.1.0]:\nauthor [Who am I?]:\nemail [whoami@existential-crisis.doom]:\ngithub_user [whoami]:\nThe composition file saved in the new project (named my-test-project in this example) as .composition.yaml would look like:
checkout: null\ncommit: 3391f60471939dd412e93e9853e3328e7a5a8c44\ncontext:\n _copy_without_render: [.github/**/*.jinja]\n _dev_requirements: {bump2version: '>=1.0.1', generate-changelog: '>=0.7.6', git-fame: '>=1.12.2',\n pip-tools: ''}\n _prod_requirements: {environs: '>=9.3.5'}\n _test_requirements: {black: '>=19.10b0', coverage: '>=6.1.2', flake8: '>=4.0.1',\n pre-commit: '>=2.15.0', pytest: '>=6.0.0', pytest-cov: '>=3.0.0'}\n author: Who am I?\n email: whoami@existential-crisis.doom\n friendly_name: My Test Project\n github_user: whoami\n project_name: my-test-project\n project_short_description: ''\n project_slug: my_test_project\n version: 0.1.0\ndirectory: cookiecutter-boilerplate\nmerge_strategies: {'*.json': comprehensive, '*.yaml': comprehensive, '*.yml': comprehensive}\nno_input: false\noverwrite: []\noverwrite_exclude: []\npassword: null\nskip_generation: []\nskip_hooks: false\nskip_if_file_exists: true\ntemplate: https://github.com/coordt/cookiecomposer-templates\n---\ncheckout: null\ncommit: 3391f60471939dd412e93e9853e3328e7a5a8c44\ncontext: {friendly_name: My Test Project, project_name: my-test-project, project_short_description: '',\n project_slug: my_test_project, version: 0.1.0}\ndirectory: cookiecutter-package\nmerge_strategies: {'*.json': comprehensive, '*.yaml': comprehensive, '*.yml': comprehensive}\nno_input: false\noverwrite: []\noverwrite_exclude: []\npassword: null\nskip_generation: []\nskip_hooks: false\nskip_if_file_exists: true\ntemplate: https://github.com/coordt/cookiecomposer-templates\n---\ncheckout: null\ncommit: 3391f60471939dd412e93e9853e3328e7a5a8c44\ncontext:\n _copy_without_render: [docsrc/**/*.rst]\n _dev_requirements: {bump2version: '>=1.0.1', generate-changelog: '>=0.7.6', git-fame: '>=1.12.2',\n pip-tools: ''}\n _docs_requirements: {Sphinx: '>=4.3.0', furo: '', ghp-import: '', linkify-it-py: '',\n myst-parser: '', sphinx-autodoc-typehints: '', sphinx-click: '', sphinx-copybutton: ''}\n _prod_requirements: {environs: '>=9.3.5'}\n friendly_name: My Test Project\n github_user: whoami\n project_name: my-test-project\n project_slug: my_test_project\ndirectory: cookiecutter-docs\nmerge_strategies: {'*.json': comprehensive, '*.yaml': comprehensive, '*.yml': comprehensive}\nno_input: false\noverwrite: []\noverwrite_exclude: []\npassword: null\nskip_generation: []\nskip_hooks: false\nskip_if_file_exists: true\ntemplate: https://github.com/coordt/cookiecomposer-templates\nIf you look closely you\u2019ll see that .composition.yaml contains the contents of package-composition.yaml. Internally the .composition.yaml file is termed a \u201crendered composition\u201d because it contains all the parameters used to render this specific project. This rendered composition is used when applying updates of the templates.
Composition files are technically YAML streams consisting of one or more documents describing a layer configuration.
"},{"location":"tutorial/","title":"Tutorial","text":""},{"location":"tutorial/composable-templates/","title":"Designing composable templates","text":""},{"location":"tutorial/compositions/","title":"Building a project from a composition","text":"Do the same thing as incrementally layering, but use a composition to alleviate the issues.
Issues to resolve:
A composition is a series of template layers. We can reproduce the results of the previous tutorial using this file:
my-package-composition.yamltemplate: https://github.com/rwxd/cookiecutter-github-project\n---\ntemplate: https://github.com/kragniz/cookiecutter-pypackage-minimal\nWe didn\u2019t change the default for the project_slug, topics or open_source_license prompts. You don\u2019t have to change all the prompts or include all the prompts in the composition.
Then run:
$ cookie-composer create /path/to/my-package-composition.yaml\n\nfull_name [rwxd]: Demo User\nemail [rwxd@pm.me]: demo_user@example.com\ngithub_username [rwxd]: demo_user\nproject_name [Python Boilerplate]: Cookie Composer Demo\nproject_slug [composer_demo]:\nproject_short_description [Python Boilerplate contains all the boilerplate you need to create a Python package.]: Cookie Composer Demo\nhomepage [https://rwxd.github.io/composer_demo/]: https://demo_user.github.io/composer_demo/\nSelect project_type:\n1 - python\n2 - go\n3 - ansible\n4 - other\nChoose from 1, 2, 3, 4 [1]:\ntopics []:\nSelect open_source_license:\n1 - MIT license\n2 - BSD license\n3 - ISC license\n4 - Apache Software License 2.0\n5 - GNU General Public License v3\n6 - Not open source\nChoose from 1, 2, 3, 4, 5, 6 [1]:\nauthor_name [Louis Taylor]: Demo User\nauthor_email [louis@kragniz.eu]: demo_user@example.com\npackage_name [cookiecutter_pypackage_minimal]: composer_demo\npackage_version [0.1.0]:\npackage_description [An opinionated, minimal cookiecutter template for Python packages]: Cookie Composer Demo\npackage_url [https://github.com/kragniz/cookiecutter-pypackage-minimal]: https://github.com/demo_user/composer_demo\nreadme_pypi_badge [True]:\nreadme_travis_badge [True]:\nreadme_travis_url [https://travis-ci.org/kragniz/cookiecutter-pypackage-minimal]: https://travis-ci.org/demouser/composer_demo\nBoth layers are applied without requiring a git repository or multiple commands.
"},{"location":"tutorial/compositions/#providing-better-defaults","title":"Providing better defaults","text":"The composition can also improve the defaults for the template prompts by:
Let\u2019s start by changing some defaults to the first template. You can find the original prompt in this template\u2019s cookiecutter.json file.
my-package-composition.yamltemplate: https://github.com/rwxd/cookiecutter-github-project\ncontext:\n full_name: Your Name\n email: \"{{ cookiecutter.full_name.lower().replace(' ', '_') }}@example.com\"\n github_username: \"{{ cookiecutter.full_name.lower().replace(' ', '_') }}\"\n homepage: \"https://{{ cookiecutter.github_username }}.github.io/{{ cookiecutter.project_slug }}\"\n project_short_description: \"\"\n project_type: python\n---\ntemplate: https://github.com/kragniz/cookiecutter-pypackage-minimal\nThe new defaults provide better suggestions based on previous prompt answers.
"},{"location":"tutorial/compositions/#using-values-from-previous-templates","title":"Using values from previous templates","text":"The second template has several prompts that simply synonymns of promts from the previous template. It would be nice if we could use our answers from that template here.
Let\u2019s do that. You can find the original prompts in this template\u2019s cookiecutter.json file.
my-package-composition.yamltemplate: https://github.com/rwxd/cookiecutter-github-project\ncontext:\n full_name: Your Name\n email: \"{{ cookiecutter.full_name.lower().replace(' ', '_') }}@example.com\"\n github_username: \"{{ cookiecutter.full_name.lower().replace(' ', '_') }}\"\n homepage: \"https://{{ cookiecutter.github_username }}.github.io/{{ cookiecutter.project_slug }}\"\n project_short_description: \"\"\n project_type: python\n---\ntemplate: https://github.com/kragniz/cookiecutter-pypackage-minimal\ncontext:\n author_name: \"{{ cookiecutter.full_name }}\"\n author_email: \"{{ cookiecutter.email }}\"\n package_name: \"{{ cookiecutter.project_slug }}\"\n package_description: \"{{ cookiecutter.project_short_description }}\"\n package_url: \"https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}\"\n readme_travis_badge: false\n readme_travis_url: \"\"\nNow:
author_name defaults to full_name\u2019s valueauthor_email defaults to email\u2019s valuepackage_name defaults to project_slug\u2019s valuepackage_description defaults to project_short_description\u2019s valuepackage_url references both github_username\u2019s and project_slug\u2019s values$ cookie-composer create /path/to/tutorial-composition-3.yaml\n\nfull_name [Your Name]: Demo User\nemail [demo_user@example.com]:\ngithub_username [demo_user]:\nproject_name [Python Boilerplate]: Composer Demo\nproject_slug [composer_demo]:\nproject_short_description []: Cookie Composer Demo\nhomepage [https://demo_user.github.io/composer_demo]:\nSelect project_type:\n1 - python\n2 - go\n3 - ansible\n4 - other\nChoose from 1, 2, 3, 4 [1]:\ntopics []:\nSelect open_source_license:\n1 - MIT license\n2 - BSD license\n3 - ISC license\n4 - Apache Software License 2.0\n5 - GNU General Public License v3\n6 - Not open source\nChoose from 1, 2, 3, 4, 5, 6 [1]:\nauthor_name [Demo User]:\nauthor_email [demo_user@example.com]:\npackage_name [composer_demo]:\npackage_version [0.1.0]:\npackage_description [Cookie Composer Demo]:\npackage_url [https://github.com/demo_user/composer_demo]:\nreadme_pypi_badge [True]:\nreadme_travis_badge [False]:\nreadme_travis_url []:\nNotice how the better defaults allow less typing and more consistency.
"},{"location":"tutorial/incrementally-layering/","title":"Building a project layer by layer","text":""},{"location":"tutorial/incrementally-layering/#create-a-project-from-a-template","title":"Create a project from a template","text":"https://github.com/rwxd/cookiecutter-github-project
$ cookie-composer create https://github.com/rwxd/cookiecutter-github-project\nfull_name [rwxd]: Demo User\nemail [rwxd@pm.me]: demo_user@example.com\ngithub_username [rwxd]: demo_user\nproject_name [Python Boilerplate]: Composer Demo\nproject_slug [composer_demo]:\nproject_short_description [Python Boilerplate contains all the boilerplate you need to create a Python package.]: A Cookie Composer demo\nhomepage [https://rwxd.github.io/composer_demo/]: https://demo_user.github.io/composer_demo/\nSelect project_type:\n1 - python\n2 - go\n3 - ansible\n4 - other\nChoose from 1, 2, 3, 4 [1]:\ntopics []:\nSelect open_source_license:\n1 - MIT license\n2 - BSD license\n3 - ISC license\n4 - Apache Software License 2.0\n5 - GNU General Public License v3\n6 - Not open source\nChoose from 1, 2, 3, 4, 5, 6 [1]:\n$ cd composer_demo\n$ cookie-composer add https://github.com/kragniz/cookiecutter-pypackage-minimal\nUsage: cookie-composer add [OPTIONS] PATH_OR_URL [DESTINATION]\nTry 'cookie-composer add --help' for help.\n\u256d\u2500 Error \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 Some cookie composer commands only work on git repositories. Please make the destination directory a \u2502\n\u2502 git repo. \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n$ git add -A\n$ git commit -m\"Initial commit\"\n[master (root-commit) 90a6a74] Initial commit\n 15 files changed, 352 insertions(+)\n create mode 100644 .composition.yaml\n create mode 100644 .github/ISSUE_TEMPLATE/bug_report_md\n create mode 100644 .github/ISSUE_TEMPLATE/config.yml\n create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md\n create mode 100644 .github/dependabot.yml\n create mode 100644 .github/settings.yml\n create mode 100644 .github/workflows/semantic-release.yml\n create mode 100644 .gitignore\n create mode 100644 .pre-commit-config.yaml\n create mode 100644 .releaserc.yml\n create mode 100644 LICENSE\n create mode 100644 Makefile\n create mode 100644 README.md\n create mode 100644 renovate.json\n create mode 100644 requirements-dev.txt\n ```\n\n```console\ncookie-composer add https://github.com/kragniz/cookiecutter-pypackage-minimal\nauthor_name [Louis Taylor]: Demo User\nauthor_email [louis@kragniz.eu]: demo_user@example.com\npackage_name [cookiecutter_pypackage_minimal]: composer_demo\npackage_version [0.1.0]:\npackage_description [An opinionated, minimal cookiecutter template for Python packages]: A Cookie Composer demo\npackage_url [https://github.com/kragniz/cookiecutter-pypackage-minimal]: https://github.com/demo_user/composer_demo\nreadme_pypi_badge [True]:\nreadme_travis_badge [True]: \nreadme_travis_url [https://travis-ci.org/kragniz/cookiecutter-pypackage-minimal]: https://travis-ci.org/demouser/composer_demo\nNow on branch add_layer_cookiecutter-pypackage-minimal
$ git status\nOn branch add_layer_cookiecutter-pypackage-minimal\nChanges not staged for commit:\n (use \"git add <file>...\" to update what will be committed)\n (use \"git restore <file>...\" to discard changes in working directory)\n modified: .composition.yaml\n\nUntracked files:\n (use \"git add <file>...\" to include in what will be committed)\n README.rst\n python_boilerplate/\n setup.py\n tests/\n tox.ini\nThe modified .composition.yaml file includes the new layer information.
Let\u2019s commit the new files
$ git add -A\n$ git commit -m\"Added layer cookiecutter-pypackage-minimal\"\n[add_layer_cookiecutter-pypackage-minimal dc62ba1] Added layer cookiecutter-pypackage-minimal\n 6 files changed, 115 insertions(+)\n create mode 100644 README.rst\n create mode 100644 python_boilerplate/__init__.py\n create mode 100644 setup.py\n create mode 100644 tests/test_sample.py\n create mode 100644 tox.ini\nNow the new branch is ready to merge.
$ git checkout master\n$ git merge add_layer_cookiecutter-pypackage-minimal\nUpdating aa3f701..dc62ba1\nFast-forward\n .composition.yaml | 24 ++++++++++++++++++++++++\n README.rst | 32 ++++++++++++++++++++++++++++++++\n python_boilerplate/__init__.py | 5 +++++\n setup.py | 44 ++++++++++++++++++++++++++++++++++++++++++++\n tests/test_sample.py | 4 ++++\n tox.ini | 6 ++++++\n 6 files changed, 115 insertions(+)\n create mode 100644 README.rst\n create mode 100644 python_boilerplate/__init__.py\n create mode 100644 setup.py\n create mode 100644 tests/test_sample.py\n create mode 100644 tox.ini\n$ git branch -d add_layer_cookiecutter-pypackage-minimal\nDeleted branch add_layer_cookiecutter-pypackage-minimal (was dc62ba1).\n