Boost Your Django DX (Adam Johnson) (Z-Library)

© 2021 Adam Johnson. All rights reserved. Published by Adam’s Web Services Ltd, UK. The moral right of the author has been asserted. See my website at https://adamj.eu for contact details and more information. Written in British English using Oxford spelling, so it’s ”behaviour” with a ”u” and ”opti- mize” with a ”z”. Created with Sphinx. Typeset in PT Sans and Ubuntu Monospace. The mascot in the front cover illustration is Esther the Enhanced Equine, drawn by ka- terinadot on Fiverr. Other illustrations from British Library on Flickr, The Internet Archive on Flickr, or self- made with Acorn and Inkscape. The only authorized vendor or distributor for this product is adamchainz on Gumroad. Dedicated to Lily.

Contents 1 Introduction 1 1.1 About this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1.1 Read in any order . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1.2 Example commands and resources . . . . . . . . . . . . . . . 3 1.1.3 End-of-chapter feedback links . . . . . . . . . . . . . . . . . . 5 1.2 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.3 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2 Virtual environments and dependencies 10 2.1 On tools and choice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.2 Virtual environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.2.1 Create a virtual environment with venv . . . . . . . . . . . . 11 2.2.2 Avoid committing your virtual environment . . . . . . . . . . 12 2.2.3 Activate a virtual environment . . . . . . . . . . . . . . . . . . 13 2.2.4 Deactivate a virtual environment . . . . . . . . . . . . . . . . 14 2.2.5 Maybe use virtualenv instead of venv . . . . . . . . . . . . . . 14 2.3 Pip and extra tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.3.1 Invoke Pip safely . . . . . . . . . . . . . . . . . . . . . . . . . . 16 2.3.2 The problems with pip freeze > requirements.txt . . . . 17 2.3.3 pip-compile: simple dependency management . . . . . . . . 18 2.3.4 Convert an existing requirements.txt file to pip-compile . 19 2.3.5 Add a new dependency with pip-compile . . . . . . . . . . . 22 2.3.6 Remove a dependency With pip-compile . . . . . . . . . . . 24 2.3.7 Upgrade dependencies with pip-compile . . . . . . . . . . . 25 2.3.8 pip-lock: keep all environments up to date . . . . . . . . . . 26 2.4 Dependency management . . . . . . . . . . . . . . . . . . . . . . . . . 29 2.4.1 Stick to a single set of dependencies (probably) . . . . . . . . 29 2.4.2 Pick new dependencies carefully . . . . . . . . . . . . . . . . 30 2.4.3 Set a dependency upgrade schedule . . . . . . . . . . . . . . 31 2.5 Python’s Development Mode . . . . . . . . . . . . . . . . . . . . . . . . 32 2.5.1 Enable development mode . . . . . . . . . . . . . . . . . . . . 32 i

