Cookiecutter - PyData Berlin 2017

Cookiecutter is a command-line utility that generates projects from templates. You can use Cookiecutter to create new Python projects and to generate the initial code for different types of applications.

In this talk, I will give an introduction to Cookiecutter, how to install it
from PyPI, how to use the CLI and finally how to author your own template.

https://pydata.org/berlin2017/schedule/presentation/49/

Transcript

1. Kickstarting projects with Cookiecutter PyData Berlin - July 1, 2017 Raphael Pierzina
2. Thanks to the organizers for a great event!
3. $ whoami
4. Hi there! I’m Raphael
5. • Maintainer and core developer of Cookiecutter • Contributor to pytest and community person • Creator of the cookiecutter-pytest-plugin template • Software Engineer at moovel Group
6. @hackebrot
7. Agenda 1. What is Cookiecutter? 2. How does Cookiecutter work? 3. Create your own Cookiecutter template 4. Popular Cookiecutter templates 5. Demo: A custom Jupyter widget
8. 1. What is Cookiecutter?
9. @hackebrot
10. @hackebrot
11. $ cookiecutter gh:pytest-dev/cookiecutter-pytest-plugin
12. full_name [Raphael Pierzina]: email [raphael@hackebrot.de]: github_username [hackebrot]: plugin_name [foobar]: emoji module_name [emoji]: short_description [A simple plugin to use with Pytest]: emoji plugin version [0.1.0]: pytest_version [3.1.1]: 3.1.2 Select docs_tool: 1 - mkdocs 2 - sphinx 3 - none Choose from 1, 2, 3 [1]: 1 Select license: 1 - MIT 2 - BSD-3 3 - GNU GPL v3.0 4 - Apache Software License 2.0 5 - Mozilla Public License 2.0 Choose from 1, 2, 3, 4, 5 [1]: 2 INFO:post_gen_project:Moving files for mkdocs. INFO:post_gen_project:Removing all temporary license files INFO:post_gen_project:Removing jinja2 macros py @hackebrot
13. pytest-emoji/ ├── LICENSE ├── MANIFEST.in ├── README.rst ├── appveyor.yml ├── docs │ └── index.md ├── mkdocs.yml ├── pytest_emoji.py ├── setup.py ├── tests │ ├── conftest.py │ └── test_emoji.py └── tox.ini py @hackebrot
14. Project • GitHub: https://github.com/audreyr/cookiecutter • Documentation: https://cookiecutter.readthedocs.io • PyPI: https://pypi.python.org/pypi/cookiecutter @hackebrot
15. Features • Cross-platform: Windows, Mac, and Linux are officially supported • Works with CPython 2.7, 3.3, 3.4, 3.5, 3.6 and PyPy • Project templates can be in any programming language or markup format @hackebrot
16. $ pip install cookiecutter
17. $ brew install cookiecutter
18. $ sudo apt-get install cookiecutter
19. $ conda install -c conda-forge cookiecutter
20. Community • Free and open source software: BSD license • 154 individual contributors from around the world • More than 1000 public templates on GitHub @hackebrot
21. Contributing • Development of Cookiecutter is community-driven • Connect with other Cookiecutter contributors and users on https://gitter.im/audreyr/cookiecutter • Everyone is invited to contribute! @hackebrot
22. 2. How does Cookiecutter work?
23. CLI + Python API • Cookiecutter can be either used as a command- line interface app or as a Python library • Both interfaces support a number of options for controlling the level of verbosity, suppressing user prompting, providing extra context and many other things @hackebrot
24. $ cookiecutter [OPTIONS] TEMPLATE [EXTRA_CONTEXT] ...
25. $ cookiecutter -v --no-input cookiecutter-pytest-plugin license=BSD-3 docs_tool=sphinx
26. # -*- coding: utf-8 -*- from cookiecutter.main import cookiecutter def run_cookiecutter(): template = 'gh:pytest-dev/cookiecutter-pytest-plugin' project_dir = cookiecutter(template) print(f"Project generated in {project_dir}!") if __name__ == '__main__': run_cookiecutter() py @hackebrot
27. Templating with Jinja2 • Jinja2 is a modern and designer-friendly templating language for Python, modelled after Django’s templates. • It is fast, widely used and secure with the optional sandboxed template execution environment @hackebrot
28. # -*- coding: utf-8 -*- import pytest def pytest_addoption(parser): group = parser.getgroup('{{cookiecutter.plugin_name}}') group.addoption( ' --foo', action='store', dest='dest_foo', default='{% now "utc", "%Y" %}', help='Set the value for the fixture "bar".' ) parser.addini('HELLO', 'Dummy pytest.ini setting') py @hackebrot
29. { "full_name": "Raphael Pierzina", "github_username": "hackebrot", "plugin_name": "foobar", "module_name": "{{ cookiecutter.plugin_name|lower|replace('-', '_') }}", "short_description": "A simple plugin to use with Pytest", "version": "0.1.0", "pytest_version": "3.1.1", "docs_tool": ["mkdocs", "sphinx", "none"], "license": [ "MIT", "BSD-3", "GNU GPL v3.0", "Apache Software License 2.0", "Mozilla Public License 2.0" ] } json @hackebrot
30. git + mercurial (+ zip) • Cookiecutter works with local templates on your filesystem or remote Git or Mercurial repositories • Short-hands for GitHub, BitBucket, and GitLab • Open Pull Request for adding support for templates from zip files or zip URLs (#961) @hackebrot
31. 3. Create your own Cookiecutter template
32. Template project • Cookiecutter takes a source directory tree and copies it into your new project • It replaces all the names that it finds surrounded by templating tags {{ and }} with names that it finds in the cookiecutter.json file @hackebrot
33. $ mkdir hello-pydata $ cd hello-pydata $ mkdir {{cookiecutter.project_slug}} $ cd {{cookiecutter.project_slug}} @hackebrot
34. Cookiecutter namespace • Anything inside templating tags can be placed inside a namespace. • cookiecutter.project_slug will be looked up as project_slug in cookiecutter.json @hackebrot
35. $ touch {{cookiecutter.script_name}}.py @hackebrot
36. # -*- coding: utf-8 -*- def hello_pydata(): print('Hello PyData {{cookiecutter.location}}!') if __name__ == '__main__': hello_pydata() py @hackebrot
37. Context • Cookiecutter needs a context file to look up all your templates items • This file goes into our hello-pydata directory, and contains all the names we’ve used @hackebrot
38. $ cd .. $ touch cookiecutter.json @hackebrot
39. { "project_slug": "project", "location": "World", "script_name": "hello_{{cookiecutter.location|lower}}" } json @hackebrot
40. hello-pydata/ ├── cookiecutter.json └── {{cookiecutter.project_slug}} └── {{cookiecutter.script_name}}.py py @hackebrot
41. $ cookiecutter ~/hackebrot/hello-pydata/
42. project_slug [project]: hello-project location [World]: Berlin script_name [hello_berlin]: py @hackebrot
43. hello-project/ !"" hello_berlin.py py @hackebrot
44. $ cd hello-project/ $ python hello_berlin.py Hello PyData Berlin!
46. Jinja2 syntax • {% … %} for statements • {{ … }} for expressions to print the template output • {# … #} for comments not included in the template output @hackebrot
47. Jinja2 control structures • For: Loop over each item in a sequence • If: Test if a variable is defined or if it’s equal to some other value • Macros: Useful to put often used idioms into reusable functions @hackebrot
48. {%- from "macros/rst" import doc_title, doc_subtitle -%} {{ doc_title('pytest-' + cookiecutter.plugin_name) }} rst @hackebrot
49. Jinja2 control structures • Assignments: Assign values to variables • Include: Return a rendered template into the current namespace • … @hackebrot
50. {%- if cookiecutter.license == "MIT" -%} {%- include 'licenses/MIT' %} {%- elif cookiecutter.license == "BSD-3" -%} {%- include 'licenses/BSD-3' %} {%- elif cookiecutter.license == "GNU GPL v3.0" -%} {%- include 'licenses/GPL-3' %} {%- elif cookiecutter.license == "Apache Software License 2.0" -%} {%- include 'licenses/Apache-2' %} {%- elif cookiecutter.license == "Mozilla Public License 2.0" -%} {%- include 'licenses/MPL-2' %} {%- endif -%} txt @hackebrot
51. Jinja2 filters • replace: Return a copy of the value with all occurrences of a substring replaced • lower: Convert a value to lowercase • upper: Convert a value to uppercase @hackebrot
52. { "full_name": "Raphael Pierzina", "github_username": "hackebrot", "plugin_name": "foobar", "module_name": "{{ cookiecutter.plugin_name|lower|replace('-', '_') }}", "short_description": "A simple plugin to use with Pytest", "version": "0.1.0", "pytest_version": "3.1.1", "docs_tool": ["mkdocs", "sphinx", "none"], "license": [ "MIT", "BSD-3", "GNU GPL v3.0", "Apache Software License 2.0", "Mozilla Public License 2.0" ] } json @hackebrot
53. Jinja2 filters • tojson: Dump a structure to a JSON string • sort: Sort an iterable in ascending order by default, or descending with an extra arg. Also allows to sort by an attribute @hackebrot
54. Jinja2 filters • select: Filter a sequence of objects by applying a test to each object • groupby: Group a sequence of objects by a common attribute @hackebrot
55. Jinja2 extensions • jinja2-time: Builtin into cookiecutter to insert a string representation of a datetime object • … • … @hackebrot
56. {#- source: http: //opensource.org/licenses/MIT #} The MIT License (MIT) Copyright (c) {% now 'utc', '%Y' %} {{cookiecutter.full_name}} Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. txt @hackebrot
57. 4. Popular Cookiecutter templates
58. https://github.com/audreyr/ cookiecutter-pypackage @hackebrot
59. cookiecutter-pypackage • Project structure for Python packages • Testing with unittest or pytest • Tox for testing compatibility across Python versions • Sphinx for documentation @hackebrot
60. https://github.com/pydanny/ cookiecutter-django @hackebrot
61. cookiecutter-django • Template for Django 1.10 and Python 3.4 or 3.5 • Optimized development and production settings • tests with unittest or pytest and 100% test coverage • Docker support using docker-compose • Bootstrap, 12-Factor, SSL, many other features @hackebrot
62. https://github.com/pytest-dev/ cookiecutter-pytest-plugin @hackebrot
63. cookiecutter-pytest-plugin • Installable PyPI package with comprehensive README.rst file • Tests for your plugin with tox, pytest, and CI config • Example code for a fixture, a CLI option, and a pytest.ini option • Optional documentation with either Sphinx or MkDocs • Choose from several FOSS licenses @hackebrot
64. https://github.com/pybee/ Python-iOS-template @hackebrot
65. Python-iOS-template • Generates Python apps that will run under iOS • Supports Python 2.7, 3.4, and 3.5 • Works well with the toga GUI toolkit for native iOS widgets @hackebrot
66. 5. Demo: A custom Jupyter widget
67. https://github.com/jupyter- widgets/widget-cookiecutter @hackebrot
69. If you or your company are using Cookiecutter, please support its development! patreon.com/hackebrot @hackebrot
70. @hackebrot