Boost Your Django DX updated again

Changelog

• 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 middle, to make the start more exciting.
  • 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 debugging.

• 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, TypeScript, 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 TV and django-classy-doc 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-imports. 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 option.

• Removed the (rather small) section on Mypy. It didn’t really provide much value.

• Removed the section on DjHTML. Whilst still a nice tool, its indentation modification can break some whitespace-sensitive contexts, such as <pre> tags. Also it removes formatting indentation from inline JavaScript, often used with frameworks like Alpine.js.

• Removed the section on ESLint. It no longer operates correctly under pre-commit since its version 9 release, and I recommend using Biome instead.

• Removed the section on Prettier. Its pre-commit hook is no longer maintained, and I recommend using Biome instead.

Table of contents

1. Introduction
   1. About this book
      • Read in any order
      • Example commands and resources
      • End-of-chapter feedback links
   2. Acknowledgements
   3. Changelog
2. Virtual environments and dependencies
   1. On tools and choice
   2. Virtual environments
      • Create a virtual environment with venv
      • Avoid committing your virtual environment
      • Activate a virtual environment
      • Deactivate a virtual environment
      • Maybe use virtualenv instead of venv
   3. Pip and extra tools
      • Invoke Pip safely
      • The problems with pip freeze > requirements.txt
      • pip-compile: simple dependency management
      • Convert an existing requirements.txt file to pip-compile
      • Add a new dependency with pip-compile
      • Remove a dependency With pip-compile
      • Upgrade dependencies with pip-compile
      • pip-lock: keep all environments up to date
   4. Dependency management
      • Stick to a single set of dependencies (probably)
      • Pick new dependencies carefully
      • Set a dependency upgrade schedule
   5. Python’s Development Mode
      • Enable development mode
      • Check if development mode is enabled
      • When to use development mode
3. Python shell
   1. The shell command
      • Execute a string with -c
      • Execute a temporary file with -c 'import t'
   2. IPython: a superior Python shell
      • Install IPython
      • Get help with ? or ??
      • Advanced autocomplete with tab
      • Reuse results with the output history
      • Export and rerun code with the input history
      • Copy in code with multi-line paste and %cpaste
      • Iterate quickly with autoreload
      • List all imported names with %who and %whos
      • Start IPython within your code with IPython.embed()
      • Benchmark code with %timeit
   3. django-read-only: production data protection
      • Quickly toggle read-only mode in IPython with %read_only
4. Debuggers
   1. pdb: Python’s built-in debugger
      • Some initial examples
      • Basic commands
      • Ways to start pdb
      • Extend pdb with .pdbrc
      • Write snapshot-style tests quickly with --pdb
   2. ipdb: IPython enhancements to pdb
      • Extra features
      • Install and use ipdb
5. Development server
   1. Django Debug Toolbar: a development boon
      • Install and configure
      • Explore the toolbar
      • Find problematic database queries with the SQL panel
      • Trace non-HTML requests with the history panel
   2. django-browser-reload: automatically reload your browser in development
      • Reloads triggered by template changes
      • Reloads triggered by static asset changes
      • Reloads triggered by code changes
      • Installation
   3. Rich: beautiful terminal output
      • Server logs
      • Management commands
6. Code quality tools
   1. EditorConfig: consistent text editing
   2. pre-commit: a code quality framework
      • What pre-commit is
      • Install pre-commit
      • Add a configuration file
      • Configuration structure
      • Pin language versions with default_language_version
      • Various ways to run hooks
      • Update hooks With pre-commit autoupdate
      • Run pre-commit in CI with pre-commit ci
      • Introduce a hook incrementally
7. Python code quality tools
   1. Black: the uncompromising code formatter
      • How Black formats code
      • Install and configure Black
   2. isort: sorted, grouped import statements
      • isort’s style
      • Split from imports one-per-line with force_single_line
      • Install and configure isort
      • Add or remove imports from every file
   3. Flake8: an extensible linter
      • Linting examples
      • Install and configure Flake8
      • flake8-bugbear: extra checks for common problems
      • flake8-no-pep420: avoid package problems
      • Further plugins
   4. pyupgrade: upgrade to the latest Python syntax
      • Some example rewrites
      • Install and configure
   5. django-upgrade: upgrade to the latest Django features
      • Example rewrites
      • Install and configure