2.5.2 Check if development mode is enabled . . . . . . . . . . . . . 33 2.5.3 When to use development mode . . . . . . . . . . . . . . . . . 33 3 Python shell 35 3.1 The shell command . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 3.1.1 Execute a string with -c . . . . . . . . . . . . . . . . . . . . . 36 3.1.2 Execute a temporary file with -c 'import t' . . . . . . . . . 37 3.2 IPython: a superior Python shell . . . . . . . . . . . . . . . . . . . . . . 37 3.2.1 Install IPython . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 3.2.2 Get help with ? or ?? . . . . . . . . . . . . . . . . . . . . . . . 39 3.2.3 Advanced autocomplete with tab . . . . . . . . . . . . . . . . 40 3.2.4 Reuse results with the output history . . . . . . . . . . . . . . 41 3.2.5 Export and rerun code with the input history . . . . . . . . . 42 3.2.6 Copy in code with multi-line paste and %cpaste . . . . . . . 43 3.2.7 Iterate quickly with autoreload . . . . . . . . . . . . . . . . . 45 3.2.8 List all imported names with %who and %whos . . . . . . . . . 48 3.2.9 Start IPython within your code with IPython.embed() . . . . 49 3.2.10 Benchmark code with %timeit . . . . . . . . . . . . . . . . . . 51 3.3 django-read-only: production data protection . . . . . . . . . . . . . . 52 3.3.1 Quickly toggle read-only mode in IPython with %read_only 54 4 Debuggers 55 4.1 pdb: Python’s built-in debugger . . . . . . . . . . . . . . . . . . . . . . 56 4.1.1 Some initial examples . . . . . . . . . . . . . . . . . . . . . . . 56 4.1.2 Basic commands . . . . . . . . . . . . . . . . . . . . . . . . . . 65 4.1.3 Ways to start pdb . . . . . . . . . . . . . . . . . . . . . . . . . 73 4.1.4 Extend pdb with .pdbrc . . . . . . . . . . . . . . . . . . . . . 78 4.1.5 Write snapshot-style tests quickly with --pdb . . . . . . . . . 81 4.2 ipdb: IPython enhancements to pdb . . . . . . . . . . . . . . . . . . . 84 4.2.1 Extra features . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 4.2.2 Install and use ipdb . . . . . . . . . . . . . . . . . . . . . . . . 86 5 Development server 89 5.1 Django Debug Toolbar: a development boon . . . . . . . . . . . . . . 89 5.1.1 Install and configure . . . . . . . . . . . . . . . . . . . . . . . . 90 5.1.2 Explore the toolbar . . . . . . . . . . . . . . . . . . . . . . . . 90 5.1.3 Find problematic database queries with the SQL panel . . . 97 5.1.4 Trace non-HTML requests with the history panel . . . . . . . 101 5.2 django-browser-reload: automatically reload your browser in devel- opment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 5.2.1 Reloads triggered by template changes . . . . . . . . . . . . . 104 5.2.2 Reloads triggered by static asset changes . . . . . . . . . . . 106 ii

5.2.3 Reloads triggered by code changes . . . . . . . . . . . . . . . 108 5.2.4 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 5.3 Rich: beautiful terminal output . . . . . . . . . . . . . . . . . . . . . . 110 5.3.1 Server logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 5.3.2 Management commands . . . . . . . . . . . . . . . . . . . . . 115 6 Code quality tools 117 6.1 EditorConfig: consistent text editing . . . . . . . . . . . . . . . . . . . 118 6.2 pre-commit: a code quality framework . . . . . . . . . . . . . . . . . . 120 6.2.1 What pre-commit is . . . . . . . . . . . . . . . . . . . . . . . . 121 6.2.2 Install pre-commit . . . . . . . . . . . . . . . . . . . . . . . . . 122 6.2.3 Add a configuration file . . . . . . . . . . . . . . . . . . . . . . 122 6.2.4 Configuration structure . . . . . . . . . . . . . . . . . . . . . . 126 6.2.5 Pin language versions with default_language_version . . . 127 6.2.6 Various ways to run hooks . . . . . . . . . . . . . . . . . . . . 128 6.2.7 Update hooks With pre-commit autoupdate . . . . . . . . . 131 6.2.8 Run pre-commit in CI with pre-commit ci . . . . . . . . . . . 132 6.2.9 Introduce a hook incrementally . . . . . . . . . . . . . . . . . 135 7 Python code quality tools 139 7.1 Black: the uncompromising code formatter . . . . . . . . . . . . . . . 140 7.1.1 How Black formats code . . . . . . . . . . . . . . . . . . . . . 141 7.1.2 Install and configure Black . . . . . . . . . . . . . . . . . . . . 143 7.2 isort: sorted, grouped import statements . . . . . . . . . . . . . . . . 145 7.2.1 isort’s style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 7.2.2 Split from imports one-per-line with force_single_line . . 147 7.2.3 Install and configure isort . . . . . . . . . . . . . . . . . . . . 148 7.2.4 Add or remove imports from every file . . . . . . . . . . . . . 149 7.3 Flake8: an extensible linter . . . . . . . . . . . . . . . . . . . . . . . . 150 7.3.1 Linting examples . . . . . . . . . . . . . . . . . . . . . . . . . . 150 7.3.2 Install and configure Flake8 . . . . . . . . . . . . . . . . . . . 152 7.3.3 flake8-bugbear: extra checks for common problems . . . . . 155 7.3.4 flake8-no-pep420: avoid package problems . . . . . . . . . . 156 7.3.5 Further plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 7.4 pyupgrade: upgrade to the latest Python syntax . . . . . . . . . . . . 158 7.4.1 Some example rewrites . . . . . . . . . . . . . . . . . . . . . . 159 7.4.2 Install and configure . . . . . . . . . . . . . . . . . . . . . . . . 159 7.5 django-upgrade: upgrade to the latest Django features . . . . . . . . 160 7.5.1 Example rewrites . . . . . . . . . . . . . . . . . . . . . . . . . 160 7.5.2 Install and configure . . . . . . . . . . . . . . . . . . . . . . . . 161 8 Further code quality tools 163 iii

