index

Symbols

@pytest.mark.parametrize decorator 69

Numerics

-3.9 flag 214

A

ABI (Application binary interface) 49

abstract syntax tree 94

actions/checkout action 112

actions/download-artifact action 122

actions/setup-python action 112, 115

actions/upload-artifact action 117 – 118

addopts key 62, 78

ADRs (Architectural decision records) 199

Application binary interface (ABI) 49

args key 174

Art of Unit Testing, The (Osherove) 57

asdf global python command 213

asdf tool 210 – 212

autodoc extension 139

automation

code quality tooling

analyzing type safety 88 – 93

creating tox environment for code formatting 93 – 95

creating tox environment for linting 96 – 98

power of tox environments 83 – 88

continuous integration

converting manual tasks to GitHub Actions 112 – 118

publishing packages 119 – 126

with GitHub Actions 105 – 112

workflow 104

documentation refresh during development 135

extraction of code documentation 135 – 143

Read the Docs builds for GitHub pull requests 152 – 153

standardizing packaging for 5 – 6

updating dependencies automatically with Dependabot 170 – 172

Average of Rates and the Average Rate, The (Lindstrom) 42

B

binary distribution package 22

binary wheel distributions 48 – 50

black package 93 – 95, 159

block expressions 185

boilerplate 180

branch coverage 62 – 63

branch key 62

build backend 23 – 24

builder-inited event 150

build frontend 24

build_sdist hook 24

build-system section 45

build tool 22, 24 – 26, 52, 118

build package 118, 193

installing 216

parts of 22 – 26

build_wheel hook 24

C

calendar versioning 164 – 166

:caption: property 140

C extension 44 – 50

build targets for binary wheel distributions 48 – 50

installing and profiling 47 – 48

integrating Cython into Python package build 45 – 47

source code 44 – 45

specifying required Python versions 50

check-imports environment 88, 99

- -check option 94

check_untyped_defs configuration option 92

CI (Continuous integration) 104

:class: role 154

code of conduct 199 – 200

code quality tooling

analyzing type safety 88 – 93

configuring mypy 91 – 93

creating tox environment for type checking 90 – 91

creating tox environment for code formatting 93 – 95

creating tox environment for linting 96 – 98

power of tox environments 83 – 88

creating nondefault tox environments 83 – 85

managing dependencies across tox environments 85 – 88

cohesion 8 – 9

combinatorial growth 70

command-line tools 50 – 53

commands key 74, 84, 130

commands list 75

community building

conveying project road map, status, and changes 201 – 205

tracking high-level changes in logs 203 – 205

using GitHub labels to track status for individual tasks 201 – 203

using GitHub projects for kanban management 201

establishing, providing, and enforcing code of conduct 199 – 200

gathering consistent information with issue templates 205 – 207

providing supporting documentation for different user types 197 – 199

README needs to make value proposition 196 – 197

consistent language 155

console_scripts group 52

context 156

continuous integration

converting manual tasks to GitHub Actions 112 – 118

building Python package distributions for variety of platforms 117 – 118

running job multiple times with build matrix 114 – 117

publishing packages 119 – 126

with GitHub Actions 105 – 112

starting workflow configuration 109 – 112

terminology 106 – 108

workflow 106

workflow 104

Continuous integration (CI) 104

continuous integration systems 104

cookiecutter 180 – 188

creating cookiecutter configuration 180 – 185

building on previous values 183 – 185

prompting user for input 182 – 183

extracting cookiecutter template from existing project 185 – 188

installing 217

cookiecutter command 183 – 184, 188

cookiecutter variable 185

core metadata

optional 28 – 30

required 26 – 28

coverage, test

increasing 65 – 68

measuring 59 – 65

enabling branch coverage 62 – 63

enabling missing coverage 63 – 64

simplifying coverage report output 64 – 65

thresholding 172 – 173

[coverage:report] section 63, 65, 172

[coverage:run] section 62

- -cov option 60 – 62

cyclomatic complexity 62

Cython 44 – 47

Cython.Build.cythonize function 46

Cython.Coverage plugin 62

cythonize call 46

D

data-driven tests 69 – 70

decomposition 12

decoupling implementation from usage 10 – 12

defensive programming 67

Dependabot 168 – 172

enabling GitHub code scanning 169 – 170

enabling security updates 168 – 169

updating dependencies automatically with 170 – 172

dependencies

dependency hell 162 – 164

direct and indirect 159 – 162

GitHub dependency graph 166 – 168

managing across tox environments 85 – 88

python dependency specifiers and dependency hell 162 – 164

specifying for Python packages 53 – 54

updating automatically with Dependabot 170 – 172

