How to Tango with Django: A Python Django Tutorial | Hacker News Reader

How to Tango with Django: A Python Django Tutorial

tangowithdjango.com

233 pointspajju68 comments

This looks like it might eventually become a useful resource, as there is nothing else out there with its particular approach and combination of topics, and it seems fundamentally sound.

However, I wouldn't recommend trying to learn from it in its current form, unless you already know a lot.

Just skimming over it, I found that it was teeming with grammatical errors and typos, with entire sentences garbled to the point where I couldn't tell what the authors had intended to say. I saw syntax errors in the code samples, which means that they weren't all verified to run as printed. Again, not a real problem except for beginners, but beginners are the target audience.

Finally, there is some utility to the concept of prerequisite that the authors seem to avoid.

This book tries to teach the beginner everything that he might need to know, from what "ls" does in the shell to how to use git and set up virtual environments. Maybe it is practical to go from never having seen the command line to deploying working, secure Django projects just by using a (cleaned up version of) this book, but doesn't it make more sense to learn things in a more solid progression of stages? It's OK to expect the student to already know some basics, and build on those. You don't find a tutorial on arithmetic in a book about topology.

I'm a PHP developer, just used this guide to get Django up and running on my MacBook.. so far so good for me.

Yeah but I think more beginner material should spell out the proper way of doing things even if it is "unrelated". My pet peeve is beginner material that reads something like:

"to make this example simpler, I am going to do something incredibly insecure. In production you would never ever do this, but I'm still going to do it, so if you are unfamiliar with foo, make sure you know all about bar too."

As well, if I was teaching someone Django/Python development from scratch today, I would definitely include pip, virtualenv, and git/mercurial as part of the baseline. HTML is a hypertext medium so you could let people who know skip ahead.

"if I was teaching someone Django/Python development from scratch today, I would definitely include pip, virtualenv, and git/mercurial as part of the baseline."

They DO show you how to use pip, git, and virtualenv.

Check out the overview: http://www.tangowithdjango.com/book/chapters/overview.html#w...

One of the first things they explain is how to use pip: http://www.tangowithdjango.com/book/chapters/requirements.ht...

They also show how to get started with git: http://www.tangowithdjango.com/book/chapters/git.html#git-cr...

and virtualenv: http://www.tangowithdjango.com/book/chapters/requirements.ht...

edit: I actually think I might have misunderstood your comment. Sorry. Anyway, just leaving this comment here for posterity.

I definitely think you have a point about the target audience. This looks to be a great resource for someone wanting to get into django who has experience in other web frameworks.

I would recommend the site qualify what they mean with the term "beginner".

Thanks for all the comments and suggestions.

By "beginner" we mean, someone with knowledge of Python, and who has started to play around with Django (i.e. started to undertake the official django tutorials).

We started the book to help my 3rd year undergraduate computer science students, who learn python in 1st year.

Thanks for the feedback and suggestions. It is work in progress, where we subscribe to the, Release Early and Release Often paradigm.

Thanks to many of the initial readers, we've been updating the book regularly and catching the typos and confusing parts of the book.

If you'd like to contribute then the source for the book is on github (written in Python Sphinx) see http://bit.ly/1bVKKJf

Question for Rails and Django users: is there a site that gives definitive best practices for both? I've actually been thinking about building a thrown-together site for just that purpose.

I've tried to get into both Rails and Django twice now (I'm a PHP guy usually), but every time I seem to get going, I get bogged down by StackOverflow after StackOverflow that have seemingly contradictory information or offer a third party solution rather than solving the problem within the framework.

In Rails, for example, Rails is easy enough, until you're dealing with RVM * , Passenger * , and installing correct dev versions of database drivers.

In Django, you deal with South migrations when you want to update your database schemas, virtualenv * , virtualenvwrapper * ; in fact, I've heard that one of the criticisms of Django is that, in order to get to production quality, you essentially have to switch out every component of it with a third party.

* The starred apps don't technically have anything to do with the framework; they're more utilities for managing multiple framework instances. Still, you're likely to find tutorials that use them as a de facto standard, which only adds to noob confusion.

I've started reading Michael Hartl's Rails tutorial, which seems promising. I found that the highly-recommended "Two Scoops of Django" book was a little too narrative for me (just tell me what to do, dammit!); there's definitely a need for more Django tutorials than just the Django website's basic one -- kudos to the author for that.

