add debugging stuff from @pbugni, add deployment and chameleon_18n to…

… index
Pylons · Nov 18, 2011 · 3bdc7d2 · 3bdc7d2
1 parent cc5f6d5
commit 3bdc7d2
Show file tree

Hide file tree

Showing 4 changed files with 132 additions and 2 deletions.
diff --git a/_themes b/_themes
diff --git a/chameleon_i18n.rst b/chameleon_i18n.rst
@@ -59,6 +59,7 @@ Well, let's translate some parts of the given template ``mytemplate.pt``. Add a
 namespace and an i18n:domain to the <html> tag:
 
 .. code-block:: text
+
    -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" xmlns:tal="http://xml.zope.org/namespaces/tal">
    +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" xmlns:tal="http://xml.zope.org/namespaces/tal"
    +      xmlns:i18n="http://xml.zope.org/namespaces/i18n"
@@ -72,6 +73,7 @@ case. Without this, the translations will not be picked up.
 So now we can mark a part of the template for translation:
 
 .. code-block:: text
+
    -          <h2>Search documentation</h2>
    +          <h2 i18n:translate="search_documentation">Search documentation</h2>
 

diff --git a/debugging.rst b/debugging.rst
@@ -1,5 +1,5 @@
 Debugging
----------
+=========
 
 Using PDB to Debug Your Application
 +++++++++++++++++++++++++++++++++++
@@ -19,3 +19,129 @@ application, and that point in your code is reached, you will be dropped into
 the ``pdb`` debugging console within the terminal that you used to start your
 application.
 
+Below is a debugging scenario using PDB to debug Pyramid.
+
+Debugging Pyramid
++++++++++++++++++
+
+This tutorial provides a brief introduction to using the python
+debugger (``pdb``) for debugging pyramid applications.
+
+This scenario assume you've created a Pyramid project already.  The scenario
+assumes you've created a Pyramid project named ``buggy`` using the
+``alchemy`` scaffold.
+
+Introducing PDB
+---------------
+
+- This single line of python is your new friend::
+
+    import pdb;  pdb.set_trace()
+
+- As valid python, that can be inserted practically anywhere in a Python
+  source file.  When the python interpreter hits it - execution will be
+  suspended providing you with interactive control from the parent TTY.
+
+PDB Commands
+------------
+
+- pdb exposes a number of standard interactive debugging
+  commands, including::
+
+    Documented commands (type help <topic>):
+    ========================================
+    EOF    bt         cont      enable  jump  pp       run      unt   
+    a      c          continue  exit    l     q        s        until 
+    alias  cl         d         h       list  quit     step     up    
+    args   clear      debug     help    n     r        tbreak   w     
+    b      commands   disable   ignore  next  restart  u        whatis
+    break  condition  down      j       p     return   unalias  where 
+    
+    Miscellaneous help topics:
+    ==========================
+    exec  pdb
+    
+    Undocumented commands:
+    ======================
+    retval  rv
+
+Debugging Our ``buggy`` App
+---------------------------
+
+- Back to our demo ``buggy`` application we generated from the ``alchemy``
+  scaffold, lets see if we can learn anything debugging it.
+
+- The traversal documentation describes how pyramid first acquires a root
+  object, and then descends the resource tree using the ``__getitem__`` for
+  each respective resource.
+
+Huh?
+----
+
+- Let's drop a pdb statement into our root factory object's ``__getitem__``
+  method and have a look.  Edit the project's ``models.py`` and add the
+  aforementioned ``pdb`` line in ``MyModel.__getitem__``
+
+  .. code-block:: python
+
+    def __getitem__(self, key):
+        import pdb; pdb.set_trace()
+        session = DBSession()
+        # ...
+
+- Restart the Pyramid application, and request a page.  Note the request
+  requires a path to hit our break-point::
+
+    http://localhost:6543/   <- misses the break-point, no traversal
+    http://localhost:6543/1  <- should find an object
+    http://localhost:6543/2  <- does not
+
+- For a very simple case, attempt to insert a missing key by default.  Set
+  item to a valid new MyModel in ``MyRoot.__getitem__`` if a match isn't
+  found in the database
+
+  .. code-block:: python
+
+        item = session.query(MyModel).get(id)
+        if item is None:
+            item = MyModel(name='test %d'%id, value=str(id))  # naive insertion
+
+- Move the break-point within the if clause to avoid the false positive hits
+
+  .. code-block:: python
+
+        if item is None:
+            import pdb; pdb.set_trace()
+            item = MyModel(name='test %d'%id, value=str(id))  # naive insertion
+
+- Run again, note multiple request to the same id continue to create
+  new MyModel instances.  That's not right!
+
+- Ah, of course, we forgot to add the new item to the session.  Another line
+  added to our ``__getitem__`` method
+
+  .. code-block:: python
+
+        if item is None:
+            import pdb; pdb.set_trace()
+            item = MyModel(name='test %d'%id, value=str(id))
+            session.add(item)
+
+- Restart and test.  Observe the stack; debug again.  Examine the item
+  returning from MyModel::
+
+    (pdb) session.query(MyModel).get(id)
+
+- Finally, we realize the item.id needs to be set as well before adding
+
+  .. code-block:: python
+
+        if item is None:
+            item = MyModel(name='test %d'%id, value=str(id))
+            item.id = id
+            session.add(item)
+
+- Many great resources can be found describing the details of using
+  pdb.  Try the interactive ``help`` (hit 'h') or a search engine near
+  you.
+
diff --git a/index.rst b/index.rst
@@ -10,6 +10,7 @@ The Pyramid Cookbook presents topical, practical usages of :mod:`Pyramid`.
    files
    exceptions
    authentication
+   deployment
    wiki2_auth
    templates
    catalog
@@ -22,6 +23,7 @@ The Pyramid Cookbook presents topical, practical usages of :mod:`Pyramid`.
    zeo
    configuration
    events
+   chameleon_i18n
    deployment/index.rst
    porting
    testing