dependency hell 163

deps key 75, 84, 87, 130

deps list 78, 159, 161

devdocs environment 138 – 139, 142

diamond dependency conflicts 163

- -diff option 94

direct dependencies 159

distribution packages 4

__doc__ attribute 136 – 137

docs/conf.py module 139, 143, 151

docs environment 133, 135, 138, 142

docstrings 136

doctest module 157

documentation

best practices 153 – 157

avoiding assumptions and create context 156

creating visual interest and coherent structure 156

powering up documentation 156 – 157

preference of linking over repetition 154 – 155

using consistent, empathetic language 155

what to document 154

philosophy 129 – 130

providing supporting documentation for different user types 197 – 199

publishing to Read the Docs platform 143 – 153

automating Read the Docs builds for GitHub pull requests 152 – 153

configuring Read the Docs 149 – 153

running sphinx-apidoc on Read the Docs 150 – 152

starting with Sphinx 130 – 143

automating documentation refresh during development 135

automating extraction of code documentation 135 – 143

duck typing 88

dynamically typed language 88

E

echo command 110, 112

-e flag 90

empathetic language 155

encapsulation 8 – 9

entry points 50 – 53

environments 72

envlist key 73, 83

evergreen packages

choosing package-versioning strategy 159 – 166

direct and indirect dependencies 159 – 162

python dependency specifiers and dependency hell 162 – 164

semantic versioning and calendar versioning 164 – 166

getting most out of GitHub 166 – 172

GitHub dependency graph 166 – 168

mitigating security vulnerabilities with Dependabot 168 – 172

reducing rework using pre-commit hooks 174 – 176

thresholding test coverage 172 – 173

updating Python syntax using pyupgrade 173 – 174

extensions list 139

F

fail_under key 172

failures 80

file: directive 30

files

controlling file discovery 33 – 35

including non-Python files in package 35 – 37

first-python-package 47, 185

flake8 97 – 98

[flake8] section 97

flake8-bugbear package 97

- -force option 137

format environment 94 – 95, 106, 113

G

get_my_ip environment 84 – 85

GitHub 166 – 172

dependency graph 166 – 168

mitigating security vulnerabilities with Dependabot 168 – 172

enabling Dependabot security updates 168 – 169

enabling GitHub code scanning 169 – 170

updating dependencies automatically with Dependabot 170 – 172

using GitHub labels to track status for individual tasks 201 – 203

using GitHub projects for kanban management 201

GitHub Actions 105 – 112

converting manual tasks to 112 – 118

building Python package distributions for variety of platforms 117 – 118

running job multiple times with build matrix 114 – 117

starting workflow configuration 109 – 112

terminology 106 – 108

workflow 106

GitHub Actions if key 122

GitHub pull requests 152 – 153

Git in Practice (McQuaid) 108

graft directive 45, 92

Grokking Continuous Delivery (Wilson) 104

H

happy path test 66

harmonic_mean function 42 – 44, 47 – 48, 61, 66, 142

harmonic_mean module 42, 44, 47, 142

harmony command 51 – 52, 54, 61, 66 – 67

harmony console script 66

harmony.py module 54, 61, 65 – 67, 70, 91, 142

hello.py module 34 – 36

helpers.py module 8

Hermans, Felienne 129

hooks, pre-commit 174 – 176

hooks key 174

http.server module 134

I

implicit namespace packages 189

- -implicit-namespaces option 137

importlib.metadata.version function 166

importlib module 143

imppkg.harmonic_mean.harmonic_mean function 51

imppkg import package 34 – 35

imppkg package 35, 140

- -index-url flag 193

indirect dependencies 159 – 162

__init__.py module 61, 65, 165, 189

installing

asdf 210 – 212

build 216

C extension 47 – 48

cookiecutter 217

frequent package installation 70 – 74

getting started with tox 70 – 72

tox environment model 72 – 74

pipx 215

pre-commit 217

python-launcher 212 – 214

tox 216 – 217

install_requires key 54, 159, 161, 188

isolated_build key 71

issue templates 205 – 207

K

kanban management 201

L

Labouardy, Mohamed 104

language 155

__len__ method 89

license 31 – 33

Lindstrom, Peter A. 42

line-length option 95, 98

linking 154 – 155

lint environment 97, 106

linting 96 – 98

logs 203 – 205

loose coupling 10

M

main function 51, 61, 65 – 67, 69 – 70, 91

markers key 78

:maxdepth: property 140

max-line-length option 98

mccabe package 97

McQuaid, Mike 108

measuring test coverage 59 – 65

enabling branch coverage 62 – 63

enabling missing coverage 63 – 64