8.1 Djade: a template formatter . . . . . . . . . . . . . . . . . . . . . . . . 164 8.1.1 Formatting examples . . . . . . . . . . . . . . . . . . . . . . . 164 8.1.2 Install and configure . . . . . . . . . . . . . . . . . . . . . . . . 165 8.2 Biome: a linter-formatter for CSS, JavaScript, JSON, and more . . . . 166 8.2.1 CSS formatting examples . . . . . . . . . . . . . . . . . . . . . 167 8.2.2 CSS linting examples . . . . . . . . . . . . . . . . . . . . . . . 168 8.2.3 JavaScript formatting examples . . . . . . . . . . . . . . . . . 171 8.2.4 JavaScript linting examples . . . . . . . . . . . . . . . . . . . . 173 8.2.5 JSON, TypeScript, and other languages . . . . . . . . . . . . . 177 8.2.6 Install and configure . . . . . . . . . . . . . . . . . . . . . . . . 179 8.3 ShellCheck: find bugs in your shell scripts . . . . . . . . . . . . . . . . 183 8.3.1 An example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 8.3.2 Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 8.4 blacken-docs: apply Black to documentation . . . . . . . . . . . . . . 186 8.5 pre-commit-hooks: general purpose checks . . . . . . . . . . . . . . . 188 9 Build your own tools 189 9.1 pre-commit’s virtual languages: rapid checks . . . . . . . . . . . . . . 189 9.1.1 Block files based on name with a custom “fail” hook . . . . . 190 9.1.2 Block files based on content with a regular expression hook 192 9.2 Flake8 plugin: custom source code checks . . . . . . . . . . . . . . . . 195 9.2.1 The Abstract Syntax Tree (AST) . . . . . . . . . . . . . . . . . 195 9.2.2 Further AST exploration . . . . . . . . . . . . . . . . . . . . . 197 9.2.3 Plugin structure . . . . . . . . . . . . . . . . . . . . . . . . . . 198 9.2.4 Make a plugin to ban lambda . . . . . . . . . . . . . . . . . . . 199 9.2.5 Test your plugin . . . . . . . . . . . . . . . . . . . . . . . . . . 202 9.2.6 Further reading . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 9.3 Write a custom tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 9.3.1 Replace Django documentation links . . . . . . . . . . . . . . 205 9.3.2 What pre-commit expects of tools . . . . . . . . . . . . . . . . 205 9.3.3 Make a tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 9.3.4 Example usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 9.3.5 Run the tool with pre-commit . . . . . . . . . . . . . . . . . . 209 9.3.6 Add tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 10 Documentation 213 10.1 DevDocs: the free rapid documentation tool . . . . . . . . . . . . . . . 213 10.1.1 Get started and set up Django’s docs . . . . . . . . . . . . . . 214 10.1.2 Perform a basic search . . . . . . . . . . . . . . . . . . . . . . 216 10.1.3 Search a single documentation source . . . . . . . . . . . . . 216 10.1.4 Reset the search box . . . . . . . . . . . . . . . . . . . . . . . 218 10.1.5 Visit the original documentation site . . . . . . . . . . . . . . 218 iv

