What makes a package useful? What is it about certain packages that makes them must-haves for any project? ...
What makes a package useful? What is it about certain packages that makes them must-haves for any project?
We’ll go over topics like: purpose, structure, docs, tests, availability on PyPI and Github/Bitbucket, activity, and more.
We will visit some of the most useful grid categories on djangopackages.com and highlight our top package picks, showing examples of what makes the top packages so great and what could use improvement.
Django Package Thunderdome by Audrey Roy & Daniel GreenfeldPresentation Transcript
by Audrey Roy and Daniel Greenfeld @audreyr / @pydanny 1
Audrey Roy• Python & Django developer for Cartwheel Web / RevSys• MIT ’04, EE/CS• PyLadies, djangopackages.com, OpenComparison Django Packages Thunderdome (Packaginator)• @pydanny / @audreyr Fiancée of Daniel Greenfeld (pydanny) http://www.flickr.com/photos/chrisjrn/6102009780/ 2
Daniel Greenfeld • Python & Django developer for Cartwheel Web / RevSys • Learned Python at NASA • djangopackages.com, OpenComparison (Packaginator), django-uni-form Django Packages Thunderdomehttp://www.flickr.com/photos/pydanny/4442245488/ • Fiancé of Audrey Roy (audreyr) @pydanny / @audreyr 3
A Year+ of Package Comparisons• We launched djangopackages.com July 2010• We’ve seen the Django package Django Packages Thunderdome ecosystem grow and change @pydanny / @audreyr 4
Why a Thunderdome?• Pattern: you hear about the “best” package for X, and you use it• Comparison grids on djangopackages.com help • but not 100% effective/objective• Why not a Consumer Reports-style analysis? Django Packages Thunderdome• This is what a Django community manager @pydanny / @audreyr would do 5
Our review criteria What makes your package worthy? 6
1. Purpose• The name tells you what it does• “django-” prefix says it’s a Django package • Even better if coupled with a related Python package Django Packages Thunderdome• The package addresses a real need @pydanny / @audreyr 7
2. Scope• Small scope, narrow focus is better • Application logic will be tighter • Patching/replacing the app will be Django Packages Thunderdome easier @pydanny / @audreyr 9
Scoring: Scope Range: -5 to +5• Does one thing: +5• Does two things: 0• Does three or more things: -5 Django Packages Thunderdome @pydanny / @audreyr 10
3. Documentation• No docs means your app is pre-alpha• Doc strings do not suffice as documentation• If there are dependencies, they should be in your docs Django Packages Thunderdome• Installation steps should be bulletproof @pydanny / @audreyr 11
Scoring: Docs Range: -5o to +15• Docs folder in RST/Sphinx format: +10 • Displayed on http://rtfd.org: +5• Lousy Docs (wiki for example): -5 to -20• Only README + docstrings: -10 Django Packages Thunderdome• No docs: -50 @pydanny / @audreyr 12
4. Testing• Tests improve reliability• Tests make it easy to advance Python/ Django versions• Tests make it easier for others to Django Packages Thunderdome contribute effectively @pydanny / @audreyr 13
Scoring: Tests Range: -50 to +15• Public Jenkins site: +5• django_coverage/coverage.py: +5• Well done tests: +5• No Tests: -10 Django Packages Thunderdome• Placeholder tests: -50 @pydanny / @audreyr 14
5. Activity• When was the last commit?• How frequent are commits?• Are there periodic version updates? Django Packages Thunderdome @pydanny / @audreyr 15
Scoring: Activity Range: 0 to +15• Last commit up to 3 months ago: +15• Last commit up to 6 months ago: +10• Last commit up to 1 year ago: +5 Django Packages Thunderdome @pydanny / @audreyr 16
6. Community• Active community leader(s)• How many people are contributing?• Proper attribution of authors? • CONTRIBUTORS.txt? Django Packages Thunderdome • README @pydanny / @audreyr 17
Scoring: Community Range: 0 to +35• Active community leader: +10 • Lots of divergent forks? Then no• Number of contributors = # of points • Maximum of 20 points Django Packages Thunderdome• Proper attribution: +5 @pydanny / @audreyr 18
7. Modularity• “Pluggability”• Installation should be minimally invasive• Do not confuse modularity with over Django Packages Thunderdome engineering @pydanny / @audreyr 19
Scoring: Modularity Range: -20 t0 +20• Just add to up to these things: • INSTALLED_APPS • MIDDLEWARE • urls.py Django Packages Thunderdome • models.py in a few cases @pydanny / @audreyr • A few custom settings +20 20
Scoring: Modularity• Having to write your own custom code/ backends from scratch• Having to write your own templates• Having to study the code to make it work Django Packages Thunderdome• More framework than pluggable @pydanny / @audreyr -5 for any of these violations 21
8. Availability on PyPI• Actually on PyPI• Latest release on PyPI • Should not have to go to repo for working version Django Packages Thunderdome• Proper version numbers @pydanny / @audreyr 22
Scoring: PyPI Availability Range: 0 to +30• Latest release download link on PyPI: +15• Latest stable release +5• Historical versions kept on PyPI: +5 Django Packages Thunderdome• Good versioning scheme: +5 @pydanny / @audreyr 23
9. VCS/Hosting• Great: Github or BitBucket• Okay: Launchpad or SourceForge• Outdated: Google Project Hosting Django Packages Thunderdome• Poor: Your own site @pydanny / @audreyr 24
Scoring: VCS/Hosting Range: -20 t0 +20• Github or BitBucket: +20• Launchpad or SourceForge: +5• Google Project Hosting: +0 Django Packages Thunderdome• Hosting your own VCS: -20 @pydanny / @audreyr 25
10. License• You need a license• Companies prefer BSD or MIT licenses• http://opensource.org/licenses/category Django Packages Thunderdome @pydanny / @audreyr 26
Scoring: License Range: -15 to +5• BSD or MIT license: +5• Any other formal license: 0• Custom license: -5 to -15 Django Packages Thunderdome• No license: -15 @pydanny / @audreyr 27
Thunderdome Fight, packages! Fight! 28
A quick warning• We’re just kidding about the fighting• Friendly, “constructive criticism”• Use our feedback to help improve your favorite package Django Packages Thunderdome• Think of us as your friendly Django @pydanny / @audreyr community managers (during the talk) 29
How packages were chosen for this• We sent out a survey and chose the: ★ most commonly-used packages ★ most interesting packages Django Packages Thunderdome• Not direct one-to-one comparisons @pydanny / @audreyr 30
Round 1API Creation 31
Contenders: API CreationThey’re all a little different: • django-piston • django-tastypie • djangorestframework Django Packages Thunderdome • django-xmlrpc @pydanny / @audreyr 32
Winners: API Creation1. djangorestframework: 162 out of 175 points2. django-tastypie: 155 out of 175 points Django Packages Thunderdome @pydanny / @audreyr 38
Winners: Fundamentals1. django-debug-toolbar: 120 out of 175 points2. django-extensions: 115 out of 175 points Note that this was obviously not a one-to- Django Packages Thunderdome one comparison, but a purely points-based @pydanny / @audreyr evaluation 45
django- Pinax django- Registration registration (accounts) django-userena social-authPurpose 15 10 15 15PopularScope unofficial 5 mirror -5 -5 5 with templates? If theDocumentation 10 10 15 10 original had templates,Tests common fork5would this 0 5 0 not be neededActivity 15 10 15 15Community 25 35 16 26Modularity -15 -5 -10 -5PyPI 15 20 25 25 Django Packages ThunderdomeVCS/Hosting 20 20 20 20 @pydanny / @audreyrLicense 5 5 5 5Totals 100 100 101 116 51
Winners: Registration1. django-social-auth: 116 out of 175 points2. django-userena: 101 out of 175 points Interesting comment from survey: Django Packages Thunderdome “Site registration sucks and using Twitter, Facebook, or @pydanny / @audreyr Google auth is easier” 52
Winners: Profiles1. idios: 111 out of 175 points2. django-userena: 101 out of 175 points Room for improvement: Django Packages Thunderdome Low point values. Few surveyed users knew of a good Django @pydanny / @audreyr profiles app. Some roll their own each time. 58
Winner: Blogs1. django-blog-zinnia: 155 out of 175 points Most points by a landslide. So many blog packages exist that this gets buried. Django Packages Thunderdome Note that biblion is early/pre-alpha. With docs, it @pydanny / @audreyr could become a promising option for 1 blog per profile sites. 64
Winner: Tagging1. django-taggit: 146 out of 175 points Sets the bar for the other packages. High points for all compared. Django Packages Thunderdome “Stable API and responsive dev” @pydanny / @audreyr “Lots of magic under the hood, though” 69
Database Migrations South nashvegasPurpose 5 5Scope 5 5Documentation 15 15Tests 5 -10Activity 15 10Community If nashvegas 22 tests plus one 11 hadModularity other higher 15 20 sub-score, it could have won!PyPI 25 30 Django Packages ThunderdomeVCS/Hosting 20 20 @pydanny / @audreyrLicense 0 5Totals 140 117 74
Winners: DB Migrations1. South: 140 out of 175 points2. nashvegas: 117 out of 175 points “I’m looking forward to someone else cha#enging this space but South is by far the best that we currently have” Django Packages Thunderdome “South is the de facto standard...sti# run into more @pydanny / @audreyr %iction on managing DB changes than I care for, but it’s a lot better than doing without.” 75
Honorable mentions What the surveyed users said 79
They also can’t live without • celery & django-celery with redis • django-haystack with pysolr, sometimes whoosh • django-fixture-generator, django-sorting, Django Packages Thunderdome django-pagination, django-uni-form, django-floppy-forms @pydanny / @audreyr 80
SummaryThe key to a prize-winning Django package 81
Judging Report• http://bit.ly/django-thunderdome-2011• A detailed report is available (PDF) Django Packages Thunderdome @pydanny / @audreyr 82
Score high on the base criteria • Purpose (0 to +15) • Community (0 to +35) • Scope (-5 to +5) • Modularity (-20 to +20) • Docs (-50 to +15) • PyPI Availability (0 to +30) • Tests (-50 to +15) • VCS/Hosting (-20 to +20) • Activity (0 to +15) • License (-15 to +5) Maximum Score: +175 83
Beyond the base criteria• Run code through PEP8 checker• Aim for 100% test coverage• Elegant, clean, explicit ways of doing things • Django Packages Thunderdome Minimize magical code @pydanny / @audreyr 84
How to get more users for your packageUse djangopackages.com to find similar packages • Add a grid (if needed) • Add your package to the grid • Add grid features Django Packages Thunderdome • Make yours better than its competitors @pydanny / @audreyr 85
• Tweet your self-calculated score at @pydanny and @audreyr• We’ll evaluate it ourselves Django Packages Thunderdome• If it ranks high, we’ll help spread the word @pydanny / @audreyr• (conference bandwidth-permitting) 86
Sérgio Garcez