Writing, Publishing & Maintaining Reusable Django Apps

At Bitmazk we have created more than 60 reusable Django apps in 2012 and 2013. This talk describes best practices and patterns for creating reusable Django apps and introduces a template repository for kickstarting new apps within a few seconds.

Presented at PyCon Singapore 2013
Video: http://youtu.be/a4S1kTJfezA
Github: https://github.com/bitmazk/django-reusable-app-template

Transcript

1. WRITING, PUBLISHING & MAINTAINING REUSABLE DJANGO APPS DRY all the things! Martin Brochhaus (@mbrochh) PyCon SINGAPORE 2013 Saturday, 15 June, 13
2. Martin Brochhaus Founder of Bitmazk Pte. Ltd. @mbrochh mbrochh@gmail.com Saturday, 15 June, 13
3. DRY? Saturday, 15 June, 13
4. DON’T REPEAT YOURSELF see https://en.wikipedia.org/wiki/Don't_repeat_yourself Saturday, 15 June, 13
5. EXAMPLE Saturday, 15 June, 13
6. EXAMPLE # some code ... if path == ‘$HOME/myapp/bin’: # do something # some more code ... if path == ‘$HOME/myapp/lib’: # do something else Saturday, 15 June, 13
7. EXAMPLE # some code ... if path == ‘$HOME/myapp/bin’: # do something # some more code ... if path == ‘$HOME/myapp/lib’: # do something else import os BASE_PATH = ‘$HOME/myapp’ # some code ... if path == os.path.join(BASE_PATH, ‘bin’): # do something # some more code ... if path == os.path.join(BASE_PATH, ‘lib’): # do something else Saturday, 15 June, 13
8. WHAT ARE REUSABLE APPS? Saturday, 15 June, 13
9. WHAT ARE REUSABLE APPS? Saturday, 15 June, 13
10. WHAT ARE REUSABLE APPS? Saturday, 15 June, 13
11. WHAT ARE REUSABLE APPS? Saturday, 15 June, 13
12. WHAT ARE REUSABLE APPS? Saturday, 15 June, 13
13. WHAT ARE REUSABLE APPS? Saturday, 15 June, 13
14. DJANGO-FEEDBACK-FORM see https://github.com/bitmazk/django-feedback-form Saturday, 15 June, 13
15. DJANGO-FEEDBACK-FORM see https://github.com/bitmazk/django-feedback-form $ pip install django-feedback-form Saturday, 15 June, 13
16. DJANGO-FEEDBACK-FORM see https://github.com/bitmazk/django-feedback-form $ pip install django-feedback-form # in settings.py INSTALLED_APPS = [ ... 'feedback_form', ] Saturday, 15 June, 13
17. DJANGO-FEEDBACK-FORM see https://github.com/bitmazk/django-feedback-form $ pip install django-feedback-form # in settings.py INSTALLED_APPS = [ ... 'feedback_form', ] $ ./manage.py migrate feedback_form Saturday, 15 June, 13
18. DJANGO-FEEDBACK-FORM see https://github.com/bitmazk/django-feedback-form $ pip install django-feedback-form # in settings.py INSTALLED_APPS = [ ... 'feedback_form', ] $ ./manage.py migrate feedback_form # in urls.py urlpatterns = ( ... url(r'^feedback/', include('feedback_form.urls')), ) Saturday, 15 June, 13
19. DJANGO-FEEDBACK-FORM see https://github.com/bitmazk/django-feedback-form $ pip install django-feedback-form # in settings.py INSTALLED_APPS = [ ... 'feedback_form', ] $ ./manage.py migrate feedback_form # in urls.py urlpatterns = ( ... url(r'^feedback/', include('feedback_form.urls')), ) # in your html template {% load feedback_tags %} {% feedback_form %} Saturday, 15 June, 13
20. LITERATURE • Learn from the official Django documentation: https://docs.djangoproject.com/en/dev/intro/reusable-apps/ • Find apps on https://www.djangopackages.com/ Saturday, 15 June, 13
21. LITERATURE • Learn from the official Django documentation: https://docs.djangoproject.com/en/dev/intro/reusable-apps/ • Find apps on https://www.djangopackages.com/ Saturday, 15 June, 13
22. LITERATURE • Learn from the official Django documentation: https://docs.djangoproject.com/en/dev/intro/reusable-apps/ • Find apps on https://www.djangopackages.com/ Saturday, 15 June, 13
23. REUSABLE APP STRUCTURE Saturday, 15 June, 13
24. REUSABLE APP STRUCTURE - root folder/ - AUTHORS - CHANGELOG.txt - DESCRIPTION - LICENSE - MANIFEST.in - README.rst - manage.py - test_requirements.txt - setup.py Saturday, 15 June, 13
25. REUSABLE APP STRUCTURE - root folder/ - AUTHORS - CHANGELOG.txt - DESCRIPTION - LICENSE - MANIFEST.in - README.rst - manage.py - test_requirements.txt - setup.py - package_name/ - __init__.py - admin.py - models.py - urls.py - app_settings.py - views.py - static/package_name/ - templates/package_name/ Saturday, 15 June, 13
26. REUSABLE APP STRUCTURE - root folder/ - AUTHORS - CHANGELOG.txt - DESCRIPTION - LICENSE - MANIFEST.in - README.rst - manage.py - test_requirements.txt - setup.py - package_name/ - __init__.py - admin.py - models.py - urls.py - app_settings.py - views.py - static/package_name/ - templates/package_name/ - tests/ - runtests.py - test_settings.py - models_tests.py etc. - test_app/ Saturday, 15 June, 13
27. AUTHORS Current or previous core committers Martin Brochhaus (mbrochh) Contributors (in alphabetical order) * Your name could stand here :) see https://github.com/django/django/blob/master/AUTHORS Saturday, 15 June, 13
28. CHANGELOG === ongoing === - Added this cool feature === 1.0 === - Public API stable and released - Backwards incompatible changes released === 0.2.1 === - Fixed annoying bug - Fixed typo === 0.2 === - Added some cool features === 0.1 === - Initial commit see https://github.com/divio/django-cms/blob/develop/CHANGELOG.txt Saturday, 15 June, 13
29. LICENSE The MIT License (MIT) Copyright (c) 2012 Martin Brochhaus Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. see http://opensource.org/licenses/MIT Saturday, 15 June, 13
30. README Title Of The App ================ Short description, what problem does it solve? Installation ============ You can use code-examples:: pip install app-name Usage ===== Settings / Templatetags ======================= Contribute ========== see https://github.com/bitmazk/django-social-media-links Saturday, 15 June, 13
31. MANIFEST include AUTHORS include LICENSE include DESCRIPTION include CHANGELOG.txt include README.md graft package_name global-exclude *.orig *.pyc *.log *.swp prune package_name/tests/coverage prune package_name/.ropeproject see http://docs.python.org/2/distutils/sourcedist.html Saturday, 15 June, 13
32. SETUP.PY setup( name="package_name", version=app.__version__, description=read('DESCRIPTION'), long_description=read('README.rst'), license='The MIT License', platforms=['OS Independent'], keywords='django, reusable, app, feedback', author='Martin Brochhaus', author_email='mbrochh@gmail.com', url="https://github.com/username/package_name", packages=find_packages(), include_package_data=True, install_requires=[ 'django>=1.3', ], ) see http://docs.python.org/2/distutils/setupscript.html & http://guide.python-distribute.org/quickstart.html Saturday, 15 June, 13
33. TEST REQUIREMENTS django-nose coverage django-coverage django-jasmine ipdb flake8 fabric factory_boy mock selenium see http://www.pip-installer.org/en/latest/requirements.html Saturday, 15 June, 13
34. REUSABLE APP STRUCTURE - root folder/ - AUTHORS - CHANGELOG.txt - DESCRIPTION - LICENSE - MANIFEST.in - README.rst - manage.py - test_requirements.txt - setup.py - package_name/ - __init__.py - admin.py - models.py - urls.py - app_settings.py - views.py - static/package_name/ - templates/package_name/ - tests/ - runtests.py - test_settings.py - models_tests.py etc. - test_app/ Saturday, 15 June, 13
35. VERSION # in __init__.py __version__ = '0.1' see http://semver.org/ Saturday, 15 June, 13
36. APP SETTINGS # in app_settings.py from django.conf import settings FORM_COLOR = getattr(settings, ‘FEEDBACK_FORM_COLOR’, ‘red’) # somewhere in your app from .app_settings import FORM_COLOR self.color = FORM_COLOR see http://blog.muhuk.com/2010/01/26/developing-reusable-django-apps-app-settings.html Saturday, 15 June, 13
37. STATIC & TEMPLATES - root - package_name - static - package_name - css - styles.css - js - some_script.js - root - package_name - templates - package_name - feedback_form.html see https://docs.djangoproject.com/en/dev/ref/templates/api/#loader-types & https://docs.djangoproject.com/en/dev/ref/settings/#staticfiles-finders Saturday, 15 June, 13
38. REUSABLE APP STRUCTURE - root folder/ - AUTHORS - CHANGELOG.txt - DESCRIPTION - LICENSE - MANIFEST.in - README.rst - manage.py - test_requirements.txt - setup.py - package_name/ - __init__.py - admin.py - models.py - urls.py - app_settings.py - views.py - static/package_name/ - templates/package_name/ - tests/ - runtests.py - test_settings.py - models_tests.py etc. - test_app/ Saturday, 15 June, 13
39. TEST DRIVEN DEVELOPMENT • test_settings.py simulates a Django project • test_app • an app within the app?! • further simulates a Django project • can be used to define Dummy models • Execute ./runtests.py see https://speakerdeck.com/mbrochh/tdd-with-django Saturday, 15 June, 13
40. SOUTH MIGRATIONS see http://south.readthedocs.org/en/latest/tutorial/part1.html Saturday, 15 June, 13
41. SOUTH MIGRATIONS # before you publish your app $ ./manage.py schemamigration package_name --initial see http://south.readthedocs.org/en/latest/tutorial/part1.html Saturday, 15 June, 13
42. SOUTH MIGRATIONS # before you publish your app $ ./manage.py schemamigration package_name --initial # when you make changes to models.py $ ./manage.py schemamigration package_name --auto see http://south.readthedocs.org/en/latest/tutorial/part1.html Saturday, 15 June, 13
43. SOUTH MIGRATIONS # before you publish your app $ ./manage.py schemamigration package_name --initial # when you make changes to models.py $ ./manage.py schemamigration package_name --auto # when you make changes that require datamigrations $ ./manage.py datamigration package_name --auto see http://south.readthedocs.org/en/latest/tutorial/part1.html Saturday, 15 June, 13
44. SOUTH MIGRATIONS # before you publish your app $ ./manage.py schemamigration package_name --initial # when you make changes to models.py $ ./manage.py schemamigration package_name --auto # when you make changes that require datamigrations $ ./manage.py datamigration package_name --auto # all your users need to do is $ ./manage.py migrate package_name see http://south.readthedocs.org/en/latest/tutorial/part1.html Saturday, 15 June, 13
45. PREVIEW YOUR APP IN THE BROWSER $ ./manage.py runserver Saturday, 15 June, 13
46. OBEY PEP8!!! $ flake8 . see http://www.python.org/dev/peps/pep-0008/ Saturday, 15 June, 13
47. PUBLISHING ON THE PYTHON PACKAGE INDEX see http://docs.python.org/3/distutils/packageindex.html Saturday, 15 June, 13
48. PUBLISHING ON THE PYTHON PACKAGE INDEX # check if MANIFEST.in includes the correct files $ python setup.py sdist see http://docs.python.org/3/distutils/packageindex.html Saturday, 15 June, 13
49. PUBLISHING ON THE PYTHON PACKAGE INDEX # check if MANIFEST.in includes the correct files $ python setup.py sdist # register your app on pypi.python.org $ python setup.py register see http://docs.python.org/3/distutils/packageindex.html Saturday, 15 June, 13
50. PUBLISHING ON THE PYTHON PACKAGE INDEX # check if MANIFEST.in includes the correct files $ python setup.py sdist # register your app on pypi.python.org $ python setup.py register # upload your app $ python setup.py sdist upload see http://docs.python.org/3/distutils/packageindex.html Saturday, 15 June, 13
51. DOCUMENTATION see http://docutils.sourceforge.net/docs/user/rst/quickstart.html & http://sphinx-doc.org/tutorial.html Saturday, 15 June, 13
52. DOCUMENTATION # in the docs folder $ mkvirtualenv -p python2.7 yourapp $ pip install Sphinx $ deactivate && workon $ sphinx-quickstart see http://docutils.sourceforge.net/docs/user/rst/quickstart.html & http://sphinx-doc.org/tutorial.html Saturday, 15 June, 13
53. DOCUMENTATION # in the docs folder $ mkvirtualenv -p python2.7 yourapp $ pip install Sphinx $ deactivate && workon $ sphinx-quickstart # in docs/source/index.rst Contents: .. toctree:: :maxdepth: 2 installation see http://docutils.sourceforge.net/docs/user/rst/quickstart.html & http://sphinx-doc.org/tutorial.html Saturday, 15 June, 13
54. DOCUMENTATION # in the docs folder $ mkvirtualenv -p python2.7 yourapp $ pip install Sphinx $ deactivate && workon $ sphinx-quickstart # in docs/source/index.rst Contents: .. toctree:: :maxdepth: 2 installation # in docs/source/installation.rst Installation ============ Your documentation goes here... see http://docutils.sourceforge.net/docs/user/rst/quickstart.html & http://sphinx-doc.org/tutorial.html Saturday, 15 June, 13
55. Saturday, 15 June, 13
56. HTTPS://GITHUB.COM/ BITMAZK/DJANGO- REUSABLE-APP- TEMPLATE Saturday, 15 June, 13
57. THANK YOU! (https://github.com/bitmazk/django-reusable-app-template) @mbrochh Saturday, 15 June, 13