10.1.6 Download documentation sources for offline use . . . . . . . 219 10.1.7 Useful documentation sources . . . . . . . . . . . . . . . . . . 221 10.1.8 More on DevDocs . . . . . . . . . . . . . . . . . . . . . . . . . 221 10.2 DuckDuckGo: a developer-friendly search engine . . . . . . . . . . . . 222 10.2.1 Access DuckDuckGo . . . . . . . . . . . . . . . . . . . . . . . . 222 10.2.2 Keyboard shortcuts . . . . . . . . . . . . . . . . . . . . . . . . 222 10.2.3 Bangs: shortcuts to other search pages . . . . . . . . . . . . . 223 10.2.4 Instant Answers: expanded results on the first page . . . . . 224 10.3 Bonus Django documentation sites . . . . . . . . . . . . . . . . . . . . 226 10.3.1 Classy Class-Based Views . . . . . . . . . . . . . . . . . . . . . 226 10.3.2 Classy Django Forms . . . . . . . . . . . . . . . . . . . . . . . 227 10.3.3 Template Tags and Filters . . . . . . . . . . . . . . . . . . . . . 228 10.3.4 Classy Django REST Framework . . . . . . . . . . . . . . . . . 229 10.3.5 Awesome Django . . . . . . . . . . . . . . . . . . . . . . . . . . 230 10.3.6 Django TV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 10.3.7 A bonus bonus: django-classy-doc . . . . . . . . . . . . . . . 232 10.4 Wget: download any website . . . . . . . . . . . . . . . . . . . . . . . . 233 10.4.1 Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 10.4.2 How to download a website . . . . . . . . . . . . . . . . . . . 234 10.4.3 Example: the Django REST Framework documentation . . . 234 10.4.4 Read offline documentation with Python’s web server . . . . 236 10.4.5 An explanation of all the flags . . . . . . . . . . . . . . . . . . 237 10.5 Miscellaneous tips and tricks . . . . . . . . . . . . . . . . . . . . . . . . 237 10.5.1 Python documentation . . . . . . . . . . . . . . . . . . . . . . 238 10.5.2 Django documentation . . . . . . . . . . . . . . . . . . . . . . 240 10.5.3 Read the Docs . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 10.5.4 Sphinx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 11 Settings 248 11.1 Structure your settings . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 11.1.1 Use a single settings file with environment variables . . . . 249 11.1.2 Load a .env file locally . . . . . . . . . . . . . . . . . . . . . . 249 11.1.3 Settings in tests . . . . . . . . . . . . . . . . . . . . . . . . . . 251 11.1.4 Group and sort settings . . . . . . . . . . . . . . . . . . . . . . 254 11.1.5 Order INSTALLED_APPS . . . . . . . . . . . . . . . . . . . . . . 254 11.1.6 Use pathlib for BASE_DIR . . . . . . . . . . . . . . . . . . . . 255 11.1.7 A settings file template . . . . . . . . . . . . . . . . . . . . . . 256 11.2 Some settings patterns to avoid . . . . . . . . . . . . . . . . . . . . . . 257 11.2.1 Don’t read settings at import time . . . . . . . . . . . . . . . . 258 11.2.2 Avoid direct setting changes . . . . . . . . . . . . . . . . . . . 259 11.2.3 Don’t import your project settings module . . . . . . . . . . . 260 v