simplifying coverage report output 64 – 65

metadata 26 – 33

optional core metadata 28 – 30

required core metadata 26 – 28

specifying license 31 – 33

[metadata] section 26, 29

missing coverage 63 – 64

- -module-first option 138

modules 140

mypy 90 – 93, 159

[mypy] section 91 – 92

N

name keys 113

namespace packages 188 – 191

namespace_packages 92

namespacing 12

- -no-cov option 62, 81

nondefault tox environments 83 – 85

O

Okken, Brian 57

[options] section 37, 50, 54

[options.entry_points] section 188

Osherove, Roy 57

os.path module 151

- -output-dir flag 117

ownership, code 9 – 10

P

package_import_name variable 187

package management systems 4

package managers 5

packaging 4

parallel test running 76

parameterized tests 57

parametrize marker 78

- -password flag 193

patch changes 164

pathlib module 151

$PATH variable 214

pip 19, 47, 192 – 194

Pipeline as Code (Labouardy) 104

pipx 215

pipx command 215

pipx install command 216 – 217

placeholder expressions expression type 185

platforms 117 – 118

poetry show - -tree command 161

- -port option 135

{posargs} placeholder 74

pre-commit

hooks 174 – 176

installing 217

pre-commit hook id key 174

pre-commit install command 175

pre-commit run - -all-files command 175

pretty configuration option 92

print function 54

private package repository servers 192 – 194

profiling C extension 47 – 48

Programmer’s Brain, The (Herman) 129

publish environment 193

publishing

documentation to Read the Docs platform 143 – 153

automating Read the Docs builds for GitHub pull requests 152 – 153

configuring Read the Docs 149 – 153

running sphinx-apidoc on Read the Docs 150 – 152

packages 119 – 126

py39 environment 88

py command 18, 20, 210, 212, 214

PyCQA (Python Code Quality Authority) 90

pydoc module 130

py -m pip install . command 67

pypa/gh-action-pypi-publish action 122

PyPA (Python Packaging Authority) 4, 216

PYPI_API_TOKEN secret 121

PyPI (Python Package Index) 16, 128

pyproject-build command 22, 45, 52

pytest

ensuring markers are valid 78 – 80

testing framework 57 – 59

pytest command 75, 78

pytest-cov package 60, 87

pytest package 90

pytest-randomly plugin 78

Python build system

build backend 23 – 24

builder-inited event 150

build frontend 24

build_sdist hook 24

build-system section 45

build_wheel hook 24

parts of 22 – 26

python command 113, 210, 214

python dependency specifiers 162 – 164

python-launcher 212 – 214

python matrix factor 115

python -m pip install command 160

python -m pip list command 160

python -m unittest discover command 57

Python packages

authoring package metadata 26 – 33

optional core metadata 28 – 30

required core metadata 26 – 28

specifying license 31 – 33

building Python package distributions for variety of platforms 117 – 118

challenges of sharing software 7

contents of distribution packages 6 – 7

controlling source code and file discovery 33 – 35

creating project template for future packages 180 – 188

creating cookiecutter configuration 180 – 185

extracting cookiecutter template from existing project 185 – 188

how packaging helps you 7 – 13

decoupling implementation from usage 10 – 12

enforcing cohesion and encapsulation through packaging 8 – 9

filling roles by composing small packages 12 – 13

promoting clear ownership of code 9 – 10

including non-Python files in package 35 – 37

managing Python virtual environments 16 – 20

overview 4

Python build workflow 22 – 26

scaling packaging in organization 191 – 194

standardizing packaging for automation 5 – 6

using namespace packages 188 – 191

Python Packaging User Guide 4

python_requires keyword 50

Python Testing with pytest, 2nd Edition (Okken) 57

python_version configuration option 92

python-version key 113

Python virtual environments 16 – 20

pyupgrade 173 – 174

R

- -randomly-seed option 78

random.randint function 43, 48

ratcheting test coverage 172 – 173

README 196 – 197

READTHEDOCS environment variable 151

Read the Docs platform 143 – 153

automating builds for GitHub pull requests 152 – 153

configuring 149 – 153

running sphinx-apidoc on 150 – 152

:ref: role 154

release, GitHub 123

remove_params function 96

rendering context 185

repetition

preference of linking over 154 – 155

repetitive tests 69 – 70

repo key 174

reports, coverage 64 – 65

- -repository flag 193

repos key 174

requests namespace 12

requests package 11 – 13, 16, 19, 84, 88

rev key 174

rm command 193

road maps 201 – 205

tracking high-level changes in logs 203 – 205

using GitHub labels to track status for individual tasks 201 – 203

