Django / Python API-如何确定方法期望接收的对象类？

Question

I just spent two hours debugging some django code because the API was not clear, in my opinion. Here is what the Django documentation says about the "render" method: https://docs.djangoproject.com/en/1.3/topics/http/shortcuts/#render

render(request, template[, dictionary][, context_instance][, content_type][, status][, current_app])

Combines a given template with a given context dictionary and returns an HttpResponse object with that rendered text.

render() is the same as a call to render_to_response() with a context_instance argument that forces the use of a RequestContext.

Now, seeing that the second argument that the render method expects is a template, I passed it a Template object. It turns out that what the method really wants is the name of the template given as a String. How am I supposed to know this? And what is "status" -- an integer? a string? a Status object? a list? Where can I get clear documentation to refer to?

Also, I would love to find an IDE that can detect these kinds of things while I'm programming -- when I worked with Netbeans and Java this sort of error would have been caught by the editor with a squiggly red underline before I'd even started typing the next line of code.

Answer 1

I can't at all see how this could be any better explained. As miku points out in the comment, the documentation clearly says "the full name of a template to use". Plus, the example given directly underneath shows the use of a string.

Python is not Java, nor any statically typed language. The documentation doesn't say it wants a string, because it doesn't: it wants something string-like that contains the name.

And don't forget, you've got immediate access to the code. Don't understand the function? Well, look at https://code.djangoproject.com/browser/django/trunk/django/shortcuts/__init__.py and there it is.

Even better, in Python you have an option that you simply don't have in Java: look in the shell. Do from django.shortcuts import render , then do help(render) to see what it says, and if that doesn't help try calling it with a few different arguments right there to see what it does.

If you insist on programming Python like it is Java, you will find it difficult. If you program Python like it's Python, you will find it much simpler.

Answer 2

While I agree with Daniel Roseman's answer, I do sympathise with your bewilderment, and I do think the interface and its parameters could have been better explained.

Django's interface is very committed to the idea of dynamic typing, or " duck typing " — as in, if it walks like a duck, if it swims like a duck, then call it a duck. Django's interface doesn't require you to pass a string type, it requires you to pass an entity which behaves like a string.

Look carefully, in the documentation to which you linked, at the specific wording for each parameter to render() . request is "the request object ". template is "the full name ... or sequence of names ." dictionary is "a dictionary of values...". status is "the status code for the response. Defaults to 200 " [an integer].

I've added emphasis to words which hint at which dynamic type the interface expects or returns. object means an object type, with a set of methods. name implies string. The example of 200 implies that status code is an integer.

I think the Django documentation would be clearer if it were more explicit about its vocabulary of the dynamic types it expects or returns. It could say something like, " request is an object implementing the Request Object Interface", and then define exactly what methods an object needs to implement to qualify as that interface. The documentation could also be explicit instead of implicit in cases like status , where it could say "integer" literally.

But those caveats aside, Django's interface is designed to be "pythonic", to embrace duck typing. Daniel is right, "if you insist on programming Python like it is Java, you will find it difficult." This might be a good time to read over Django's Design Philosophies and Python's PEP 20 -- The Zen of Python . Note that neither mentions "compile-time syntax checking thanks to strong typing" as a goal. Toto, I don't think we're in Java anymore.