A starter kit for python packages based on Reece's biocommons starter kit
- namespace packages
- package version directly from tags
- pytest preconfigured, with support for doctests and coverage
- tox preconfigured
- sphinx documentation configured
- unified interface (via Makefile)
- yapf-preconfigured (
make reformat
)
$ git clone [email protected]:reece/geneoscopy.pytemplate.git
$ cd geneoscopy.pytemplate/
$ make devready
$ source venv/3.7/bin/activate
$ git tag 0.1.0
$ ipython
In [1]: import geneoscopy.pytemplate
In [2]: geneoscopy.pytemplate.__version__
Out[2]: '0.1.0'
Notice that the version is pulled automatically from the tag. As soon as a change is made to this README (or any file in the repo), the version is updated automatically.
In [1]: import geneoscopy.pytemplate
In [2]: geneoscopy.pytemplate.__version__
Out[2]: '0.1.1.dev0+gbedcaee.d20191007'
This version indicates that we are developing toward the 0.1.1
release. dev0
indicates that we're 0 commits from that the last
tagged release. The remainder is a unique tag for the current state
of the directory.
The advantage of this method is that git tags and python package versions are guaranteed to be in sync. Furthermore, it also guarantees that PEP440 (version string formats) is used, which is required for downstream packaging tools.
make test
runs package tests and generates a coverage report. For example:
1 $ make test
2 ...
3 ===================================== test session starts =====================================
4 platform linux -- Python 3.7.3, pytest-5.2.1, py-1.8.0, pluggy-0.13.0
5 rootdir: /home/reece/projects/geneoscopy/geneoscopy.pytemplate, inifile: setup.cfg, testpaths: src, tests
6 plugins: cov-2.8.1
7 collected 3 items
8
9 src/geneoscopy/pytemplate/utils.py . [ 33%]
10 tests/test_greeting.py .. [100%]
11
12 ----------- coverage: platform linux, python 3.7.3-final-0 -----------
13 Name Stmts Miss Cover Missing
14 ---------------------------------------------------------------------
15 src/geneoscopy/pytemplate/__init__.py 6 2 67% 5-6
16 src/geneoscopy/pytemplate/__main__.py 33 22 33% 23-24, 27-29, 33-71, 81-85
17 src/geneoscopy/pytemplate/utils.py 6 0 100%
18 ---------------------------------------------------------------------
19 TOTAL 45 24 47%
Lines 9 and 10 indicate source lines being tested. utils.py
is
tested because it contains doctests. test_greeting.py
is tested
because it is in the tests/
and begins with test_
.
When testing, python lines are monitored for execution. If at least one test invokes code on a particular line, it's "covered". The coverage section indicate the number of statement lines, number of lines not covered by tests, percentage that is covered, and which lines are not covered ("missing"). Generally, it's a good idea to write tests to cover lines in the missing column.
This starter kit includes a command line tool,
geneoscopy-pytemplate
. Examples:
$ geneoscopy-pytemplate --help
usage: geneoscopy-pytemplate [-h] [--version] [--verbose] {greet,migrate} ...
geneoscopy pytemplate command-line script
optional arguments:
-h, --help show this help message and exit
--version, -V show program's version number and exit
--verbose, -v
subcommands:
{greet,migrate}
greet print greeting
migrate create/migrate database
$ geneoscopy-pytemplate --version
0.1.1.dev1+gbc021c3.d20191008
$ geneoscopy-pytemplate greet -h
usage: geneoscopy-pytemplate greet [-h] [--lang LANG]
optional arguments:
-h, --help show this help message and exit
--lang LANG, -l LANG language abbreviation (default: en)
$ geneoscopy-pytemplate greet
hello
$ geneoscopy-pytemplate greet -l cn
你好
$ geneoscopy-pytemplate migrate -d postgres://user:pass@localhost:5432/mydb
2019-10-08 22:30:35 geneoscopy.pytemplate.__main__[32266] CRITICAL I'm not really doing anything with postgres://user:pass@localhost:5432/mydb!
The example script also includes logging. Here's the same command as above, but adding -v (verbose) adds INFO-level information. Another -v gives DEBUG logging.
$ geneoscopy-pytemplate -v migrate -d postgres://user:pass@localhost:5432/mydb
2019-10-08 22:30:40 snafu geneoscopy.pytemplate.__main__[32305] CRITICAL I'm not really doing anything with postgres://user:pass@localhost:5432/mydb!
2019-10-08 22:30:40 snafu geneoscopy.pytemplate.__main__[32305] INFO Connecting to postgres://user:pass@localhost:5432/mydb... success
2019-10-08 22:30:40 snafu geneoscopy.pytemplate.__main__[32305] INFO Migrating postgres://user:pass@localhost:5432/mydb... success
make bdist_wheel
builds a Python wheel archive.