I'd say don't worry about south if you're not working with a big team.

Just track the changes you make to your models and make the same changes to the database.

I don't agree with that. I'd say don't worry about south if you're just starting out playing with django and willing to manually delete tables every now and then to get make sure your db matches your models.

As soon as you are doing something that anyone relies on and to save you endless effort you should use South, IMO. Even if it's a one-person project (I have a few of those) South saves you both a lot of time and aggravation.

Absolutely agree. Even something as simple as adding an optional field is just ./manage.py schemamigration --auto <appname> and you're done vs "ALTER TABLE blah blah blah...." on your local system, dev/staging, and then again on production in the right order, every time, manually. Can't imagine anyone wanting to go back to manual after using South.

This thread perfectly exemplifies the frustration laid out in my original post.

Welcome to development with open source technology. It takes time and effort to figure out the best practices. There is no magic bullet, sorry. That's not meant to be snarky it's just the way the process works.

And use Postgres as the database. If you use MySQL you will get sick of South telling you to use Postgres whenever a migration doesn´t go smoothly.

Definitely not good advice, regardless of what language or framework you're working with. If there's a solid migration tool available, it is definitely better to use it.

Aside from being a great habit to get into, South (or whatever other migration tool you want to use) will keep your database consistent and predictable to the framework. If you add or alter columns on your own, you run the risk of slight differences between what you've done and what the framework would've done left to its own devices. You may not have done anything wrong, but you don't want that inconsistency.

Migrations are going to be a core feature (quite similar to Ruby on Rails) from Django 1.7, and I personally find it more convenient. Eventually you will need to use migrations anyway.

I honestly find South to be the easiest and most efficient way to make model changes even on a solo project.

The biggest upside to it is that it fully documents all of your chances, and even allows rollbacks if necessary. Editing the database directly doesn't give you any kind of change log unless you do it manually, which is not really sustainable, even while working solo.

For Rails I highly recommend this course an the accompanying book https://www.edx.org/course/berkeley/cs169-1x/software-servic...

Hartl's Rails tutorial is comprehensive, but does not spend enough time explaining the underlying principles IMO. Writing a test for everything also muddies the water in that tutorial (which does not mean TDD is not good for you).

Which underlying principles do you have in mind? I might use any suggestions you have to augment the next edition.

By the way, though the feedback on the inclusion of TDD has generally been positive, it can get tedious, even for me. I do hope to produce a simpler, test-free Rails intro at some point as a complement to the present tutorial.

Two Scoops of Django does a great job of covering best practices.

https://django.2scoops.org/

The best resource for learning Django best practices right now is probably the Two Scoops book:

https://django.2scoops.org/

One thing that Django suffers from is having a long history which means that old best-practices (which no longer are best practices) still float around on blogs and it's hard to know what is what. I understand that the fact that so many people swap out core components with 3rd party libs can make it confusing, but I would disagree that in order to get to production quality it is required. I would even recommend avoiding swapping out core pieces whenever possible and work within the framework.

As I said in the original comment, I didn't find Two Scoops to be effective. It's woefully indirect and is itself riddled with digressions about third party libraries. I just want a list of what to install and why so that I don't have to constantly backtrack.

As one of the authors, I'm not sure what to say to this. I would honestly love to get your feedback.

Just so you know, when the book was more direct we had reviewers saying it was too direct and they wanted more flavor text. Our answer was an appendix of libraries in the back that listed all the recommended packages. Perhaps we should point readers to that earlier?

Also, if you are using Django, using third-party libraries is part of using Django. We feel this is a good thing because you don't want critical libraries standing still waiting for the next major Django release (a roughly yearly event). A good example is OAuth authentication - if Facebook or Twitter changes it's methods, you can upgrade to the latest django-social-auth or django-allauth and expect things to work.

However, as I said, I would love to hear more detailed feedback. That way we can make the book better. :-)

Thanks for the reply! I'd love to go more in-depth with my critique. Keep in mind that, while I'm new to Django and Python, I've worked with PHP, Java, C++, C, and Objective-C for years. I'm familiar with writing reusable code and how to write code that is able to be read by others. I'm also an OOP fanatic, so I'm already on board with most of the conventions that are suggested by most frameworks like Django and Rails. My previous experience with Django was going through the official Django tutorial.

