Skip to content

Commit 875bb4f

Browse files
clawsclaws
committed
initial commit
1 parent 6e64118 commit 875bb4f

28 files changed

+1231
-2
lines changed

‎.travis.yml

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
language: python
2+
python:
3+
- 3.6
4+
- pypy3
5+
os:
6+
- linux
7+
git:
8+
depth: 1
9+
before_install:
10+
- pip install pip --upgrade
11+
install:
12+
- "pip install -r requirements.txt"
13+
script:
14+
- "cookiecutter --no-input . package_name=example"
15+
- "cd example"
16+
- "make venv"
17+
- "source ~/.venvs/example/bin/activate"
18+
- "make style"
19+
- "make check_types"
20+
- "make test"
21+
- "make test.verbose"
22+
- "make coverage"
23+
- "make docs"
24+
- "make dist"
25+
- "make dist.test"

‎README.md

-2
This file was deleted.

‎README.rst

+218
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
Cookiecutter Python Project
2+
###########################
3+
4+
This project contains a Cookiecutter template to create new Python 3.6+
5+
projects. This approach takes lots of the boiler plate out of creating new
6+
Python projects.
7+
8+
Cookiecutter is a command-line utility that creates projects from templates.
9+
Cookiecutter lets you to easily and quickly bootstrap a new project from a
10+
template which allows you to skip all manual setup and common mistakes when
11+
starting a new project.
12+
13+
Cookiecutter takes a source directory tree and copies it into your new
14+
project. It replaces all the names that it finds surrounded by templating
15+
tags ``{{`` and ``}}`` with names that it finds in the file
16+
``cookiecutter.json``.
17+
18+
The Python project structure produced by this Cookiecutter template
19+
contains the following items:
20+
21+
- A minimal README.rst file.
22+
- A Makefile that automates common developer tasks, such as:
23+
- Run unit tests.
24+
- Run code coverage checks.
25+
- Run style compliance checks.
26+
- Run type annotations checks.
27+
- Generate documentation.
28+
- Generate, test and upload a project release to PyPI.
29+
- A ``setup.py`` file used to generate project install and releases.
30+
- A ``CONTRIBUTING.rst`` guide. On Github this file is shown when sending
31+
a pull request or an issue. This file gets included in the generated
32+
documentation.
33+
- an empty ``CHANGELOG.rst`` file. This file gets included in the documentation.
34+
- A ``License`` file that defaults to the MIT License. Change this if
35+
you choose a license other than MIT.
36+
- A ``tests`` directory containing a basic unit test (using unittest) and
37+
a shell script that can be used to test a wheel distribution of the
38+
package.
39+
- A ``.travis.yml`` file for continuous integration setup.
40+
- A ``docs`` directory with a pre-configured Sphinx documentation setup. It
41+
contains:
42+
- A minimal index.rst page
43+
- A user focused page containing information such as install, API
44+
and a link to the change log.
45+
- A change log file.
46+
- A developer focused page containing information such as contributing,
47+
testing, code coverage, style compliance, type annotations and
48+
documentation.
49+
- An ``examples`` directory with a minimal example script. This script is
50+
called and tested as part of the unit tests.
51+
52+
It is assumed that the new Python package will eventually be:
53+
54+
- hosted on Github (or perhaps GitLab)
55+
- published to PyPI (using bdist_wheel)
56+
- linked to ReadTheDocs.
57+
58+
The generated docs have some references and links to those sites.
59+
60+
61+
Getting Started
62+
===============
63+
64+
.. _one-time-setup-steps-label:
65+
66+
One Time Setup Steps
67+
--------------------
68+
69+
You need to prepare two locations to store content:
70+
71+
- A place where you store your projects (git repositories). You probably
72+
have a folder for that already (e.g. ``git-repos``). We will call this
73+
location $REPOS_DIR.
74+
75+
- A place to store Python virtual environments. Avoid putting your virtual
76+
environment in your project directory next to your code. This will avoid
77+
accidentally adding venv content to a git change set. We will call this
78+
location $VENVS_DIR.
79+
80+
Create a new virtual environment for cookiecutter and install cookiecutter
81+
using ``pip``:
82+
83+
.. code-block:: console
84+
85+
$ python -m venv $VENVS_DIR/ccenv
86+
$ source $VENVS_DIR/ccenv/bin/activate
87+
(ccenv) $
88+
(ccenv) $ pip install cookiecutter
89+
90+
You are now ready to create a new Python project from the Cookiecutter
91+
template provided by this project.
92+
93+
94+
.. _create-new-project-label:
95+
96+
Create a new project
97+
--------------------
98+
99+
To create a new Python project based on a cookiecutter template simply
100+
navigate to a directory where you want to create the new project (e.g
101+
$REPOS_DIR) and run the ``cookiecutter`` command with this template as a
102+
command line argument.
103+
104+
If you have cloned a local copy of this template you can use that:
105+
106+
.. code-block:: console
107+
108+
(ccenv) $ cookiecutter path/to/cookiecutter-python-project
109+
110+
Alternatively you can create a new project by referencing this template
111+
at Github (where gh is an abbreviated shortened form for Github):
112+
113+
.. code-block:: console
114+
115+
(ccenv) $ cookiecutter gh:claws/cookiecutter-python-project
116+
117+
You will be prompted for input unless you suppress it with --no-input:
118+
119+
- Prompts are the keys in cookiecutter.json.
120+
- Default responses are the values in cookiecutter.json.
121+
- Prompts are shown in order.
122+
123+
You should now have a new Python project. Once you have created the project
124+
you can exit the cookiecutter virtual environment.
125+
126+
.. code-block:: console
127+
128+
(ccenv) $ deactivate
129+
$
130+
131+
132+
Manual Modifications
133+
--------------------
134+
135+
Some aspects of generating a project in a generic approach are not practical
136+
to completely automate so there may be a few steps remaining before you can
137+
use the new project.
138+
139+
- If you specify a license other than MIT then you will need to update the
140+
``LICENSE`` file to contain your license content. By default it contains
141+
a MIT License.
142+
143+
- If you do not plan to publish project artifacts at GitHub, PyPI or
144+
ReadTheDocs then remove any links to those sites. Affected files are:
145+
146+
- README.rst
147+
- setup.py
148+
- docs/source/index.rst
149+
150+
- Update any additional useful classifiers in ``setup.py``. The list of
151+
available classifiers can be found `here <https://pypi.python.org/pypi?:action=list_classifiers>`_.
152+
153+
154+
Example
155+
=======
156+
157+
Below is an example showing exactly how to create a new Python project using
158+
this project. In this case the package is called ``example``.
159+
160+
At this point it is assumed that you have performed the actions outlined in
161+
:ref:`one-time-setup-steps-label`. This provides a virtual environment that
162+
makes cookiecutter available.
163+
164+
Create the ``example`` project using cookiecutter.
165+
166+
.. code-block:: console
167+
168+
(ccenv) $ cookiecutter ../python-project-template
169+
package_name [package_name]: example
170+
package_display_name [example]: Example
171+
package_short_description [A description of the package]: This package provides example capability
172+
version [0.0.1]:
173+
full_name [Your Name]: First Last
174+
email []:
175+
github_user_name [GithubUserName]: flast
176+
github_repo_name [example]:
177+
Select license:
178+
1 - MIT license
179+
2 - BSD license
180+
3 - Apache Software License 2.0
181+
4 - GNU General Public License v3
182+
5 - Not open source
183+
Choose from 1, 2, 3, 4, 5 [1]:
184+
year [2017]:
185+
(ccenv) $ deactivate
186+
187+
Perform initial project checks.
188+
189+
.. note::
190+
191+
The ``make style`` step will raise the following git-related error because the
192+
project is not yet controlled by git. This error will not be seen once the
193+
project is under version control.
194+
195+
.. code-block::
196+
197+
fatal: Not a git repository (or any of the parent directories): .git
198+
199+
.. code-block:: console
200+
201+
$ cd example
202+
$ make venv
203+
...
204+
Enter virtual environment using:
205+
206+
source path/to/venvs/example/bin/activate
207+
208+
$ source path/to/venvs/example/bin/activate
209+
(example) $
210+
(example) $ make style
211+
(example) $ make check_types
212+
(example) $ make test
213+
(example) $ make test.verbose
214+
(example) $ make coverage
215+
(example) $ make docs
216+
(example) $ make docs.serve # in browser navigate to http://localhost:8000/html
217+
(example) $ make dist
218+
(example) $ make dist.test

