Dependency choices

A lot of the value derived from this package is provided by its dependencies, and this section explains the reasoning behind the choices.

Note

The notes here aren’t meant to be unbiased, and you should use whatever works for you. I keep it here mainly as a reference for myself.

The following headings are references to the extras identifiers for the given functionality.

colour

click>=7.0

See Why require click just for jnrbase[colour]?.

doc

Sphinx is a no-brainer. There is simply no better documentation generator. Built on a base of simple, stable choices, like jinja2 and pygments.

sphinx_rtd_theme is the theme used by the excellent Read the Docs site, and having local builds closely mirror hosted documentation is clearly a good call.

iso_8601

ciso8601>=2.1

ciso8601 is an extremely fast parser for ISO-8601 compatible dates and datetimes. It is hundreds of times faster than many alternatives, and thousands of times faster than some.

$ dt="2017-11-11T07:29:13
$ python -m timeit -s 'from parsedatetime import Calendar; p = Calendar()' \
    "p.parse('$dt')"
1000 loops, best of 3: 544 usec per loop
$ python -m timeit -s 'from dateutil import parser' "parser.parse('$dt')"
10000 loops, best of 3: 199 usec per loop
$ python -m timeit -s 'from datetime import datetime' \
    "datetime.strptime('$dt', '%Y-%m-%dT%H:%M:%S')"
10000 loops, best of 3: 48.7 usec per loop
$ python -m timeit -s 'from pyrfc3339 import parse' "parse('${dt}Z')"
10000 loops, best of 3: 40.6 usec per loop
$ python -m timeit -s 'from ciso8601 import parse_datetime' \
    "parse_datetime('2017-11-11T07:29:13')"
1000000 loops, best of 3: 0.573 usec per loop

I really can’t recommend it enough, especially as it will force you to use standardised timestamps in your applications.

template

click>=7.0
html2text>=2020.1.16
Jinja2>=2.10.2
Pygments>=2.5

See Why require click just for jnrbase[colour]?.

html2text was chosen as it supports the systems I use, and is packaged by the major distributions. An alternative that produced reST would be taken in a heartbeat.

jinja2 is the only choice for templating in my eyes. Not only is the package well designed, it is also already in use by many of the projects I use via Sphinx.

Pygments is without contenders. It has lexers for basically every language imaginable, and an enormous number of styles.

test

hiro>=0.5
hypothesis>=5.5
# hiro explicitly requires mock, and not Python 3’s unittest.mock
mock>=2.0
pytest>=5.3
pytest-cov>=2.8
pytest-randomly>=3.2

hiro is a cool little package for modifying system time for use in tests, and works really well. If you need to fiddle the time thousands of times in a testsuite then libfaketime may be a better choice, but for regular use hiro is great.

Over the years I’ve been the umpire of a ping pong championship between nose2 and pytest. I prefer nose2 over pytest in almost every way, but it isn’t maintained that well. There have been times in the past where the pinned six dependency has broken nose2 for pip users and as I write this it doesn’t work with current Python releases.

Once you’ve chosen pytest jump straight on pytest-cov, and pytest-randomly. coverage is obviously important, and randomising test order to shake out unstated dependencies is cheap way to improve test trustworthiness.