11.2.4 Avoid creating custom settings where module constants would do . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 11.2.5 Avoid creating dynamic module constants instead of settings 261 11.2.6 Name your custom settings well . . . . . . . . . . . . . . . . . 262 11.2.7 Override complex settings correctly . . . . . . . . . . . . . . . 262 11.3 Test your settings file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 11.3.1 Test your settings functions . . . . . . . . . . . . . . . . . . . 264 11.3.2 Test your settings logic . . . . . . . . . . . . . . . . . . . . . . 266 12 Models and migrations 270 12.1 Seed your database with a custom management command . . . . . . 270 12.1.1 Sample data approaches . . . . . . . . . . . . . . . . . . . . . 271 12.1.2 Create a command . . . . . . . . . . . . . . . . . . . . . . . . . 271 12.1.3 Test your command . . . . . . . . . . . . . . . . . . . . . . . . 275 12.2 Factory Boy: easier data generation . . . . . . . . . . . . . . . . . . . . 279 12.2.1 Install and define factories . . . . . . . . . . . . . . . . . . . . 280 12.2.2 Invoke factories . . . . . . . . . . . . . . . . . . . . . . . . . . 281 12.2.3 Use factories in tests . . . . . . . . . . . . . . . . . . . . . . . 282 12.2.4 Use factories in seed_database . . . . . . . . . . . . . . . . . 283 12.2.5 Further features . . . . . . . . . . . . . . . . . . . . . . . . . . 284 12.3 Migration safeguards . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 12.3.1 Test for pending migrations . . . . . . . . . . . . . . . . . . . 285 12.3.2 django-linear-migrations: prevent merge migrations . . . . . 287 13 System checks 291 13.1 How system checks work . . . . . . . . . . . . . . . . . . . . . . . . . . 291 13.1.1 The basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 13.1.2 How to silence checks . . . . . . . . . . . . . . . . . . . . . . . 292 13.1.3 The advantages of checks . . . . . . . . . . . . . . . . . . . . . 293 13.2 Write your own checks . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 13.2.1 How to write a check function . . . . . . . . . . . . . . . . . . 294 13.2.2 How to register a check function . . . . . . . . . . . . . . . . 295 13.2.3 Add a check for Python’s development mode . . . . . . . . . 296 13.2.4 Add a check for model class names . . . . . . . . . . . . . . . 299 13.3 Test your checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 13.3.1 Test the development mode check . . . . . . . . . . . . . . . 302 13.3.2 Test the model name check . . . . . . . . . . . . . . . . . . . . 304 13.4 Further places that checks live . . . . . . . . . . . . . . . . . . . . . . . 308 13.4.1 Model class checks . . . . . . . . . . . . . . . . . . . . . . . . 308 13.4.2 Model field checks . . . . . . . . . . . . . . . . . . . . . . . . . 310 13.5 django-version-checks: keep your environments in sync . . . . . . . . 311 13.5.1 Install and configure . . . . . . . . . . . . . . . . . . . . . . . . 311 vi

13.5.2 Upgrading dependencies . . . . . . . . . . . . . . . . . . . . . 313 14 Outroduction 315 14.1 Further reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 14.2 Thank you . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 vii

Chapter 1 Introduction Kaizen is the Japanese philosophy of constant improvement to a process. It means con- stantly seeking reliability, speed, quality, and other betterments. Every failure is feedback about where the system can be revised. Software development is a unique arena for kaizen. The flexibility of code allows us to refine it constantly at every level. There is no limit to how much better a process can be. When I learned of kaizen, it resonated with me. I started to see every bug and flaw I encountered as an annoyance to be fixed and a chance to rework the process that led to it. I am constantly finding new ways to work smarter. And dear reader, as you’ve picked up this book, I suspect you, too, have an affinity for kaizen. I hope the tools and practices in this book improve your DX (Development Expe- 1

Boost Your Django DX, Release 2024-11-18 rience) with Django for you and those you work with. Moreover, I hope this book inspires you to seek further improvements and contribute to our wonderful Django ecosystem. 1.1 About this book DX is a broadly applicable term. Many things can improve your development experience, from a smooth keyboard to a supportive team to humorous “Looks Good To Me” memes. But in this book, we’ll focus on tools and practices. This book is meant to serve as many situations as possible. We will primarily cover open source, cross-platform tools. We won’t look at any particulars of writing “normal” Django code. We’re working at the level above: improvements to the process, not the process itself. We will focus on Django projects instead of third-party packages published on PyPI. But packages overlap with projects, so most of the tools we’ll look at apply; there are others we won’t touch on. We’ll not cover anything specific to text editors, JavaScript frameworks, or production environments. These worlds are too varied to cover much ground in one book. But please do seek process improvements in these areas. 1.1.1 Read in any order This book coversmany different areas: virtual environments, the Python shell, debugging, code quality tools, documentation, settings, models, migrations, and system checks. This order is somewhat arbitrary and may not be the most effective order for you to read it in. As such, this book is structured to be read in pretty much any order you like, which sections cross-referencing each other as needed. Browse the table of contents and pick whatever seems most beneficial to you right now. Learn a tool or practice, understand its why, try it out, and iterate. And don’t believe anything covered in this book is “the best” way to do it. It’s only based on this one author’s knowledge, at one point in time. There are many tools and practices out there, many of which I haven’t had a chance to try, or maybe never heard of. Follow Bruce Lee’s advice: “Absorb what is useful, discard what is useless, and add what is specifically your own”. 2 Chapter 1. Introduction

