[Checkins] SVN: grok/branches/kteague-getapp/src/grok/ add grok.getApplication() feature

[Kevin Teague]

Log message for revision 106050:
  add grok.getApplication() feature

Changed:
  U   grok/branches/kteague-getapp/src/grok/__init__.py
  A   grok/branches/kteague-getapp/src/grok/ftests/application/
  A   grok/branches/kteague-getapp/src/grok/ftests/application/__init__.py
  A   grok/branches/kteague-getapp/src/grok/ftests/application/application.py
  U   grok/branches/kteague-getapp/src/grok/ftests/test_grok_functional.py
  U   grok/branches/kteague-getapp/src/grok/interfaces.py
  U   grok/branches/kteague-getapp/src/grok/util.py

-=-
Modified: grok/branches/kteague-getapp/src/grok/__init__.py
===================================================================
--- grok/branches/kteague-getapp/src/grok/__init__.py	2009-11-27 00:23:25 UTC (rev 106049)
+++ grok/branches/kteague-getapp/src/grok/__init__.py	2009-11-27 01:11:45 UTC (rev 106050)
@@ -57,6 +57,7 @@
 
 from zope.event import notify
 from zope.app.component.hooks import getSite
+from grok.util import getApplication
 from zope.lifecycleevent import (
     IObjectCreatedEvent, ObjectCreatedEvent,
     IObjectModifiedEvent, ObjectModifiedEvent,

Added: grok/branches/kteague-getapp/src/grok/ftests/application/__init__.py
===================================================================
--- grok/branches/kteague-getapp/src/grok/ftests/application/__init__.py	                        (rev 0)
+++ grok/branches/kteague-getapp/src/grok/ftests/application/__init__.py	2009-11-27 01:11:45 UTC (rev 106050)
@@ -0,0 +1 @@
+# this is a package

Added: grok/branches/kteague-getapp/src/grok/ftests/application/application.py
===================================================================
--- grok/branches/kteague-getapp/src/grok/ftests/application/application.py	                        (rev 0)
+++ grok/branches/kteague-getapp/src/grok/ftests/application/application.py	2009-11-27 01:11:45 UTC (rev 106050)
@@ -0,0 +1,46 @@
+"""
+An application is a mixin for grok application objects.
+
+You can get the current application by using the
+grok.getApplication() function. Typically this will return the same
+object as grok.getSite(), but it is possible to have sub-Site objects
+which will be returned for grok.getSite(), where-as grok.getApplication
+will walk up the tree until it reaches the top-level site object.
+
+Let's create an application, then get it using grok.getApplication():
+
+  >>> import grok
+  >>> import zope.site.hooks
+  >>> root = getRootFolder()
+  >>> app = grok.util.create_application(Cave, root, 'mycave')
+  >>> root['cave'] = app
+  >>> zope.site.hooks.setSite(app)
+  >>> grok.getApplication()
+  <grok.ftests.application.application.Cave object at ...>
+  
+Or get it using grok.getSite():
+
+  >>> grok.getSite()
+  <grok.ftests.application.application.Cave object at ...>
+  
+Now we can create a container with a sub-site. When we call grok.getSite()
+we'll get the box:
+
+  >>> root['cave']['box'] = WoodBox()
+  >>> zope.site.hooks.setSite(root['cave']['box'])
+  >>> grok.getSite()
+  <grok.ftests.application.application.WoodBox object at ...>
+  
+But when we call grok.getApplication() we get the cave:
+  
+  >>> grok.getApplication()
+  <grok.ftests.application.application.Cave object at ...>
+
+"""
+import grok
+
+class Cave(grok.Container, grok.Application):
+    """A shelter for homeless cavemen."""
+
+class WoodBox(grok.Container, grok.Site):
+    """A prehistoric container for holding ZCA registries."""

Modified: grok/branches/kteague-getapp/src/grok/ftests/test_grok_functional.py
===================================================================
--- grok/branches/kteague-getapp/src/grok/ftests/test_grok_functional.py	2009-11-27 00:23:25 UTC (rev 106049)
+++ grok/branches/kteague-getapp/src/grok/ftests/test_grok_functional.py	2009-11-27 01:11:45 UTC (rev 106050)
@@ -71,7 +71,8 @@
 def test_suite():
     suite = unittest.TestSuite()
     for name in ['xmlrpc', 'traversal', 'form', 'url', 'security', 'rest',
-                 'catalog', 'site', 'viewlet', 'json', 'lifecycle']:
+                 'catalog', 'site', 'application', 'viewlet', 'json',
+                 'lifecycle']:
         suite.addTest(suiteFromPackage(name))
     return suite
 

Modified: grok/branches/kteague-getapp/src/grok/interfaces.py
===================================================================
--- grok/branches/kteague-getapp/src/grok/interfaces.py	2009-11-27 00:23:25 UTC (rev 106049)
+++ grok/branches/kteague-getapp/src/grok/interfaces.py	2009-11-27 01:11:45 UTC (rev 106050)
@@ -147,6 +147,8 @@
     def getSite():
         """Get the current site."""
 
+    def getApplication():
+        """Get the current application."""
 
     IRESTSkinType = interface.Attribute('The REST skin type')
 

Modified: grok/branches/kteague-getapp/src/grok/util.py
===================================================================
--- grok/branches/kteague-getapp/src/grok/util.py	2009-11-27 00:23:25 UTC (rev 106049)
+++ grok/branches/kteague-getapp/src/grok/util.py	2009-11-27 01:11:45 UTC (rev 106050)
@@ -14,6 +14,7 @@
 """Grok utility functions.
 """
 import grok
+import grok.interfaces
 import zope.event
 import zope.location.location
 from zope import interface
@@ -23,7 +24,6 @@
 
 from grokcore.security.util import check_permission
 
-
 def make_checker(factory, view_factory, permission, method_names=None):
     """Make a checker for a view_factory associated with factory.
 
@@ -65,6 +65,20 @@
     interface.directlyProvides(request, *ifaces)
 
 
+def getApplication():
+    """Get the application."""
+    site = grok.getSite()
+    if grok.interfaces.IApplication.providedBy(site):
+        return site
+    else:
+        # another sub-site is within the application, walk up
+        # the tree until we get to the application
+        parent = site.__parent__
+        while not grok.interfaces.IApplication.providedBy(parent):
+            parent = parent.__parent__
+        return parent
+
+
 def create_application(factory, container, name):
     """Creates an application and triggers the events from
     the application lifecycle.