using GitHub projects for kanban management 201

roles 12 – 13

runs-on key 118

Rust cargo tool 213

S

scaling packaging 191 – 194

- -sdist flag 118

secret context variable 121

security vulnerabilities 168 – 172

enabling Dependabot security updates 168 – 169

enabling GitHub code scanning 169 – 170

updating dependencies automatically with Dependabot 170 – 172

semantic versioning 164 – 166

- -separate option 138

setup function 46, 150

- -setup option 42

setup.py module 46

setup-python action 113, 166

Setuptools 50 – 53

setuptools package 19, 23

setuptools.setup function 46

shipyard package 86

show_error_context configuration option 92

show_missing key 63

site packages directory 16

Sized type 89

skip_covered key 65

skip_install key 85, 95

software, sharing 7

software repositories 5

source code 33 – 35

source distribution package 22

source key 62, 64

specifiers, python dependency 162 – 164

Sphinx 130 – 143

automating documentation refresh during development 135

automating extraction of code documentation 135 – 143

sphinx-apidoc command 137 – 140, 149 – 152

sphinx-autobuild command 135, 139

sphinx-autobuild package 135

sphinx-build command 133

sphinx.ext.autodoc extension 140

sphinx package 130, 135

standardizing packaging for automation 5 – 6

standard library 16

startsWith function 122

stateful tests 77 – 78

static analysis 90

status 201 – 205

tracking high-level changes in logs 203 – 205

using GitHub labels to track status for individual tasks 201 – 203

using GitHub projects for kanban management 201

strategy.matrix key 114

- -strict-markers option 78

str.replace function 184

submodules 140

swimlanes 201

T

target-version 95

templates, project 180 – 188

creating cookiecutter configuration 180 – 185

building on previous values 183 – 185

prompting user for input 182 – 183

extracting cookiecutter template from existing project 185 – 188

termcolor.cprint function 54

termcolor package 54, 90, 159, 162

[testenv] section 74 – 75, 78, 83 – 85

testenv:check-imports environment 87

[testenv:docs] section 130

testenv environment 87

[testenv:format] section 95

[testenv:<name>] section 84

test fixtures 57

test_harmonic_mean.py module 58 – 59, 61, 65, 68

{[testimports]deps} reference 87

[testimports] section 87

testpaths configuration 59

testpaths key 59

test runner 57

test suites

addressing testing tedium 69 – 80

configuring test environments 74 – 76

frequent package installation 70 – 74

repetitive, data-driven tests 69 – 70

tips for quicker and safer testing 76 – 80

integrating testing setup 57 – 68

adding test coverage measurement 59 – 65

increasing test coverage 65 – 68

pytest testing framework 57 – 59

thresholding test coverage 172 – 173

text/markdown content type 30

threat model of decay 170

timeit module 42 – 44

toctree directive 140

[tool:pytest] section 62, 78, 80

tox

analyzing type safety 88 – 93

configuring mypy 91 – 93

creating tox environment for type checking 90 – 91

creating tox environment for code formatting 93 – 95

creating tox environment for linting 96 – 98

environment model 72 – 74

getting started with 70 – 72

installing 216 – 217

power of tox environments 83 – 88

creating nondefault tox environments 83 – 85

managing dependencies across tox environments 85 – 88

running job multiple times with build matrix 114 – 117

tox -e devdocs command 135, 139

tox -e docs command 131

toxenv variable 115

tox package 117

[tox:tox] section 71, 73 – 74

tree command 28

Trigger GitHub Action concept 107

twine 192 – 194

twine upload command 193

typecheck environment 91, 106

types

analyzing type safety 88 – 93

configuring mypy 91 – 93

creating tox environment for type checking 90 – 91

creating tox environment for type checking 90 – 91

types-termcolor package 90

U

unhappy path tests 66 – 68

unittest module 57

updating Python syntax 173 – 174

urllib3 package 92

urllib.request.urlopen utility 12

- -username flag 193

uses key 109

V

variable_one variable 182

variable_two variable 182

vehicle drift 41 – 44

venv 18 – 20

__version__ attribute 165 – 166

versions

choosing package-versioning strategy 159 – 166

direct and indirect dependencies 159 – 162

python dependency specifiers and dependency hell 162 – 164

semantic versioning and calendar versioning 164 – 166

specifying required 50

version variable 115

virtual environments 16, 18 – 20

visual interest 156

W

warn_unused_configs configuration option 92

wheel package 19, 23 – 24

Wilson, Christie 104

with key 113

with.path key 117, 122

Workflow GitHub Action concept 106

working-directory key 113

X

xfail marker 80

xfail_strict key 80