Boost Your Django DX, Release 2024-11-18 1.1.2 Example commands and resources This book contains many code examples. Here are some details about them. resources.zip This book comes with a zip file called resources.zip, containing various example files. Sections refer to specific files when relevant, allowing you to read their contents and copy from them. Versions Examples have been prepared with Python 3.13 and Django 5.1. Generally, the tools we’re looking at should work with any recent, supported version. Where there’s a more specific version constraint, I’ll mention it. Commands Example shell commands look like this: $ python --version Python 3.13.0 The $ represents the prompt - this is not part of the command, so don’t type it. Most commands should work on any platform or shell, but somemore complicated exam- ples use Bash/Zsh-specific features. If you use a different shell, you may need to adapt. Snipping Some examples have “snipped” code or output, in which irrelevant details have been re- placed with ... (an ellipsis). For example, the following list of subcommands is snipped: $ ./manage.py --help Type 'manage.py help <subcommand>' for help on a specific subcommand. Available subcommands: [django] check ... testserver 1.1. About this book 3

Boost Your Django DX, Release 2024-11-18 In Python code, ... is also syntactically valid—it’s the rarely needed Ellipsis object1. In the examples here, this never has any meaning except for snipping. Source control Some sections presume that you’re using Git for source control. And one tool we’ll look at, pre-commit, only works with Git. You’ll need to adapt if you’re using a different source control tool. As a minority in the current development ecosystem, you’re probably already used to this. If you’re not using source control, that gives me a “yikes” reaction (and emailing zip files doesn’t count). Using source control will probably help your development experience more than any of the tools in this book. Try learning Git: an excellent place to start is GitHub’s Git Handbook2. If you do use Git, check out my book Boost Your Git DX3 for Git DX tips. Django projects Example projects use my “simple” startproject template4, which uses this directory struc- ture: . ├── example │ ├── __init__.py │ ├── models.py │ ├── tests │ │ ├── __init__.py │ │ └── test_models.py │ ├── settings.py │ └── urls.py └── manage.py This layout is slightly different to Django’s standard startproject template. The whole project lives inside a single Python package called example, which is also an app contain- ing models and tests. Compare this with the Django default, where apps live in modules that are peers to the “project app” that contains only settings. The single package layout hopefully makes the examples more straightforward to understand. 1 https://docs.python.org/3/library/stdtypes.html#bltin-ellipsis-object 2 https://docs.github.com/en/get-started/using-git 3 https://adamchainz.gumroad.com/l/bygdx 4 https://github.com/adamchainz/django-startproject-templates#simple 4 Chapter 1. Introduction

Boost Your Django DX, Release 2024-11-18 For simplicity, the example projects have some insecure settings (DEBUG = True, ALLOWED_HOSTS = ["*"], a hard coded SECRET_KEY, etc.). Avoid copying those bits into your own projects, and remember to run through Django’s deployment checklist5 when- ever you set up a new production environment. Related blog posts Many sections in this book are also available as blog posts. In such cases, the section starts with a link to the post saying: “Blog post version of this section”. Share this link with others to show them that part of the book. 1.1.3 End-of-chapter feedback links Each chapter ends with a link saying: Leave feedback for this chapter Click these links to open the chapter-specific feedback form. Please let me know your thoughts, as they will help me improve the book. You can also contact me directly with the details on my contact page6. 1.2 Acknowledgements Thank you to everyone who has helpedme assemble this book. It results frommany years of working with Django, so I can’t possibly cover everyone. I’ve been influenced by all of my friends in the Python and Django worlds, anyone whose talk I attended, and everyone I’ve worked with. Many others have created, maintained, or contributed to all the tools mentioned. I’m thankful for all this work and truly enjoy being part of this community. Thank you to these readers who sent me feedback: • Andy Ide • Anthony Sottile • Antoni Aloy • Baptiste Mispelon • Brand Datwyler • Carles Pina i Estany 5 https://docs.djangoproject.com/en/stable/howto/deployment/checklist/ 6 https://adamj.eu/contact/ 1.2. Acknowledgements 5

