Django Standalone Apps Learn to Develop Reusable Django Libraries — Ben Lopatin Django Standalone Apps Learn to Develop Reusable Django Libraries Ben Lopatin Django Standalone Apps: Learn to Develop Reusable Django Libraries Ben Lopatin New York, NY, USA ISBN-13 (pbk): 978-1-4842-5631-2 ISBN-13 (electronic): 978-1-4842-5632-9 https://doi.org/10.1007/978-1-4842-5632-9 Copyright © 2020 by Ben Lopatin This work is subject to copyright. All rights are reserved by the Publisher, whether the whole or part of the material is concerned, specifically the rights of translation, reprinting, reuse of illustrations, recitation, broadcasting, reproduction on microfilms or in any other physical way, and transmission or information storage and retrieval, electronic adaptation, computer software, or by similar or dissimilar methodology now known or hereafter developed. Trademarked names, logos, and images may appear in this book. Rather than use a trademark symbol with every occurrence of a trademarked name, logo, or image we use the names, logos, and images only in an editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the trademark. The use in this publication of trade names, trademarks, service marks, and similar terms, even if they are not identified as such, is not to be taken as an expression of opinion as to whether or not they are subject to proprietary rights. While the advice and information in this book are believed to be true and accurate at the date of publication, neither the authors nor the editors nor the publisher can accept any legal responsibility for any errors or omissions that may be made. The publisher makes no warranty, express or implied, with respect to the material contained herein. Managing Director, Apress Media LLC: Welmoed Spahr Acquisitions Editor: Celestin Suresh John Development Editor: Matthew Moodie Coordinating Editor: Aditee Mirashi Cover designed by eStudioCalamar Cover image designed by Freepik (www.freepik.com) Distributed to the book trade worldwide by Springer Science+Business Media New York, 233 Spring Street, 6th Floor, New York, NY 10013. Phone 1-800-SPRINGER, fax (201) 348-4505, e-mail orders-ny@springer- sbm.com, or visit www.springeronline.com. Apress Media, LLC is a California LLC and the sole member (owner) is Springer Science + Business Media Finance Inc (SSBM Finance Inc). SSBM Finance Inc is a Delaware corporation. For information on translations, please e-mail [email protected], or visit http://www.apress.com/ rights-permissions. Apress titles may be purchased in bulk for academic, corporate, or promotional use. eBook versions and licenses are also available for most titles. For more information, reference our Print and eBook Bulk Sales web page at http://www.apress.com/bulk-sales. Any source code or other supplementary material referenced by the author in this book is available to readers on GitHub via the book’s product page, located at www.apress.com/978-1-4842-5631-2. For more detailed information, please visit http://www.apress.com/source-code. Printed on acid-free paper Table of Contents About the Author �����������������������������������������������������������������������������������������������������ix About the Technical Reviewer ���������������������������������������������������������������������������������xi Introduction �����������������������������������������������������������������������������������������������������������xiii Part I: Basic Components of a Django App ��������������������������������������������1 Chapter 1: Defining the scope of a Django standalone app ��������������������������������������3 Benefits of creating standalone apps �������������������������������������������������������������������������������������������3 Sharing your work �������������������������������������������������������������������������������������������������������������������3 Improved code quality �������������������������������������������������������������������������������������������������������������4 Don’t repeat yourself ���������������������������������������������������������������������������������������������������������������4 Commonality across a company ���������������������������������������������������������������������������������������������4 Commonalities across client projects �������������������������������������������������������������������������������������5 The currency of prestige ����������������������������������������������������������������������������������������������������������5 With or without Django? ���������������������������������������������������������������������������������������������������������������6 Choosing your dependencies ��������������������������������������������������������������������������������������������������������7 Necessary functionality �����������������������������������������������������������������������������������������������������������7 Version compatibility ���������������������������������������������������������������������������������������������������������������8 Testing and documentation �����������������������������������������������������������������������������������������������������8 Maintenance cadence �������������������������������������������������������������������������������������������������������������9 Specific vs� generalized�����������������������������������������������������������������������������������������������������������9 Summary�������������������������������������������������������������������������������������������������������������������������������������10 Chapter 2: Structuring standalone Django apps �����������������������������������������������������11 Django apps as Python modules �������������������������������������������������������������������������������������������������11 What about middleware and URLs and views? ���������������������������������������������������������������������������13 Example app: currency ����������������������������������������������������������������������������������������������������������������13 Summary�������������������������������������������������������������������������������������������������������������������������������������15 iii Table of ConTenTs Chapter 3: Testing ���������������������������������������������������������������������������������������������������17 Why test? ������������������������������������������������������������������������������������������������������������������������������������17 Testing apps from a Django project ���������������������������������������������������������������������������������������18 Testing the app ����������������������������������������������������������������������������������������������������������������������19 Testing outside of a project ���������������������������������������������������������������������������������������������������19 Using a testing script �������������������������������������������������������������������������������������������������������������20 Testing application relationships �������������������������������������������������������������������������������������������22 Where to include tests �����������������������������������������������������������������������������������������������������������24 Testing without Django ����������������������������������������������������������������������������������������������������������25 Summary�������������������������������������������������������������������������������������������������������������������������������������25 Chapter 4: Model migrations ����������������������������������������������������������������������������������27 Migrations outside of a project ���������������������������������������������������������������������������������������������������27 Testing migrations ����������������������������������������������������������������������������������������������������������������������28 Additional migration guidelines ��������������������������������������������������������������������������������������������������29 Summary�������������������������������������������������������������������������������������������������������������������������������������30 Chapter 5: Templates ����������������������������������������������������������������������������������������������31 Three basic strategies�����������������������������������������������������������������������������������������������������������������31 What to include ���������������������������������������������������������������������������������������������������������������������������31 Email and miscellaneous templates ��������������������������������������������������������������������������������������34 Summary�������������������������������������������������������������������������������������������������������������������������������������34 Chapter 6: Using static files �����������������������������������������������������������������������������������35 Static files in standalone apps ����������������������������������������������������������������������������������������������������35 In the Django admin ��������������������������������������������������������������������������������������������������������������������37 Summary�������������������������������������������������������������������������������������������������������������������������������������38 Chapter 7: Namespacing in your app ���������������������������������������������������������������������39 Namespaces at a glance �������������������������������������������������������������������������������������������������������������39 App itself �������������������������������������������������������������������������������������������������������������������������������������40 URLs ��������������������������������������������������������������������������������������������������������������������������������������������40 Settings ���������������������������������������������������������������������������������������������������������������������������������������41 iv Table of ConTenTs Management commands ������������������������������������������������������������������������������������������������������������41 Template tags �����������������������������������������������������������������������������������������������������������������������������43 Models and database tables �������������������������������������������������������������������������������������������������������44 Chapter 8: Creating a basic package ����������������������������������������������������������������������45 An example blog app ������������������������������������������������������������������������������������������������������������������45 A basic setup�py file ��������������������������������������������������������������������������������������������������������������46 Adding templates and static files ������������������������������������������������������������������������������������������48 Installing and using ���������������������������������������������������������������������������������������������������������������������49 Summary�������������������������������������������������������������������������������������������������������������������������������������50 Part II: Scoping and Extracting a Reusable App ����������������������������������51 Chapter 9: Scoping and drawing boundaries ���������������������������������������������������������53 Scoping and the nature of the problem ��������������������������������������������������������������������������������������53 The job of a standalone app ��������������������������������������������������������������������������������������������������������54 The dimensions for creation and extraction �������������������������������������������������������������������������������55 Sizing the scope of an app ����������������������������������������������������������������������������������������������������������57 When an app is too big ����������������������������������������������������������������������������������������������������������57 When an app is too small ������������������������������������������������������������������������������������������������������58 Summary�������������������������������������������������������������������������������������������������������������������������������������59 Chapter 10: Separating your app ����������������������������������������������������������������������������61 Getting started ����������������������������������������������������������������������������������������������������������������������������61 Refactor first �������������������������������������������������������������������������������������������������������������������������������62 Model renaming and migrations �������������������������������������������������������������������������������������������������63 Allowing customization ���������������������������������������������������������������������������������������������������������������66 Backend classes ��������������������������������������������������������������������������������������������������������������������67 Signals �����������������������������������������������������������������������������������������������������������������������������������68 Finalization and removing from the project ��������������������������������������������������������������������������������69 Summary�������������������������������������������������������������������������������������������������������������������������������������69 v Table of ConTenTs Chapter 11: Adding your app back in ���������������������������������������������������������������������71 Verifying locally ���������������������������������������������������������������������������������������������������������������������������71 Source control–based packages �������������������������������������������������������������������������������������������������72 Published packaged ��������������������������������������������������������������������������������������������������������������������74 Summary�������������������������������������������������������������������������������������������������������������������������������������76 Part III: Beyond the Basics ������������������������������������������������������������������77 Chapter 12: Handling app settings �������������������������������������������������������������������������79 Settings naming ��������������������������������������������������������������������������������������������������������������������������79 Settings formats �������������������������������������������������������������������������������������������������������������������������80 Sourcing app settings �����������������������������������������������������������������������������������������������������������������81 Summary�������������������������������������������������������������������������������������������������������������������������������������85 Chapter 13: Internationalization �����������������������������������������������������������������������������87 Why translation ���������������������������������������������������������������������������������������������������������������������������87 Translatable strings and how translation works �������������������������������������������������������������������������88 Prioritizing translation steps �������������������������������������������������������������������������������������������������������89 Model content and translations ��������������������������������������������������������������������������������������������������91 Summary�������������������������������������������������������������������������������������������������������������������������������������93 Chapter 14: Managing version compatibility ���������������������������������������������������������95 Python version ����������������������������������������������������������������������������������������������������������������������������95 Django and dependencies �����������������������������������������������������������������������������������������������������������97 Solving for incompatibilities �����������������������������������������������������������������������������������������������������100 Future proofing �������������������������������������������������������������������������������������������������������������������������100 Summary�����������������������������������������������������������������������������������������������������������������������������������101 Chapter 15: Mixed dependency support ���������������������������������������������������������������103 Beyond Django ��������������������������������������������������������������������������������������������������������������������������103 The nuts and bolts ��������������������������������������������������������������������������������������������������������������������104 Real-world examples ����������������������������������������������������������������������������������������������������������������106 Summary�����������������������������������������������������������������������������������������������������������������������������������108 vi Table of ConTenTs Chapter 16: Modularity �����������������������������������������������������������������������������������������109 Additional standalone apps �������������������������������������������������������������������������������������������������������109 Using sub-apps �������������������������������������������������������������������������������������������������������������������������111 Embracing horizontal modularity ����������������������������������������������������������������������������������������������111 Summary�����������������������������������������������������������������������������������������������������������������������������������112 Chapter 17: Better packaging �������������������������������������������������������������������������������113 Version consolidation ����������������������������������������������������������������������������������������������������������������113 Using a source directory �����������������������������������������������������������������������������������������������������������116 Using setup�cfg �������������������������������������������������������������������������������������������������������������������������118 The pyproject�toml and more tooling ����������������������������������������������������������������������������������������119 Summary�����������������������������������������������������������������������������������������������������������������������������������121 Part IV: Managing Your Standalone App ��������������������������������������������123 Chapter 18: Licensing �������������������������������������������������������������������������������������������125 What licenses do �����������������������������������������������������������������������������������������������������������������������125 Varieties of licenses ������������������������������������������������������������������������������������������������������������������126 How and where to include your license ������������������������������������������������������������������������������������127 How to include other licenses ���������������������������������������������������������������������������������������������������128 Summary�����������������������������������������������������������������������������������������������������������������������������������130 Chapter 19: Documenting your standalone app ���������������������������������������������������131 Starting with questions �������������������������������������������������������������������������������������������������������������131 The forms of documentation �����������������������������������������������������������������������������������������������������133 Code comments and docstrings ������������������������������������������������������������������������������������������135 Tools for documentation �����������������������������������������������������������������������������������������������������������136 Summary�����������������������������������������������������������������������������������������������������������������������������������137 Chapter 20: Additional Testing �����������������������������������������������������������������������������139 Testing migrations ��������������������������������������������������������������������������������������������������������������������139 Testing against different versions ���������������������������������������������������������������������������������������������140 Using pytest ������������������������������������������������������������������������������������������������������������������������������141 Summary�����������������������������������������������������������������������������������������������������������������������������������144 vii Table of ConTenTs Chapter 21: Automating ����������������������������������������������������������������������������������������145 What is it and why bother? �������������������������������������������������������������������������������������������������������145 Starting to automate �����������������������������������������������������������������������������������������������������������������146 Continuous integration services �����������������������������������������������������������������������������������������������146 Travis CI �������������������������������������������������������������������������������������������������������������������������������147 GitHub ����������������������������������������������������������������������������������������������������������������������������������147 GitLab ����������������������������������������������������������������������������������������������������������������������������������148 CircleCI ��������������������������������������������������������������������������������������������������������������������������������149 Others ����������������������������������������������������������������������������������������������������������������������������������150 Summary�����������������������������������������������������������������������������������������������������������������������������������150 Chapter 22: Databases and other backend-specific considerations ��������������������151 Backend-specific implementation and features �����������������������������������������������������������������������151 Approaching database-specific functionality ����������������������������������������������������������������������������152 Summary�����������������������������������������������������������������������������������������������������������������������������������154 Chapter 23: Collaborating �������������������������������������������������������������������������������������155 Why contributions ���������������������������������������������������������������������������������������������������������������������155 What to expect ��������������������������������������������������������������������������������������������������������������������������156 Setting expectations �����������������������������������������������������������������������������������������������������������������156 The role and obligations of an open source maintainer ������������������������������������������������������������159 Summary�����������������������������������������������������������������������������������������������������������������������������������160 Chapter 24: Using app templates �������������������������������������������������������������������������161 startapp �������������������������������������������������������������������������������������������������������������������������������������161 Cookiecutter ������������������������������������������������������������������������������������������������������������������������������162 Summary�����������������������������������������������������������������������������������������������������������������������������������164 Index ���������������������������������������������������������������������������������������������������������������������165 viii About the Author Ben Lopatin is cofounder and principal consultant at Wellfire Interactive and has been developing with Django since the pre-version 1.0 days. Over that time he has led a variety of CMS and SaaS projects, using numerous standalone apps and releasing a few himself. He writes a newsletter devoted to working with existing production Django apps called “This Old Pony,” named after his most recent DjangoCon talk, and he can be reached at https://benlopatin.com. ix