.. include:: /extras.rst.txt
.. highlight:: rst
.. index:: cookie-create-pkg ; Index
.. _cookie-create-pkg:
=================================
Create a cookiecutter-py3-package
=================================
|
See a list of the steps below to get up get your Cookiecutter Package up
and running fast.
.. note::
This method allows you to create many packages without the need to
re-create the virtual environments.
For example, a new user may want to generate several packages trying
different options.
More advanced users may choose a different way to structure their virtual
environments.
|
Pre-requisites
==============
`Python 3.6 `_ or greater installed on
your computer.
:ref:`Create a GitHub repository.`
.. _create-cookiecutter-tutorial:
Tutorial
========
Navigate to the folder you wish to create your cookiecutter-py3-package.
Here we are using packages.
.. code-block:: bash
dev@aps1:~/projects/packages$
.. _create-virtual-environemnt:
Create a Virtual Environment
----------------------------
Select the tab for your preferred Operating System.
.. note::
The commands to create a virtual environment below will use the default
Python version in your Operating System.
If you prefer another python version installed on your computer, you can
replace `python3` with `python3.n`, where n is the version number.
.. tab:: Linux
.. code-block:: bash
:caption: **bash/zsh**
python3 -m venv my_venv
You will have a folder structure similar to this.
.. code-block:: bash
packages
└── my_venv
.. tab:: macOS
.. code-block:: bash
:caption: **bash/zsh**
python3 -m venv my_venv
You will have a folder structure similar to this.
.. code-block:: bash
packages
└── my_venv
.. tab:: Windows
If you have installed Python in your PATH and PATHEXT.
.. code-block:: bash
:caption: **cmd/PowerShell**
python3 -m venv my_venv
Otherwise use
.. code-block:: bash
:caption: **cmd/PowerShell**
c:\>c:\Python36\python -m venv c:\path\to\packages\my_env
You will have a folder structure similar to this.
.. code-block:: cmd
packages
└── my_venv
.. _activate-virtual-environemnt:
Activate Virtual Environment
----------------------------
Ensure you are in the same folder as `my_env`. In this example, we are in the
`packages` folder. Use the following command for your Operating System to
activate the virtual environment.
.. tab:: Linux
.. code-block:: bash
:caption: **bash/zsh**
source my_env/bin/activate
.. tab:: macOS
.. code-block:: bash
:caption: **bash/zsh**
source my_env/bin/activate
.. tab:: Windows
.. code-block:: bash
:caption: **cmd**
my_env\Scripts\activate.bat
.. code-block:: bash
:caption: **PowerShell**
my_env\Scripts\Activate.ps1
After activating the virtual environment, your cli will look something like
this, identifying the name of the virtual environment at the start.
.. code-block:: bash
(my_env) dev@aps1:~/projects/packages$
.. _install-cookiecutter:
Install Cookiecutter
--------------------
Firstly it's advisable to upgrade pip using the following command.
.. code-block:: bash
:caption: **Linux, macOS and Windows**
pip install --upgrade pip
You will see something like this in your CLI.
.. code-block:: cmd
Requirement already satisfied: pip in ./my_env/lib/python3.9/site-packages (21.2.3)
Collecting pip
Using cached pip-21.2.4-py3-none-any.whl (1.6 MB)
Installing collected packages: pip
Attempting uninstall: pip
Found existing installation: pip 21.2.3
Uninstalling pip-21.2.3:
Successfully uninstalled pip-21.2.3
Successfully installed pip-21.2.4
Install cookiecutter_ into your virtual environment.
.. code-block:: bash
:caption: **Linux, macOS and Windows**
pip install cookiecutter
You will see something like this in your CLI.
.. code-block:: cmd
Collecting cookiecutter
Using cached cookiecutter-1.7.3-py2.py3-none-any.whl (34 kB)
Collecting jinja2-time>=0.2.0
Using cached jinja2_time-0.2.0-py2.py3-none-any.whl (6.4 kB)
Collecting python-slugify>=4.0.0
Using cached python_slugify-5.0.2-py2.py3-none-any.whl (6.7 kB)
Collecting binaryornot>=0.4.4
Using cached binaryornot-0.4.4-py2.py3-none-any.whl (9.0 kB)
Collecting requests>=2.23.0
Using cached requests-2.26.0-py2.py3-none-any.whl (62 kB)
Collecting poyo>=0.5.0
Using cached poyo-0.5.0-py2.py3-none-any.whl (10 kB)
Collecting six>=1.10
Using cached six-1.16.0-py2.py3-none-any.whl (11 kB)
Collecting click>=7.0
Using cached click-8.0.1-py3-none-any.whl (97 kB)
Collecting Jinja2<4.0.0,>=2.7
Using cached Jinja2-3.0.1-py3-none-any.whl (133 kB)
Collecting chardet>=3.0.2
Using cached chardet-4.0.0-py2.py3-none-any.whl (178 kB)
Collecting MarkupSafe>=2.0
Using cached MarkupSafe-2.0.1-cp39-cp39-manylinux_2_5_x86_64.manylinux1_
x86_64.manylinux_2_12_x86_64.manylinux2010_x86_64.whl (30 kB)
Collecting arrow
Using cached arrow-1.1.1-py3-none-any.whl (60 kB)
Collecting text-unidecode>=1.3
Using cached text_unidecode-1.3-py2.py3-none-any.whl (78 kB)
Collecting idna<4,>=2.5
Using cached idna-3.2-py3-none-any.whl (59 kB)
Collecting charset-normalizer~=2.0.0
Using cached charset_normalizer-2.0.6-py3-none-any.whl (37 kB)
Collecting certifi>=2017.4.17
Using cached certifi-2021.5.30-py2.py3-none-any.whl (145 kB)
Collecting urllib3<1.27,>=1.21.1
Using cached urllib3-1.26.7-py2.py3-none-any.whl (138 kB)
Collecting python-dateutil>=2.7.0
Using cached python_dateutil-2.8.2-py2.py3-none-any.whl (247 kB)
Installing collected packages: six, python-dateutil, MarkupSafe, urllib3,
text-unidecode, Jinja2, idna, charset-normalizer, chardet, certifi, arrow,
requests, python-slugify, poyo, jinja2-time, click, binaryornot, cookiecutter
Successfully installed Jinja2-3.0.1 MarkupSafe-2.0.1 arrow-1.1.1
binaryornot-0.4.4 certifi-2021.5.30 chardet-4.0.0 charset-normalizer-2.0.6
click-8.0.1 cookiecutter-1.7.3 idna-3.2 jinja2-time-0.2.0 poyo-0.5.0
python-dateutil-2.8.2 python-slugify-5.0.2 requests-2.26.0 six-1.16.0
text-unidecode-1.3 urllib3-1.26.7
Check new packages installed into your virtual environment.
.. code-block:: bash
:caption: **Linux, macOS and Windows**
pip freeze
You will see something like this in your CLI.
.. code-block:: cmd
arrow==1.1.1
binaryornot==0.4.4
certifi==2021.5.30
chardet==4.0.0
charset-normalizer==2.0.6
click==8.0.1
cookiecutter==1.7.3
idna==3.2
Jinja2==3.0.1
jinja2-time==0.2.0
MarkupSafe==2.0.1
poyo==0.5.0
python-dateutil==2.8.2
python-slugify==5.0.2
requests==2.26.0
six==1.16.0
text-unidecode==1.3
urllib3==1.26.7
.. _create_package:
Create Your Package
-------------------
In your packages folder, use the following command.
.. code-block:: bash
:caption: **Linux, macOS and Windows**
cookiecutter https://github.com/imAsparky/cookiecutter-py3-package.git
Cookiecutter will ask questions to set your package up.
If you're unsure or don't know what to enter, stick with the defaults.
See :ref:`Prompts` for more details about the prompt options.
.. _an-example-package:
An Example Package
------------------
.. code-block:: cmd
:caption: **An example package created with some non default selections**
(my_env) dev@aps1:~/projects/packages$ cookiecutter
https://github.com/imAsparky/cookiecutter-py3-package
full_name [Mark Sevelj]:
email [mark@example.com]:
github_username [imAsparky]:
project_name [Python 3 Package Boilerplate]: My New Package (NON DEFAULT)
git_project_name [my-new-package]:
project_slug [my_new_package]:
project_short_description [Python 3 Package Boilerplate contains all the boilerplate you need to create a Python package.]: An example package for cookiecutter-py3-package. (NON DEFAULT)
pypi_username [imAsparky]:
version [0.1.0]:
add_pyup_badge [n]: y (NON DEFAULT)
Select command_line_interface:
1 - Click
2 - Argparse
3 - No command-line interface
Choose from 1, 2, 3 [1]:
create_author_file [y]:
create_conventional_commits_edit_message [y]:
create_repo_auto_test_workflow [y]:
create_auto_CHANGELOG [n]:
Select github_CHANGELOG_access_token:
1 - secrets.GITHUB_TOKEN
2 - secrets.CHANGELOG_UPDATE
Choose from 1, 2 [1]:
use_GH_action_semantic_version [y]:
use_pre_commit [y]:
use_GH_custom_issue_templates [y]:
automatic_set_up_git_and_initial_commit [y]:
use_release_to_test_pypi_with_tags [n]: y (NON DEFAULT)
Select open_source_license:
1 - MIT license
2 - BSD license
3 - ISC license
4 - Apache Software License 2.0
5 - GNU General Public License v3
6 - Not open source
Choose from 1, 2, 3, 4, 5, 6 [1]:
(my_env) dev@aps1:~/projects/packages$
.. hint::
See below, notice the project_name format and how cookiecutter-py3-package
automatically formats the name for your GitHub repository and python module
as default inputs.
.. code-block:: cmd
project_name [Python 3 Package Boilerplate]: My New Package
git_project_name [my-new-package]:
project_slug [my_new_package]:
.. new-folder-structure::
Folder Structure
----------------
If you have been following along the Tutorial order, your directory structure
will look something like this.
.. code-block:: cmd
packages
├── my-new-package
│ ├── .git
│ ├── .github
│ ├── AUTHORS.rst
│ ├── CHANGELOG.md
│ ├── CONTRIBUTING.rst
│ ├── LICENSE
│ ├── MANIFEST.in
│ ├── Makefile
│ ├── README.rst
│ ├── docs
│ ├── my_new_package
│ ├── pytest.ini
│ ├── requirements_dev.txt
│ ├── setup.cfg
│ ├── setup.py
│ ├── tests
│ └── tox.ini
└── my_env
├── bin
├── include
├── lib
├── lib64 -> lib
└── pyvenv.cfg
Whats next?
-----------
:ref:`Create your first git push`.
or you can
Check out our other :ref:`Tutorials` for more information on
how to get the most out of your cookiecutter package.
.. _cookiecutter: https://cookiecutter.readthedocs.io/en/1.7.2/installation.html