Boost Your Django DX, Release 2024-11-18 • David Smith • Jeff Triplett • Kevin Wetzels • Mark Walker • Markus Holtermann • Mateusz Bełczowski • Neil Bachelor • Peter Böttges • Rolo Mawlabaux • Ryan Cheley • Sarah Abderemane • Steven Mapes • Thomas Güttler For hosting me on the Django Chat podcast, I send thanks to Carlton Gibson and Will Vincent. For recently working withme and allowingme to think about DX, I’d like to thank Chris Darby and all of ev.energy, Rupert Baker, Charlie Shufeldt, and Jeroen Janssens. I would also like to thankmy partner, Mafalda, for providing unwavering love and support, especially through difficult times. And similarly, I am grateful for the support of my parents, brother, sister-in-law, mother-in-law, and extended family. For wake-up calls and energizing morning walkies, I thank Kevin, the puppy. And finally, thank you, dear reader, for purchasing this book. I hope you learn a lot. 1.3 Changelog 2024-11-18 • Restructured the book: – The first and last chapters are now called “Introduction” and “Outroduction”, for consistency with my other books. – The documentation chapter has moved from the start of the book to the mid- dle, to make the start more exciting. 6 Chapter 1. Introduction

Boost Your Django DX, Release 2024-11-18 – The code quality tools chapters have been reorganized, spreading the content from two chapters to three, with a new chapter titled “Python code quality tools”. • Upgraded to Python 3.13 and Django 5.1. • Added a chapter on debuggers, covering ways to use pdb and ipdb within your Django project. Previously, the IPython section had a short mention of ipdb, with the sentence: pdb is fantastic and worth learning, but that’s for another book or blog post… Well, that’s not in another book or blog post, it’s here now. Enjoy and happy de- bugging. • Added a section on Djade, my new tool for formatting Django templates. • Added a section on Biome, a formatter and linter for CSS, JavaScript, JSON, Type- Script, and more. This tool replaces my recommendations for ESLint and Prettier, which have been removed per the below release notes. • Added a section on IPython’s %who and %whos magic commands. • Updated the isort section to cover the force_single_line option. • Updated the Flake8 section to demonstrate some rules and recommend disabling E501, the maximum line length rule. I don’t think it’s worth the effort to fix or individually ignore most “line too long” errors. • Added Django TV7 and django-classy-doc8 to Bonus Django documentation sites. • Edited the Black section to cover setting the target version with project. requires-python, rather than tool.black.target-version. • Removed the section on reorder-python-imports9. Unfortunately, it is incompatible with Black version 24, with no fix planned. I recommend using isort instead, which is Black-compatible and can apply a similar style with the force_single_line op- tion. • Removed the (rather small) section on Mypy. It didn’t really provide much value. • Removed the section on DjHTML10. Whilst still a nice tool, its indentation modifi- cation can break some whitespace-sensitive contexts, such as <pre> tags. Also it 7 https://djangotv.com 8 https://pypi.org/project/django-classy-doc/ 9 https://github.com/asottile/reorder-python-imports 10 https://github.com/rtts/djhtml 1.3. Changelog 7

