Skip to content

Commit 3ca9981

Browse files
jonn-smithjonn-smith
committed
Populating template project.
1 parent ca29453 commit 3ca9981

30 files changed

+898
-2
lines changed

‎.bumpversion.cfg

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
[bumpversion]
2+
current_version = 0.0.1
3+
commit = True
4+
tag = False
5+
tag_name = {new_version}
6+
7+
[bumpversion:file:setup.py]
8+
search = version = "{current_version}"
9+
replace = version = "{new_version}"
10+
11+
[bumpversion:file:README.md]
12+
search = Current version: {current_version}
13+
replace = Current version: {new_version}
14+
15+
[bumpversion:file:src/carrot_cli/__main__.py]
16+
search = __version__ = "{current_version}"
17+
replace = __version__ = "{new_version}"

‎.coveragerc

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
[run]
2+
source = carrot_cli
3+
branch = True
4+
5+
[report]
6+
skip_covered = True
7+
exclude_lines =
8+
no cov
9+
no qa
10+
noqa
11+
pragma: no cover
12+
13+
# Don't complain if tests don't hit defensive assertion code:
14+
raise AssertionError
15+
raise NotImplementedError
16+
17+
[html]
18+
directory = coverage_html_report

‎.gitignore

+107
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
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+
.pytest_cache/
49+
50+
# Translations
51+
*.mo
52+
*.pot
53+
54+
# Django stuff:
55+
*.log
56+
local_settings.py
57+
db.sqlite3
58+
59+
# Flask stuff:
60+
instance/
61+
.webassets-cache
62+
63+
# Scrapy stuff:
64+
.scrapy
65+
66+
# Sphinx documentation
67+
docs/_build/
68+
69+
# PyBuilder
70+
target/
71+
72+
# Jupyter Notebook
73+
.ipynb_checkpoints
74+
75+
# pyenv
76+
.python-version
77+
78+
# celery beat schedule file
79+
celerybeat-schedule
80+
81+
# SageMath parsed files
82+
*.sage.py
83+
84+
# Environments
85+
.env
86+
.venv
87+
env/
88+
venv/
89+
ENV/
90+
env.bak/
91+
venv.bak/
92+
93+
# Spyder project settings
94+
.spyderproject
95+
.spyproject
96+
97+
# Rope project settings
98+
.ropeproject
99+
100+
# mkdocs documentation
101+
/site
102+
103+
# mypy
104+
.mypy_cache/
105+
106+
# PyCharm
107+
.idea

‎.isort.cfg

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
[settings]
2+
known_first_party=carrot_cli

‎.pylintrc

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
2+
[TYPECHECK]
3+
# List of members which are set dynamically and missed by pylint inference
4+
# system, and so shouldn't trigger E1101 when accessed. Python regular
5+
# expressions are accepted.
6+
generated-members=pysam*
7+
8+
[MASTER]
9+
disable=
10+
C0330,
11+
C0114,
12+
C0116,
13+
E1136, # known bug in pylint 2.4.4

‎.readthedocs.yml

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# .readthedocs.yml
2+
# Read the Docs configuration file
3+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
4+
5+
# Required
6+
version: 2
7+
8+
# Build documentation in the docs/ directory with Sphinx
9+
sphinx:
10+
configuration: docs/conf.py
11+
12+
# Build documentation with MkDocs
13+
#mkdocs:
14+
# configuration: mkdocs.yml
15+
16+
# Optionally build your docs in additional formats such as PDF and ePub
17+
formats: all
18+
19+
# Optionally set the version of Python and requirements required to build your docs
20+
python:
21+
version: 3.7
22+
install:
23+
- requirements: docs/requirements.txt

‎LICENSE

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
BSD 3-Clause License
2+
3+
Copyright (c) 2019, Broad Institute
4+
All rights reserved.
5+
6+
Redistribution and use in source and binary forms, with or without
7+
modification, are permitted provided that the following conditions are met:
8+
9+
1. Redistributions of source code must retain the above copyright notice, this
10+
list of conditions and the following disclaimer.
11+
12+
2. Redistributions in binary form must reproduce the above copyright notice,
13+
this list of conditions and the following disclaimer in the documentation
14+
and/or other materials provided with the distribution.
15+
16+
3. Neither the name of the copyright holder nor the names of its
17+
contributors may be used to endorse or promote products derived from
18+
this software without specific prior written permission.
19+
20+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

‎MANIFEST.in

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
graft tests
2+
graft src
3+
4+
include README.rst
5+
include LICENSE.txt
6+
include tox.ini .travis.yml
7+
8+
prune **/.hypothesis
9+
10+
global-exclude *.py[cod] __pycache__ *.so *.dylib .DS_Store

‎README.md