So, while I may be a weird outlier (not a beginner, but I only have a basic understanding of Python), I felt that the book was never really written for me. It lacks an authoritative tone that I want in a "best practices" manual, and the fact that the book spends so much time explaining why best practices are important really made me think that the book was meant for programming beginners. Paradoxically, the book will then randomly drop in a Python package or two without explanation and expect me to know what it is.

Here are some examples:

Using explicit relative imports -- The section explains why explicit relative imports are good. Fair enough. Then, the book provides an example of "bad code" with "implicit relative imports". Keep in mind that you still haven't defined "explicit relative imports." Then, you explain how un-portable and un-reusable these "hard coded" imports are. After that, you convert the snippet to "explicit relative imports". Still no definition. From here, I try to compare the two snippets. Did the authors really spend 2 pages explaining a "best practice" that could easily fixed by just omitting the package name? I honestly thought I was missing something. Then, the fact that "implicit" relative imports had more code than "explicit" relative imports really started messing with my head, so I decided to move on.

Chapter 2 Fixtures -- I wasn't wondering why we weren't using fixtures because I had no idea what they were (they weren't covered in the tutorial). Simply defining fixtures would help here.

The rest of the chapter was all info that applies to every language and isn't specific to Django (dev and prod should be identical, use git, etc.), so I wasn't really getting much out of the chapter.

Chapter 3

Other Alternatives -- why?! I'm trusting you with my life here! Tell me what to do! I am yours to mold into a brilliant Django developer!

Chapter 6

Model managers -- This is where the narrative style really lead to ambiguity for me. Example 6.6 isn't labeled as a BAD EXAMPLE, yet you lead into it with a rhetorical question. My e-reader happened split the page right after the example, so if I had stopped reading there (which is common for me with reference books), I may have not seen that, on the next page, you explain that Example 6.6 is an example of what not to do.

General My problem getting acclimated to Django isn't the third party libraries necessarily; it's more my lack of knowledge about them at all. Throughout the book, there are tips for libraries to add to Django, but there's hardly ever a thorough explanation or description of the product, just that you think it's important.

Hope that helps! Just in case it needs to be said: none of this is an attack on you at all; I totally appreciate the work that went into this book. Thanks for listening to feedback and let me know if you have any other questions!

If I might make a suggestion, I think a lot of these problems would have been solved by reading the Django project docs before Two Scoops. Unlike many open source projects, Django's docs are of extremely high quality. Their main shortcoming is that while they tell you a great deal about what Django's pieces are and how they work, it leaves out a lot of practical usage stuff. That's where Two Scoops picks up. To me it's less of a book for a pure beginner and more so intended for turning someone who knows the basics into someone who can deploy a real site into production.

That's a fair point. I went through the tutorial and totally overlooked the rest of the docs (with the exception of the ones that I needed). Even still, I think Two Scoops could be a lot more concise and spend less time focusing on why and more time focusing on how. Best practices are means to an end; if someone's reading a book about them, chances are that they're aware of the benefits of following best practices anyway and don't need the constant reminder of why portable, readable code is important.

> in fact, I've heard that one of the criticisms of Django is that, in order to get to production quality, you essentially have to switch out every component of it with a third party.

This is not necessarily true. Everything in Django is production quality as you will see in several sites in the wild (including the very first Django sites).

No framework will give you the most optimal set of components for every possible scenario. In most cases Django components are swapped out for performance reasons, especially when they are high traffic sites. In other cases, it is due to the NIH syndrome where almost every component has been homegrown (perhaps trying to become more standalone).

>they're more utilities for managing multiple framework instances. Still, you're likely to find tutorials that use them as a de facto standard, which only adds to noob confusion.

That sounds more like a problem of php. Tools like composer should be more widespread and when they are switching to virtualenv probably isn't going to be so much of a hassle.

Nope, not a PHP problem.

If you are planning to enter Django world, it's always good to know Python well.

The Hitchhiker’s Guide to Python![1] explains a number of Python related things which beginners(in my experience and opinion) generally either tend to overlook. You do not need to read it all at once. Chapters can almost be read independently and in no particular order.

Secondly, go through Python Ecosystem - An Introduction[2](shameless plug) once. .

[1]http://docs.python-guide.org/en/latest/ [2]http://mirnazim.org/writings/python-ecosystem-introduction/

> in fact, I've heard that one of the criticisms of Django is that, in order to get to production quality, you essentially have to switch out every component of it with a third party.

where did you hear that? its outright non-sense. everything that ships with django is good enough for production right out of the box.

For people starting with Web Framework or new to Python, I would suggest starting with a lightweight framework, such as Flask or Pylons.

I used to struggle with Django, so I started to look into Flask, and I really feel like I finally understood what I was doing.

Flask tuto : http://flask.pocoo.org/

I agree, being new to web development a few years ago I struggled along with Django for a bit before trying Flask, which is a fantastic framework. It's easy to keep the entire thing in your head while coding. Today I've moved on from Flask to Django, because as my web apps began to grow I ended up writing features that Django gives out of the box, but I still value Flask hugely. I will probably use it in the future, for small web apps here and there.

Don't you feel you wasted your time learning flask and django, when you could have just learned django?

I'm interested in a response here as well. I know a tiny amout of Flask and am disputing moving to Django.

Why is the time wasted if you move on to Django? I'm sure the time won't be going to waste as you will become a better developer having been exposed to both.

The decision which to learn should be based on what your overall goals are. I am myself starting to learn python and will be moving towards learning Django. I don't see Django as the final solution to everything but its a solid start to being exposed to python and its web frameworks.

I have looked at Flask and Pyramid. Both seem quite good but at this moment I'm looking at learning a framework that will do a lot of heavy lifting for me. Django will do that better. Likely in about a year or more, I will be in a position to decide for myself based on my own experience whether getting into Flask or Pyramid would be a better idea for my projects.

Personally, I'd rather go to a restaurant and see the full buffet and sample the food that way (ie. Django) versus go in and pick niche items of the menu (ie. Flask).

I'm in the same position as the parent (grandparent?). I went through a bunch of django tutorials but felt that too much of it was "magic", so while everything worked out pretty well, I was never really sure why. I'm currently learning flask now because it still seems really easy while being more straightforward. I think that once I have actually written some stuff from scratch, I'll understand and appreciate a lot more of what is happening behind the scenes with django more.

learning is never a waste of time. even things that seem redundant are not really. seeing the same problem solved two different ways can offer a lot of insight into the nature of the problem and the trade offs of each solution.

Would you have the same suggestion for seasoned web developers in other languages, but who are still new to Python?

I'm curious as I'm really looking to learn Python and was looking at Django for the web side of things.

Well, Python is quick to learn. So my advice would be first a focus on the Python langage. After, it would depend : If you have great experience in MVC framework and you need it for a seasoned job, I think you could start with Django. Flask is a just an easier (cooler !) way to learn framework with python.

Flask is inherently simpler/smaller than Django. For doing simple/small web sites its a naturally good fit. However, due to its simplicity it needs to be significantly augmented if you intend to build a more complex web app with it.

Augmenting Flask with a data persistence layer, a RESTful API system, a more robust templating system, and any of the other infrastructure tools you'll need (user auth, session management, xss protection, input cleaning/validation, etc.) is quite complicated. If you go through those steps you'll basically just end up with something like what Django gives you right out of the box. Except that Django's components are well integrated with each other and fully tested, and your custom built system won't be.

This would've been immensely useful when starting out.

Official tutorials and docs don't cover nearly all of the accepted standard practices. As a relative outsider it seems a lot of this Django/Python knowledge is taken for granted by the tightly knit community of the skillful developers who interact with each other and exchange various tips, while a beginner who is not really embedded in the community misses out on all that and picks it up only when it's widely enough used that it hits the blogs and podcasts in bits and pieces.

From a quick overview I really like your approach: you start by a hello world directly (then template, then models) instead of doing this strange approach of the django official tutorial that starts with model then admin interface then show an hello world at part 3. I also really like the presence of exercices.

Quick comment: here, you are teaching render_to_response http://www.tangowithdjango.com/book/chapters/templates_stati... while you should be using render instead https://docs.djangoproject.com/en/1.5/topics/http/shortcuts/... which is simplier than render_to_reponse (where you have to use the horrible context_instance=RequestContext(request) to be able to do certain things in the template which confuse a lot people).

Thanks for this contribution to the django community!

Another awesome resource for Django Screencasts is Neckbeard Republic.

https://www.neckbeardrepublic.com/tagged/django

You should probably not use django-registration for user auth as referred to in the guide, since it's been abandoned at this point: https://news.ycombinator.com/item?id=6278464.

django-allauth is a very good alternative that covers almost all kinds of authentications.

Thanks for the tip. We hope to include a chapter that uses OpenAuth instead. It is on our TODO list :-)

