Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/pyscaffold/pyscaffoldext-cookiecutter

:cookie: Extension that combines the flexibility of Cookiecutter templates with the power of PyScaffold.
https://github.com/pyscaffold/pyscaffoldext-cookiecutter

cookiecutter pyscaffold pyscaffold-extension python

Last synced: 2 months ago
JSON representation

:cookie: Extension that combines the flexibility of Cookiecutter templates with the power of PyScaffold.

Awesome Lists containing this project

README 

        
.. image:: https://api.cirrus-ci.com/github/pyscaffold/pyscaffoldext-cookiecutter.svg?branch=master

    :alt: Built Status

    :target: https://cirrus-ci.com/github/pyscaffold/pyscaffoldext-cookiecutter

.. image:: https://readthedocs.org/projects/pyscaffoldext-cookiecutter/badge/?version=latest

    :alt: ReadTheDocs

    :target: https://pyscaffoldext-cookiecutter.readthedocs.io/

.. image:: https://img.shields.io/coveralls/github/pyscaffold/pyscaffoldext-cookiecutter/master.svg

    :alt: Coveralls

    :target: https://coveralls.io/r/pyscaffold/pyscaffoldext-cookiecutter

.. image:: https://img.shields.io/pypi/v/pyscaffoldext-cookiecutter.svg

    :alt: PyPI-Server

    :target: https://pypi.org/project/pyscaffoldext-cookiecutter/

.. image:: https://pepy.tech/badge/pyscaffoldext-cookiecutter/month

    :alt: Monthly Downloads

    :target: https://pepy.tech/project/pyscaffoldext-cookiecutter



==========================

pyscaffoldext-cookiecutter

==========================



    Extension that combines the flexibility of **Cookiecutter** templates

    with the power of **PyScaffold**.



`Cookiecutter`_ is a flexible utility that allows the definition of templates

for a diverse range of software projects.

On the other hand, `PyScaffold`_ is focused in a good out-of-the-box experience

for developing distributable Python packages (exclusively).

Despite the different objectives, it is possible to combine the power of both

tools to create a custom Python project setup.



Quickstart

==========



This extension can be directly installed with ``pip``:



.. code-block:: bash



    pip install pyscaffoldext-cookiecutter



Or, if you prefer ``pipx``:



.. code-block:: shell



    pipx install pyscaffold  # if you haven't installed pyscaffold yet

    pipx inject pyscaffold pyscaffoldext-cookiecutter



Note that, after the installation, ``putup -h`` will show a new option

``--cookiecutter TEMPLATE``.

Use this option to point out which template you want to use (path or url).

The file structure created by `Cookiecutter`_ will be refined by PyScaffold

afterwards.

For example:



.. code-block:: shell



    putup my-proj1 --cookiecutter ~/my-templates/default

    putup my-proj2 --cookiecutter gh:something/from-github



Please refer to `Cookiecutter`_ documentation for more details on possible URLs

and abbreviations.



An additional option ``--cookiecutter-params`` is also added, so you can have

more control over the values `Cookiecutter`_ uses when rendering the templates

(PyScaffold will not run Cookiecutter's interactive prompt).

This option takes the form of a space separated list of ``NAME=VALUE``

arguments as showed in the example bellow:



.. code-block:: bash



    putup mypkg \

      --cookiecutter gh:pyscaffold/cookiecutter-pypackage \

      --cookiecutter-params command_line_interface=Argparse use_pytest=y



Check the ``cookiecutter.json`` file in the repository (or directory) of the template you are

using to see the available parameters.

Please notice PyScaffold already add some default parameters, as indicated in

the section **Suitable Templates** bellow.



Cookiecutter templates with PyScaffold

======================================



The following example shows how to create a new package named ``mypkg``,

that uses a Cookiecutter template, but is enhanced by PyScaffold's features:



.. code-block:: bash



    putup mypkg --cookiecutter gh:pyscaffold/cookiecutter-pypackage



This is roughly equivalent to first create a project using the Cookiecutter

template and convert it to PyScaffold afterwards:



.. code-block:: bash



    cookiecutter --no-input gh:pyscaffold/cookiecutter-pypackage project_name=mypkg

    putup mypkg --force



.. note::

   For complex Cookiecutter templates calling ``cookiecutter`` and ``putup``

   separately may be a better option, since it is possible to answer

   specific template questions or at least set values for Cookiecutter

   variables.



.. warning::

   Although using Cookiecutter templates is a viable solution to customize

   a project that was set up with PyScaffold, the recommended way is to help

   improve PyScaffold by contributing an `extension`_.



.. _suitable-templates:



Suitable templates

------------------



Note that PyScaffold will overwrite some files generated by Cookiecutter,

like ``setup.py``, the ``__init__.py`` file under the package folder

and most of the ``docs`` folder, in order to provide `setuptools-scm`_

and `sphinx`_ integration.

Therefore not all Cookiecutter templates are suitable for this approach.



Ideally, interoperable templates should focus on the file structure inside the

``src`` folder instead of packaging or distributing, since PyScaffold already

handles it under-the-hood. This also means that your template should adhere to

the src-layout if you want to generate files within your Python package.



In addition, PyScaffold runs Cookiecutter with the ``--no-input`` flag

activated and thus the user is not prompted for manual configuration. Instead,

PyScaffold injects the following parameters::



    author

    email

    full_name => same as author

    project_name => the name of the folder where the project will be generated

    repo_name => same as project_name

    package_name => putup's --package (as in `import`)

    namespace => putup's --namespace (if any)

    installable_name => putup's --name (an installable name, like in PyPI/pip install)

    project_short_description => putup's description

    release_date => equivalent to the day you are running putup

    year => equivalent to the year you are running putup



Any extra parameter should be passed using the ``--cookiecutter-params`` option.



Accordingly, the template file structure should be similar to::



    cookiecutter-something/

    └── {{cookiecutter.project_name}}/

        └── src/

            └── {{cookiecutter.package_name}}/

                └── ...



See `Cookiecutter`_ for more information about template creation.



.. note::

   PyScaffold uses Cookiecutter only for its ability to create files.

   Pre/post hooks that perform any other kind of side effect are not

   guaranteed to work.



.. _pyscaffold-notes:



Making Changes & Contributing

=============================



This project uses `pre-commit`_, please make sure to install it before making any

changes::



    pip install pre-commit

    cd pyscaffoldext-cookiecutter

    pre-commit install



It is a good idea to update the hooks to the latest version::



    pre-commit autoupdate



Please also check PyScaffold's `contribution guidelines`_,



Note

====



This project has been set up using PyScaffold 4.1.4. For details and usage

information on PyScaffold see https://pyscaffold.org/.



.. _PyScaffold: https://pyscaffold.org

.. _Cookiecutter: https://cookiecutter.readthedocs.org

.. _setuptools-scm: https://pypi.python.org/pypi/setuptools-scm/

.. _sphinx: https://www.sphinx-doc.org

.. _extension: https://pyscaffold.org/en/latest/extensions.html

.. _pre-commit: https://pre-commit.com/

.. _contribution guidelines: https://pyscaffold.org/en/latest/contributing.html