Cookiecutter - Python Glasgow Feb 2016

Cookiecutter is a command-line utility that helps you to start new projects following best practices of the community or simply based on your very own experience.

Authoring templates couldn't be any easier and you absolutely don't need to be an expert in Python. This talk briefly showcases how to do it and use Cookiecutter to greatly simplify the process of starting new projects.

Transcript

1. Cookiecutter
   or what we can learn from templates
   

   View Slide

2. Raphael Pierzina
   Python Glasgow - February, 2016
   

   View Slide

3. Who am I?
   • Night owl, comic lover, overall geek
   • Software Engineer at FanDuel
   • Stuttgart ✈ Edinburgh
   

   View Slide

4. / hackebrot
   @hackebrot
   

   View Slide

5. Open Source Projects
   • Cookiecutter
   • Pytest and plugins
   • Kivy Blueprints
   • … a couple of smaller projects
   

   View Slide

6. View Slide

7. What is Cookiecutter?
   • Command-line utility that helps you to start new projects following
   best practices of the community or simply based on your very own
   experience.
   • Renders templates based on user-input on the CLI
   • Project templates can be in any programming language or markup
   format
   

   View Slide

8. What is Cookiecutter?
   • 100% Python - using click and jinja2
   • Compatible with CPython 2.7, 3.3, 3.4, 3.5 and also PyPy
   • Available on OS X, Linux and Windows
   • Free software, permissive BSD license
   

   View Slide

9. View Slide

10. Community
    • The core committer team is @audreyr, @pydanny, @michaeljoseph,
    @pfmoore, and @hackebrot
    • Close to 3k stars on GitHub, around 12k downloads per month on
    PyPI with 600 templates on GitHub
    • Talks at multiple conferences (PyCon ZA, EuroPython, …)
    • Open Source sponsor for PyCon US 2016
    

    View Slide

11. Why Templates?
    • A great addition to user documentation that you can explore
    • Even in Python we sometimes do the same stuff over and over again
    • Writing scripts is really easy, polishing a package to upload it to PyPI
    can be tricky
    • Some packages require (or recommend) a certain project structure
    and naming convention
    

    View Slide

12. Templates
    • Local templates (that you’ve downloaded or created)
    • Mercurial/Git repositories on BitBucket and GitHub
    

    View Slide

13. Templates
    54 “official” Templates
    Python
    36
    Python C
    C++ C#
    Common Lisp JS
    LaTeX/XeTeX Berkshelf-Vagrant
    HTML Scala
    6502 Assembly Kotlin
    

    View Slide

14. View Slide

15. Installation
    $ pip install cookiecutter # Recommended!
    $ brew install cookiecutter # OS X
    $ apt-get install cookiecutter # Ubuntu
    ...
    

    View Slide

16. CLI or API
    • Python API to run cookiecutter from your own tools
    • Command-line interface using click
    # http://click.pocoo.org/5/python3/
    export LC_ALL=en_US.UTF-8
    export LANG=en_US.UTF-8
    

    View Slide

17. CLI Options
    Usage: cookiecutter [OPTIONS] TEMPLATE
    Create a project from a Cookiecutter project template (TEMPLATE).
    Options:
    -V, --version Show the version and exit.
    --no-input Do not prompt for parameters and only use
    cookiecutter.json file content
    -c, --checkout TEXT branch, tag or commit to checkout after git clone
    -v, --verbose Print debug information
    --replay Do not prompt for parameters and only use
    information entered previously
    -f, --overwrite-if-exists Overwrite the contents of the output directory if
    it already exists
    -o, --output-dir PATH Where to output the generated project dir into
    --config-file PATH User configuration file
    --default-config Do not load a config file. Use the defaults
    instead
    -h, --help Show this message and exit.
    

    View Slide

18. Usage
    $ cookiecutter gh:pytest-dev/cookiecutter-pytest-plugin
    

    View Slide

19. View Slide

20. Demo
    Using Cookiecutter
    

    View Slide

21. cookiecutter.json
    {
    "full_name": "Raphael Pierzina",
    "email": "raphael@hackebrot.de",
    "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": "2.8.1",
    "year": "2015",
    "docs_tool": ["mkdocs", "sphinx", "none"],
    "license": ["MIT", "BSD-3", "GNU GPL v3.0", "Apache Software License 2.0"]
    }
    

    View Slide

22. Template Structure
    cookiecutter-pytest-plugin/
    !"" LICENSE
    !"" Makefile
    !"" README.md
    !"" cookiecutter.json
    !"" docs
    # !"" contributor-guide
    # # !"" documentation.md
    # # $"" quickstart.md
    # !"" index.md
    # $"" user-guide
    # !"" publish-plugin.md
    # $"" quickstart.md
    !"" hooks
    # !"" post_gen_project.py
    # $"" pre_gen_project.py
    !"" mkdocs.yml
    

    View Slide

23. Template Structure
    !"" pytest-{{cookiecutter.plugin_name}}
    # !"" LICENSE
    # !"" README.rst
    # !"" appveyor.yml
    # !"" mkdocs
    # # !"" index.md
    # # $"" mkdocs.yml
    # !"" pytest_{{cookiecutter.module_name}}.py
    # !"" setup.py
    

    View Slide