‎cookiecutter.json

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"package_name": "package_name",
3+
"package_display_name": "{{cookiecutter.package_name}}",
4+
"package_short_description": "A description of the package",
5+
"version": "0.0.1",
6+
"full_name": "Your Name",
7+
"email": "",
8+
"github_user_name": "GithubUserName",
9+
"github_repo_name": "{{cookiecutter.package_name}}",
10+
"license": ["MIT license", "BSD license", "Apache Software License 2.0", "GNU General Public License v3", "Not open source"],
11+
"year": "{% now 'utc', '%Y' %}",
12+
"_extensions": ["jinja2_time.TimeExtension"]
13+
}

‎requirements.txt

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
cookiecutter

‎{{cookiecutter.package_name}}/.coveragerc

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
[run]
2+
branch = True
3+
4+
[report]
5+
exclude_lines =
6+
pragma: no cover
7+
def __repr__
8+
if self.debug
9+
raise AssertionError
10+
raise NotImplentedError
11+
if 0:
12+
if __name__ == .__main__.:
13+
14+
ignore_errors = True

‎{{cookiecutter.package_name}}/.gitignore

+109
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Byte-compiled / optimized / DLL files
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
6+
# C extensions
7+
*.so
8+
9+
# Distribution / packaging
10+
.Python
11+
build/
12+
develop-eggs/
13+
dist/
14+
downloads/
15+
eggs/
16+
.eggs/
17+
lib/
18+
lib64/
19+
parts/
20+
sdist/
21+
var/
22+
wheels/
23+
*.egg-info/
24+
.installed.cfg
25+
*.egg
26+
MANIFEST
27+
28+
# PyInstaller
29+
# Usually these files are written by a python script from a template
30+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
31+
*.manifest
32+
*.spec
33+
34+
# Installer logs
35+
pip-log.txt
36+
pip-delete-this-directory.txt
37+
38+
# Unit test / coverage reports
39+
htmlcov/
40+
.tox/
41+
.coverage
42+
.coverage.*
43+
.cache
44+
nosetests.xml
45+
coverage.xml
46+
*.cover
47+
.hypothesis/
48+
49+
# Translations
50+
*.mo
51+
*.pot
52+
53+
# Django stuff:
54+
*.log
55+
.static_storage/
56+
.media/
57+
local_settings.py
58+
59+
# Flask stuff:
60+
instance/
61+
.webassets-cache
62+
63+
# Scrapy stuff:
64+
.scrapy
65+
66+
# Sphinx documentation
67+
docs/_build/
68+
docs/build/
69+
docs/source/api/
70+
71+
# PyBuilder
72+
target/
73+
74+
# Jupyter Notebook
75+
.ipynb_checkpoints
76+
77+
# pyenv
78+
.python-version
79+
80+
# celery beat schedule file
81+
celerybeat-schedule
82+
83+
# SageMath parsed files
84+
*.sage.py
85+
86+
# Environments
87+
.env
88+
.venv
89+
env/
90+
venv/
91+
ENV/
92+
env.bak/
93+
venv.bak/
94+
95+
# Spyder project settings
96+
.spyderproject
97+
.spyproject
98+
99+
# Rope project settings
100+
.ropeproject
101+
102+
# mkdocs documentation
103+
/site
104+
105+
# mypy
106+
.mypy_cache/
107+
108+
# VSCode
109+
.vscode/

0 commit comments

Comments
 (0)