[py-svn] r6977 - py/dist/doc

[hpk at codespeak.net]

Author: hpk
Date: Sun Oct 17 16:37:59 2004
New Revision: 6977

Modified:
   py/dist/doc/future.txt
Log:
added a new future chapter on system/executable interaction ... 



Modified: py/dist/doc/future.txt
==============================================================================
--- py/dist/doc/future.txt	(original)
+++ py/dist/doc/future.txt	Sun Oct 17 16:37:59 2004
@@ -11,8 +11,9 @@
 thoughts and not always real code so read with some caution. 
 This is not a reference guide (tm).* 
 
-Direction: A more generalizing view on ``py.path`` objects 
-==========================================================
+Direction: A more general view on ``py.path`` objects 
+=====================================================
+.. _`a more general view on path objects`:
 
 Seen from a more general persective, the current ``fspy`` path 
 offers a way to go from a file to the structured content of 
@@ -281,3 +282,101 @@
 
 .. _`py.execnet`: execnet.html 
 .. _`wrapping techniques PyPy uses`: http://codespeak.net/pypy/index.cgi?doc/wrapping.html
+
+
+Supporting interaction with system utilities/binaries
+=====================================================
+
+Currently, the py lib offers a simple way to interact with 
+executables in shell style::
+
+    out = py.process.cmdexec('ls -v')
+
+which will raise an exception in case of a return-code other than 0
+and otherwise return the output of the child process. 
+
+shortcomings of the current approach
+------------------------------------
+
+However, the ``cmdexec`` approach has a few shortcomings:: 
+
+- it relies on the underlying system shell
+
+- it neccessitates shell-escaping for expressing arguments
+
+- it does not easily allow to "fix" the binary you want to run.  
+
+- it only allows to execute executables from the local 
+  filesystem 
+
+path objects come to rescue 
+---------------------------
+
+We probably want to offer a stripped down functionality of what
+the new `PEP-324 subprocess module`_ offers.  The main functionality 
+of synchronously should have a straightforward api, like:: 
+
+    binsvn.execute('ls', 'http://codespeak.net/svn') 
+
+where ``binsvn`` is a path that points to the ``svn`` commandline
+binary. Note that this function would not offer any shell-escaping
+so you really have to pass in separated arguments.  This idea
+fits nicely into `a more general view on path objects`_. 
+
+For a first go, we could simply reuse the existing `subprocess
+implementation`_ but would not expose any of its API apart
+from the above "execute()" method. 
+
+finding an executable
+---------------------
+
+Finding an executable is quite different on multiple platforms. 
+At least, the ``PATH`` environment variable based search on
+unix platforms should be supported with something like::
+
+    py.path.local.sysfind('svn') 
+
+which would return the first path found to the ``svn`` exectuable. 
+In principle, 'sysfind' deploys platform specific algorithms
+to perform the search.  On Windows, for example, it may look
+at the registry. 
+
+To make the story complete, we can allow to pass in a "checker"
+that would be called for each found executable.  For example, 
+if you have multiple binaries available you may want to select 
+the right version:: 
+
+    def mysvn(p):
+        """ check that the given svn binary has version 1.1. """
+        line = p.execute('--version'').readlines()[0]
+        if line.find('version 1.1'): 
+            return p 
+
+    py.path.local.sysfind('svn', checker=mysvn) 
+
+world wide subversive interaction?
+----------------------------------
+
+While we are at it, we may want to run python scripts from 
+the net::
+
+    vadm = py.path.svnurl('http://codespeak.net/svn/vadm/dist/vadm/cmdline.py') 
+    stdoutput = vadm.execute('diff')
+
+To be able to execute this code fragement, we need either or all of 
+
+- an improved import system that allows remote imports 
+
+- a way to specify what the "neccessary" python import
+  directories are. for example, the above scriptlet will
+  require a certain root included in the python search for module 
+  in order to execute something like "import vadm". 
+
+- a way to specify dependencies ... which opens up another
+  interesting can of worms, suitable for another chapter
+  in the neverending `future book`_. 
+
+
+.. _`future book`: future.html 
+.. _`PEP-324 subprocess module`: http://www.python.org/peps/pep-0324.html
+.. _`subprocess implementation`: http://www.lysator.liu.se/~astrand/popen5/