Boost Your Django DX, Release 2024-11-18 removes formatting indentation from inline JavaScript, often used with frameworks like Alpine.js. • Removed the section on ESLint11. It no longer operates correctly under pre-commit since its version 9 release, and I recommend using Biome instead. • Removed the section on Prettier12. Its pre-commit hook is no longer maintained, and I recommend using Biome instead. 2024-01-16 • Upgraded to Python 3.12 and Django 5.0. • Added a section on Django’s shell command, covering a couple of ways to use its -c option. • Added a section on IPython’s autoreload extension, a neat tool for incremental de- velopment. Thanks to Matt Segal for the inspirational tweet13. • Added a section on IPython’s embed function, a great way to work “within” your live code. Thanks to Luke Plant for the inspirational blog post14. • Edited Virtual environments to recommend the name .venv for virtual environment directories, rather than venv. Using a dot prefix hides the directory, keeping the virtual environment files out of the way. This change aligns the book with Brett Cannon’s advice and the VS Code default. • Edited Create a virtual environment with venv to use only one venv command. The previous command to upgrade setuptools and wheel is no longer required as Pip now installs the latest versions when necessary. • Edited the Black section to use the new pre-commit repository: https://github. com/psf/black-pre-commit-mirror. This repository installs the compiled version of Black, which is about two times faster. • Edited the ESLint section to use its new “flat” configuration format. • Edited Settings in tests to replace pytest-is-running with a check in sys.modules. This is good enough for most projects, and I’ve retired the pytest-is-running pack- age accordingly. • Edited Test your settings logic to replace the custom reimport_module() with Python’s built-in import_fresh_module(). This function can be used to test a mul- tiple settings file approach. 11 https://eslint.org/ 12 https://prettier.io/ 13 https://x.com/mattdsegal/status/1551056308585234433 14 https://lukeplant.me.uk/blog/posts/repl-python-programming-and-debugging-with-ipython/ 8 Chapter 1. Introduction

Boost Your Django DX, Release 2024-11-18 • Removed the core app from the example projects. Instead, the example module is itself an app. This change means the projects have fewer files, hopefully making them easier to understand. • Removed the Watchman section. pywatchman 1.4.1 does not work with Python 3.10+ (Issue #97015). • Removed the curlylint section. This tool has not seen any maintenance for over a year, has always been advertised as experimental, and can be pretty slow. • Removed the “Disallow auto-named migrations” section (which was based on a previous blog post16). This advice no longer applies since Django 4.0 improved the automatic migration naming behaviour (in Ticket #3151617). If you previously followed the section and overrode the makemigrations command to require -n (--name), you can remove that on newer Django versions. • Improved grammar and tone throughout. 2022-01-10 • Initial release! Leave feedback for this chapter18 15 https://github.com/facebook/watchman/issues/970 16 https://adamj.eu/tech/2020/02/24/how-to-disallow-auto-named-django-migrations/ 17 https://code.djangoproject.com/ticket/31516 18 https://rb.adamj.eu/f/byddx/2024-11-18/1/Introduction/24ffdbd08c/ 1.3. Changelog 9

Chapter 2 Virtual environments and dependencies The magic of development happens in your local virtual environment. As such, managing your environment well can smooth out the development process. In this chapter, we’ll cover tool choice, creating environments, managing dependencies, and using Python’s development mode. 10

Boost Your Django DX, Release 2024-11-18 2.1 On tools and choice There is an abundance of tools out there for managing Python environments, such as Conda, Poetry, and Pipenv. It’s great to see such innovation, and clearly, these tools help scratch particular itches. That said, I prefer to stick to Python’s default tools. That means venv, Pip, and a few extras. I prefer using these default tools for a few reasons. First, using the default tools makes onboarding new developers to a project easier. Be- ginner tutorials start with venv and Pip, so every Python developer has some familiarity with them. When developers with various skill levels join your project, using the lowest common denominator eases the process. Second, the default tools support more use cases. As the universal installation tool, Pip has to cover all bases. This is not the case for other tools. They may provide a shiny interface that works 99% of the time but occasionally requires you to use a workaround for niche problems (perhaps invoking Pip directly!). Third, there are fewer layers to “go wrong”. We seem inevitably doomed to face the unentertaining challenge of debugging a broken environment. With only venv and Pip involved, there are fewer moving pieces to inspect. Since other tools are built on top of venv and Pip, they have more parts to worry about. So anyway, those are my reasons. If your preferences differ, that’s fine. Ultimately, use the tools you and your team are comfortable with. In this chapter, we’ll look at using the default tools venv and Pip, plus some extras. If you use other tools, that’s fine - you can still pick up some principles on the way. 2.2 Virtual environments The first step for any project is to create a virtual environment to isolate its dependencies. Although you’ve probably set up an environment before, we’ll start from scratch here, so we cover all the basics. Let’s look at creating, activating, and deactivating virtual environments and venv versus virtualenv. 2.2.1 Create a virtual environment with venv Create a snazzy virtual environment with: python -m venv --prompt . --upgrade-deps .venv 2.1. On tools and choice 11