Cool. What made you go with OpenAuth?

I couldn't spot an issue discussing it, but if you have a good link on the pros and cons, I'd love to see it. :)

We are still investigating the options, but OpenAuth seems like a pretty useful open and applicable standard for authenticating users. In the book, we are trying to build up a series of guides on useful tools and toolkits for doing things.

So I'd also like to read about the pros and cons of the various authentication packages.

Django screencasts for the interested:

https://godjango.com/

http://gettingstartedwithdjango.com/

you should take a look at http://neckbeardrepublic.com/ as well. one of the pycoder's guys does it.

Looks interesting, thanks!

Another great resource is http://gettingstartedwithdjango.com/

This is fantastic! Congrats and keep up the good work! Will there be an ebook version available any time in the future? Thanks again.

Thanks! We appreciate your comments.

We'll be releasing a pdf and ebook in the future, but if you can't wait you can download the source for the book from github, see http://bit.ly/1bVKKJf

We've written the book in Python Sphinx so it is easy to compile into pdf.

I recently started to learn Ruby on Rails. I like the language and the framework, but I also appreciate the simplicity and power of Python.

Which framework should I focus on if my priorities are professional development and ease of workflow? I realize this is a hard question to answer, but I'm interested in hearing different perspectives.

I also was deciding between which language to learn and its corresponding web framework. What's the criteria for you? For me, one of the main criteria's is the applicability of the language and its supporting ecosystem across many application domains (ie. web, scientific, systems programming, etc.).