+139-2
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,139 @@
1-
# python_cli_template
2-
A template repository for python programs that use a CLI.
1+
# Python CLI Project Template
2+
This template was created so that a new python3 CLI program could be quickly whipped up with a nice infrastructure.
3+
4+
## Acknowledgements
5+
This template is based on several projects that originated at or as part of collaborations involving The Broad Institute of MIT and Harvard.
6+
In particular, the following people were instrumental in those projects:
7+
8+
- Kiran Garimella (@kvg)
9+
- Winni Kretzschmar (@winni2k)
10+
- Karl Johan Westrin (@karljohanw)
11+
12+
## Contents / Features
13+
Included in this template are the following features:
14+
- `click` for argument parsing with examples
15+
- an over-engineered logging module (ensures that all log messages have correct leading whitespace to be column-aligned)
16+
- `tox` setup (linting, black for code formatting, testing)
17+
- examples of tests (already connected to tox for quick starting)
18+
- `.gitignore` for most kinds of local files
19+
- include sort ordering defaults
20+
- a `readthedocs` template
21+
- a `bumpversion` config file
22+
- a `pylint` config file
23+
24+
If you check this out and run `tox` the tests will all pass.
25+
26+
## Make It Your Own
27+
### Required Changes
28+
To make this project-specific, several placeholder values need to be replaced with your content.
29+
30+
| FIELD | DESCRIPTION |
31+
| ----- | ----------- |
32+
| PROJECT\_NAME | The name of your new project / tool. |
33+
| \_SHORT\_PROJECT\_DESCRIPTION\_ | A concise description of your new project / tool. |
34+
| \_AUTHOR\_ | The name of the primary author / point of contact. |
35+
| \_AUTHOR\_EMAIL\_ | The email address of the primary author / point of contact. |
36+
37+
This find/replace will be needed until github [implements template repo variables.](https://github.com/isaacs/github/issues/1716)
38+
39+
However, fear not! I have provided `initialize.sh` for this very purpose. Run it with the following parameters after creating your repo to initialize your specific repository info:
40+
41+
```
42+
./initialize.sh PROJECT_NAME "SHORT PROJECT DESCRIPTION" "AUTHOR NAME" AUTHOR_EMAIL
43+
```
44+
I quoted the fields that are likely to contain spaces - this will be necessary.
45+
46+
### Optional Changes
47+
You may also need to do the following:
48+
- Update the LICENSE file - it defaults to the BSD 3-Clause License.
49+
50+
When you add development dependencies, add them to `dev-requirements.txt`.
51+
52+
When you add testing dependencies, add them to `test-requirements.txt`.
53+
54+
When you add runtime dependencies, add them to `setup.py` in the `install_requires` section.
55+
56+
## General Notes
57+
58+
When running `tox`, you'll notice that the linter runs before black8. This is intentional. Rather than have it blindly reformat your code, I wanted to make sure you knew what you were doing wrong (i.e. against PEP 8 standards). You can configure this order to suit your needs.
59+
60+
Notable projects already using this template are:
61+
- [Cromshell 2.0](https://github.com/broadinstitute/cromshell/tree/cromshell_2.0)
62+
- [CARROT CLI](https://github.com/broadinstitute/carrot_cli)
63+
64+
Lastly, it's worth double-checking everything to make sure you want what's included here.
65+
66+
Below this line begins the project-specific portion of the README that should be modified after creating a new project:
67+
68+
---
69+
70+
# PROJECT\_NAME
71+
\_SHORT\_PROJECT\_DESCRIPTION\_
72+
73+
Current version: 0.0.1
74+
75+
## Installation
76+
77+
pip install .
78+
79+
## Development
80+
81+
To do development in this codebase, the python3 development package must
82+
be installed.
83+
84+
After installation the development environment can be set up by
85+
the following commands:
86+
87+
python3 -mvenv venv
88+
. venv/bin/activate
89+
pip install -r dev-requirements.txt
90+
pip install -e .
91+
92+
### Linting files
93+
94+
# run all linting commands
95+
tox -e lint
96+
97+
# reformat all project files
98+
black src tests setup.py
99+
100+
# sort imports in project files
101+
isort -rc src tests setup.py
102+
103+
# check pep8 against all project files
104+
flake8 src tests setup.py
105+
106+
# lint python code for common errors and codestyle issues
107+
pylint src
108+
109+
### Tests
110+
111+
# run all linting and test
112+
tox
113+
114+
# run only (fast) unit tests
115+
tox -e unit
116+
117+
# run only linting
118+
tox -e lint
119+
120+
Note: If you run into "module not found" errors when running tox for testing, verify the modules are listed in test-requirements.txt and delete the .tox folder to force tox to refresh dependencies.
121+
122+
### Versioning
123+
124+
We use `bumpversion` to maintain version numbers.
125+
*DO NOT MANUALLY EDIT ANY VERSION NUMBERS.*
126+
127+
Our versions are specified by a 3 number semantic version system (https://semver.org/):
128+
129+
major.minor.patch
130+
131+
To update the version with bumpversion do the following:
132+
133+
`bumpversion PART` where PART is one of:
134+
- major
135+
- minor
136+
- patch
137+
138+
This will increase the corresponding version number by 1.
139+

‎dev-requirements.txt

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
isort==4.3.21
2+
tox
3+
wheel
4+
bumpversion
5+
twine
6+
black
7+
flake8
8+
pylint
9+
cython
10+
sphinx
11+
sphinx-rtd-theme
12+
mypy==0.770
13+
click

0 commit comments

Comments
 (0)