Differences

This shows you the differences between two versions of the page.

--- devel:blueprints:refactor-mod-python-to-django [2011/03/09 08:36] – created morten
+++ devel:blueprints:refactor-mod-python-to-django [2012/10/03 08:29] (current) – old revision restored morten
@@ Line 10: / Line 10: @@
 Often, the handler will include its own dispatch function - it performs varying actions based on the request's URI. The dispatch function often comes in the form of a giant ''if/elif/else'' construct, or, if you're lucky, it delegates each accepted URI pattern to a separate handler/view function.
+A handler does its work, the writes some output back to the client by using the **request object's** ''.write()'' method. The handler function then must return a response status code, typically ''mod_python.apache.OK'' (which is equal to 200).
+NAV's handlers will typically create an instance of a Cheetah template, fill it, get it's output via the ''respond()'' method and write this to the request object.
+===== Scope =====
+Refactoring a ''mod_python'' handler is limited to the parts that use ''mod_python'' in some way.  It is **not** necessary to ditch Cheetah templates in favor of Django templates, nor ditch pure SQL and legacy db connection in favor of Django's ORM.
+===== Suggested refactoring steps =====
+The goal is most likely to get rid of the ''handler()'' function altogether, by splitting its functionality into separate view functions, which can later be attached to a Django urlconfig.
+  * Split a large ''handler()'' function's dispatch construct by delegating each URI or action to a separate view function.  Confirm that this works before proceeding.
+  * Deconstruct the URI dispatcher into a Django urlconfig.
+  * Refactor each of the newly created view functions:
+    * Usage of mod_python's ''FieldStorage'' class, or NAV's ''nav.web.URI.URI'' class, to extract GET/POST parameters must be refactored to use the GET, POST or REQUEST attributes of the incoming Django request structure.
+    * Create a ''HttpResponse'' object, feeding it the output of the template's ''respond()'' method, and return this response object instead of an ''apache.OK''.
+A typical handler ends with something like this:
+<code python>
+req.write(template.respond())
+return apache.OK
+</code>
+Which can be turned into:
+<code python>
+return HttpResponse(template.respond())
+</code>
+The ''HttpResponse'' can also adjust the response code and the content-type of the output (which defaults to ''text/html''). Django also has other ''HttpResponse'' subclasses for returning specific response codes, such as ''Http404''.
+==== Gotchas ====
+  * A legacy handler's URLs may already have been configured with view names in the ''nav.django.urls.urlbuilder'' module, in order for Django apps and templates to easily create reverse links to these systems.  These config items must be moved in to your new urlconfig.
+===== Example =====
+Examine these changesets:
+  * [[http://nav.uninett.no/hg/default/rev/61a95ac14564|Refactoring the Netmap backend handler]]
+  * [[http://nav.uninett.no/hg/default/rev/1409829b73bc|Refactoring the sortedStats handler]]
+:!: It's probably better to portion out your refactoring in multiple changesets which make your changes easier to follow. That's one of the things DVCS'es are for.