I am not tied to either language (not yet at least) so the decision was based more on "bang for the buck". I decided that Python is a better investment of my time. This was largely based on the fact that Python is used in many, many areas outside of web development. As a result, I feel python will server me more across most domains versus Ruby. It's true that Ruby can also be used in many different application domains but based on my research, it just doesn't have the legs that Python has for general programming. For better or worse, Ruby is widely known as "Ruby on Rails".

In terms of which language is better, both are good so this wasn't a factor.

Thanks for your insights. I share your priorities in terms of wanting to find a language that's widely used for general programming as well as the web. I'll have to spend more checking out Python!

Looks impressive. I'm a Ruby guy, but I would probably start with this if I was getting into Python/Django.

Looks good! The part I chose to jump to was deployment as there's a million ways to do it and I've been looking for a best practices. Was a little saddened to see you chose PythonAnywhere not because the service is bad, but because it has a limited use case.

Yeah there are a million ways to deploy for simplicity we choose PythonAnywhere. This was mainly because when you are teaching 200+ students, you need it to be easy, quick, and free (also it doesn't require a credit card to join).

We also hope to expand this chapter in the future to show how to migrate to a real database.

If you have some suggestions about other platforms to deploy on we'd love to hear them.

Good Tutorial. I like how you are building a website and adding features.

So far I have made it to the Ajax page.

Why don't you use render in your views, and url tags with the name in urls.py?

Also there is a lot of typos. Is the site open source?

Thank you for putting so much work into this, but it's not Python 3!

Totally! We hope to put another version out next summer using Python 3 and the latest version of Django at that point.

Another recommended resource for learning Django: http://www.djangobook.com/en/2.0/index.html

Please don't recommend the Django book to people. It's very out of date (in case you didn't read the warning on the front). Use the official Django tutorial [1] instead.

[1]: https://docs.djangoproject.com/en/1.5/intro/tutorial01/

There are plans to update the book, but they need help with that:

https://readthedocs.org/projects/django-book-new/

https://github.com/jacobian/djangobook.com

Thanks for all your comments and suggestions so far. Please keep the coming.

Reply on news.ycombinator.com