[Checkins] SVN: zc.buildout/trunk/ Added an **experimental** extensions mechamism, mainly to support

[Jim Fulton]

Log message for revision 70103:
  Added an **experimental** extensions mechamism, mainly to support
  adding sftp support to buildouts that need it.
  

Changed:
  U   zc.buildout/trunk/README.txt
  U   zc.buildout/trunk/src/zc/buildout/buildout.py
  U   zc.buildout/trunk/src/zc/buildout/buildout.txt

-=-
Modified: zc.buildout/trunk/README.txt
===================================================================
--- zc.buildout/trunk/README.txt	2006-09-11 20:47:15 UTC (rev 70102)
+++ zc.buildout/trunk/README.txt	2006-09-11 21:32:32 UTC (rev 70103)
@@ -189,6 +189,12 @@
 Change History
 ==============
 
+1.0.0b4
+-------
+
+Added an **experimental** extensions mechamism, mainly to support
+adding sftp support to buildouts that need it.
+
 1.0.0b3
 -------
 

Modified: zc.buildout/trunk/src/zc/buildout/buildout.py
===================================================================
--- zc.buildout/trunk/src/zc/buildout/buildout.py	2006-09-11 20:47:15 UTC (rev 70102)
+++ zc.buildout/trunk/src/zc/buildout/buildout.py	2006-09-11 21:32:32 UTC (rev 70103)
@@ -137,6 +137,7 @@
                                             options['installed'])
 
         self._setup_logging()
+        self._load_extensions()
 
     def _dosubs(self, section, option, value, data, converted, seen):
         key = section, option
@@ -590,7 +591,23 @@
         args.insert(0, sys.executable)
         sys.exit(os.spawnv(os.P_WAIT, sys.executable, args))
 
+    def _load_extensions(self):
+        specs = self['buildout'].get('extensions', '').split()
+        if specs:
+            if self['buildout'].get('offline') == 'true':
+                dest = None
+            else:
+                dest = self['buildout']['eggs-directory']
+            zc.buildout.easy_install.install(
+                specs, dest,
+                path=[self['buildout']['develop-eggs-directory']],
+                working_set=pkg_resources.working_set,
+                )
+            for ep in pkg_resources.iter_entry_points('zc.buildout.extension'):
+                ep.load()(self)
+                    
 
+
 _spacey_nl = re.compile('[ \t\r\f\v]*\n[ \t\r\f\v\n]*'
                         '|'
                         '^[ \t\r\f\v]+'

Modified: zc.buildout/trunk/src/zc/buildout/buildout.txt
===================================================================
--- zc.buildout/trunk/src/zc/buildout/buildout.txt	2006-09-11 20:47:15 UTC (rev 70102)
+++ zc.buildout/trunk/src/zc/buildout/buildout.txt	2006-09-11 21:32:32 UTC (rev 70103)
@@ -1271,3 +1271,76 @@
 
 Note that the buildout script was installed but not run.  To run
 the buildout, we'd have to run the installed buildout script.
+
+Extensions
+----------
+
+An **experimental** feature allows code to be loaded and run after
+condiguration files have been read but before the buildout has begun
+any processing.  The intent is to allow special plugins such as
+urllib2 request handlers to be loaded.
+
+To load an extension, we use the extensions option and list one or
+more distribution requirements, on separate lines.  The distributions
+named will be loaded and any zc.buildout.extensions entry points found
+will be called with the buildout as an argument.
+
+Let's create a sample extension in out sample buildout created in the
+previous section:
+
+    >>> mkdir(sample_bootstrapped, 'demo')
+
+    >>> write(sample_bootstrapped, 'demo', 'demo.py', 
+    ... """
+    ... def ext(buildout):
+    ...     print 'ext', list(buildout)
+    ... """)
+
+    >>> write(sample_bootstrapped, 'demo', 'setup.py',
+    ... """
+    ... from setuptools import setup
+    ... 
+    ... setup(
+    ...     name = "demo",
+    ...     entry_points = {'zc.buildout.extension': ['ext = demo:ext']},
+    ...     )
+    ... """)
+
+Our extension just prints out the word 'demo', and lists the sections
+found in the buildout passed to it.
+
+We'll update our buildout.cfg to list the demo directory as a develop
+egg to be built:
+
+    >>> write(sample_bootstrapped, 'buildout.cfg',
+    ... """
+    ... [buildout]
+    ... develop = demo
+    ... parts =
+    ... """)
+
+    >>> os.chdir(sample_bootstrapped)
+    >>> print system(os.path.join(sample_bootstrapped, 'bin', 'buildout')),
+    buildout: Develop: /sample-bootstrapped/demo/setup.py
+
+Now we can add the extensions option.  We were a bit tricly and ran
+the buildout once with the demo develop egg defined but without the
+extension option.  This is because extensions are loaded before the
+buildout creates develop eggs. We needed to use a separate buildout
+run to create the develop egg.  Normally, when eggs are loaded from
+the network, we wouldn't need to do anything special.
+
+    >>> write(sample_bootstrapped, 'buildout.cfg',
+    ... """
+    ... [buildout]
+    ... develop = demo
+    ... extensions = demo
+    ... parts =
+    ... """)
+   
+We see that out extension is loaded and executed:
+
+    >>> print system(os.path.join(sample_bootstrapped, 'bin', 'buildout')),
+    ext ['buildout']
+    buildout: Develop: /tmp/tmpi0JFIIsample-bootstrapped/demo/setup.py
+