24. Template Structure
    # !"" sphinxdocs
    # # !"" Makefile
    # # !"" _build
    # # !"" _static
    # # !"" _templates
    # # !"" conf.py
    # # !"" index.rst
    # # $"" make.bat
    # !"" tests
    # # !"" conftest.py
    # # $"" test_{{cookiecutter.module_name}}.py
    # $"" tox.ini
    

    View Slide

25. Template Structure
    !"" tests
    # !"" conftest.py
    # $"" test_create_template.py
    $"" tox.ini
    12 directories, 29 files
    

    View Slide

26. Templated File
    name='pytest-{{cookiecutter.plugin_name}}',
    version='{{cookiecutter.version}}',
    author='{{cookiecutter.full_name}}',
    author_email='{{cookiecutter.email}}',
    maintainer='{{cookiecutter.full_name}}',
    maintainer_email='{{cookiecutter.email}}',
    license='{{cookiecutter.license}}',
    

    View Slide

27. Templated File
    {% if cookiecutter.license == "MIT" -%}
    'License :: OSI Approved :: MIT License',
    {%- elif cookiecutter.license == "BSD-3" -%}
    'License :: OSI Approved :: BSD License',
    {%- elif cookiecutter.license == "GNU GPL v3.0" -%}
    'License :: OSI Approved :: GNU General Public License v3 (GPLv3)',
    {%- elif cookiecutter.license == "Apache Software License 2.0" -%}
    'License :: OSI Approved :: Apache Software License',
    {%- endif %}
    

    View Slide

28. Sphinx Quickstart
    > Root path for the documentation [.]:
    > Separate source and build directories (y/n) [n]: y
    > Name prefix for templates and static dir [_]:
    > Project name: pytest-{{cookiecutter.plugin_name}}
    > Author name(s): {{cookiecutter.full_name}}
    > Project version: {{cookiecutter.version}}
    > Project release [{{cookiecutter.version}}]:
    > Source file suffix [.rst]:
    

    View Slide

29. Jinja2 Template
    {% for item in commands.split(',') -%}
    {% set command = item.strip().lower() %}
    @cli.command('{{command}}', help="Meaningful message here")
    def {{command}}_cmd(*args, **kwargs):
    pass
    {% endfor %}
    

    View Slide

30. Jinja2 Output
    @cli.command('foo', help="Meaningful message here")
    def foo_cmd(*args, **kwargs):
    pass
    @cli.command('bar', help="Meaningful message here")
    def bar_cmd(*args, **kwargs):
    pass
    @cli.command('helloworld', help="Meaningful message here")
    def helloworld_cmd(*args, **kwargs):
    pass
    

    View Slide

31. Demo
    Creating a “HelloWorld” Template
    

    View Slide

32. ~/.cookiecutterrc
    default_context:
    full_name: "Raphael Pierzina"
    email: "raphael@hackebrot.de"
    github_username: "hackebrot"
    abbreviations:
    cookiedozer: https://github.com/hackebrot/cookiedozer.git
    gh: https://github.com/{0}.git
    

    View Slide

33. Showcase User Config
    $ cookiecutter gh:audreyr/cookiecutter-pypackage
    Cloning into 'cookiecutter-pypackage'...
    remote: Counting objects: 505, done.
    remote: Total 505 (delta 0), reused 0 (delta 0), pack-reused 505
    Receiving objects: 100% (505/505), 77.43 KiB | 0 bytes/s, done.
    Resolving deltas: 100% (265/265), done.
    Checking connectivity... done.
    full_name [Raphael Pierzina]:
    email [raphael@hackebrot.de]:
    github_username [hackebrot]:
    project_name [Python Boilerplate]: Test User Config
    repo_name [boilerplate]:
    project_short_description [Python Boilerplate contains all the boilerplate you need to
    create a Python package.]:
    release_date [2015-01-11]:
    year [2015]:
    version [0.1.0]:
    

    View Slide

34. View Slide

35. psst…cibopath
    

    View Slide

36. cibopath
    $ cibopath search django
    cookiecutter-django................. https://github.com/pydanny/cookiecutter-django
    cookiecutter-django-cms............. https://github.com/palazzem/cookiecutter-django-cms
    cookiecutter-django-crud............ https://github.com/wildfish/cookiecutter-django-crud
    cookiecutter-django-lborgav......... https://github.com/lborgav/cookiecutter-django
    cookiecutter-django-paas............ https://github.com/pbacterio/cookiecutter-django-paas
    cookiecutter-django-rest............ https://github.com/agconti/cookiecutter-django-rest
    cookiecutter-django-rest-framework.. https://github.com/jpadilla/cookiecutter-django-rest-framework
    cookiecutter-djangopackage.......... https://github.com/pydanny/cookiecutter-djangopackage
    cookiecutter-simple-django.......... https://github.com/marcofucci/cookiecutter-simple-django
    cookiecutter-wagtail................ https://github.com/torchbox/cookiecutter-wagtail
    wagtail-cookiecutter-foundation..... https://github.com/chrisdev/wagtail-cookiecutter-foundation
    

    View Slide

37. Questions?
    

    View Slide

38. pytest sprint 2016
    https://www.indiegogo.com/projects/
    python-testing-sprint-mid-2016#/
    

    View Slide

39. https://speakerdeck.com/hackebrot
    

    View Slide

40. / hackebrot
    @hackebrot
    

    View Slide