8. Further code quality tools
   1. Djade: a template formatter
      • Formatting examples
      • Install and configure
   2. Biome: a linter-formatter for CSS, JavaScript, JSON, and more
      • CSS formatting examples
      • CSS linting examples
      • JavaScript formatting examples
      • JavaScript linting examples
      • JSON, TypeScript, and other languages
      • Install and configure
   3. ShellCheck: find bugs in your shell scripts
      • An example
      • Install
   4. blacken-docs: apply Black to documentation
   5. pre-commit-hooks: general purpose checks
9. Build your own tools
   1. pre-commit’s virtual languages: rapid checks
      • Block files based on name with a custom “fail” hook
      • Block files based on content with a regular expression hook
   2. Flake8 plugin: custom source code checks
      • The Abstract Syntax Tree (AST)
      • Further AST exploration
      • Plugin structure
      • Make a plugin to ban lambda
      • Test your plugin
      • Further reading
   3. Write a custom tool
      • Replace Django documentation links
      • What pre-commit expects of tools
      • Make a tool
      • Example usage
      • Run the tool with pre-commit
      • Add tests
10. Documentation
    1. DevDocs: the free rapid documentation tool
       • Get started and set up Django’s docs
       • Perform a basic search
       • Search a single documentation source
       • Reset the search box
       • Visit the original documentation site
       • Download documentation sources for offline use
       • Useful documentation sources
       • More on DevDocs
    2. DuckDuckGo: a developer-friendly search engine
       • Access DuckDuckGo
       • Keyboard shortcuts
       • Bangs: shortcuts to other search pages
       • Instant Answers: expanded results on the first page
    3. Bonus Django documentation sites
       • Classy Class-Based Views
       • Classy Django Forms
       • Template Tags and Filters
       • Classy Django REST Framework
       • Awesome Django
       • Django TV
       • A bonus bonus: django-classy-doc
    4. Wget: download any website
       • Install
       • How to download a website
       • Example: the Django REST Framework documentation
       • Read offline documentation with Python’s web server
       • An explanation of all the flags
    5. Miscellaneous tips and tricks
       • Python documentation
       • Django documentation
       • Read the Docs
       • Sphinx
11. Settings
    1. Structure your settings
       • Use a single settings file with environment variables
       • Load a .env file locally
       • Settings in tests
       • Group and sort settings
       • Order INSTALLED_APPS
       • Use pathlib for BASE_DIR
       • A settings file template
    2. Some settings patterns to avoid
       • Don’t read settings at import time
       • Avoid direct setting changes
       • Don’t import your project settings module
       • Avoid creating custom settings where module constants would do
       • Avoid creating dynamic module constants instead of settings
       • Name your custom settings well
       • Override complex settings correctly
    3. Test your settings file
       • Test your settings functions
       • Test your settings logic
12. Models and migrations
    1. Seed your database with a custom management command
       • Sample data approaches
       • Create a command
       • Test your command
    2. Factory Boy: easier data generation
       • Install and define factories
       • Invoke factories
       • Use factories in tests
       • Use factories in seed_database
       • Further features
    3. Migration safeguards
       • Test for pending migrations
       • django-linear-migrations: prevent merge migrations
13. System checks
    1. How system checks work
       • The basics
       • How to silence checks
       • The advantages of checks
    2. Write your own checks
       • How to write a check function
       • How to register a check function
       • Add a check for Python’s development mode
       • Add a check for model class names
    3. Test your checks
       • Test the development mode check
       • Test the model name check
    4. Further places that checks live
       • Model class checks
       • Model field checks
    5. django-version-checks: keep your environments in sync
       • Install and configure
       • Upgrading dependencies
14. Outroduction
    1. Further reading
    2. Thank you