[Scipy-svn] r3417 - trunk/scipy/io

scipy-svn@scip... scipy-svn@scip...
Fri Oct 5 17:40:46 CDT 2007


Author: chris.burns
Date: 2007-10-05 17:40:42 -0500 (Fri, 05 Oct 2007)
New Revision: 3417

Modified:
   trunk/scipy/io/datasource.py
Log:
Update documentation and api.

Modified: trunk/scipy/io/datasource.py
===================================================================
--- trunk/scipy/io/datasource.py	2007-10-05 10:08:16 UTC (rev 3416)
+++ trunk/scipy/io/datasource.py	2007-10-05 22:40:42 UTC (rev 3417)
@@ -15,6 +15,22 @@
 # TODO: replace with newer tuple-based path module
 from scipy.io.path import path
 
+import warnings
+
+# datasource has been used for a while in the NiPy project for analyzing
+# large fmri imaging files hosted over a network.  Data would be fetched
+# via URLs, cached locally and analyzed. Under these conditions the code
+# worked well, however it needs to be documented, tested and reviewed
+# before being fully exposed to SciPy.  We hope to do this before the
+# 0.7 release.
+_api_warning = "The datasource API will be changing frequently before \
+the 0.7 release as the code is ported from the NiPy project to SciPy. \
+Some of the current public interface may become private during the port! \
+Use this module minimally, if at all, until it is stabilized."
+
+warnings.warn(_api_warning)
+
+# TODO: .zip support
 zipexts = (".gz",".bz2")
 file_openers = {".gz":gzip.open, ".bz2":bz2.BZ2File, None:file}
 
@@ -46,7 +62,7 @@
 
     *Returns*:
 
-        path
+        path_obj
             Path object of the unzipped file.
 
     """
@@ -81,12 +97,11 @@
     return False
 
 def splitzipext(filename):
-    """Return a tuple containing the filename and the zip extension separated.
+    """Split the filename into a path object and a zip extension.
 
-    If the filename does not have a zip extension then:
-        base -> filename
-        zip_ext -> None
-
+    If the filename does not have a zip extension the zip_ext in the
+    return will be None.
+    
     *Parameters*:
 
         filename : {string}
@@ -95,7 +110,7 @@
     *Returns*:
 
         base, zip_ext : {tuple}
-            Tuple containing the base file...
+            Tuple containing a path object to the file and the zip extension.
 
     """
 
@@ -104,12 +119,11 @@
     else:
         return filename, None
 
-
-
 def isurl(pathstr):
     """Test whether a given string can be parsed as a URL.
 
-    *Parameters*
+    *Parameters*:
+    
         pathstr : {string}
             The string to be checked.
 
@@ -123,10 +137,8 @@
     return bool(scheme and netloc)
 
 def ensuredirs(directory):
-    """Ensure that the given directory path actually exists.
+    """Ensure that the given directory path exists.  If not, create it.
 
-    If the directory does not exist, it is created.
-
     *Parameters*:
         directory : {path object}
         
@@ -141,10 +153,10 @@
         directory.makedirs()
 
 class Cache (object):
-    """A file cache.
+    """A local file cache for URL datasources.
 
-    The path of the cache can be specified or else use ~/.scipy/cache
-    by default.
+    The path of the cache can be specified on intialization.  The default
+    path is ~/.scipy/cache
 
 
     """
@@ -160,36 +172,92 @@
             ensuredirs(self.path)
 
     def tempfile(self, suffix='', prefix=''):
-        """ Return an temporary file name in the cache"""
+        """Create and return a temporary file in the cache.
+
+        *Parameters*:
+            suffix : {''}, optional
+
+            prefix : {''}, optional
+
+        *Returns*:
+            tmpfile : {string}
+                String containing the full path to the temporary file.
+
+        *Examples*
+
+            >>> mycache = datasource.Cache()
+            >>> mytmpfile = mycache.tempfile()
+            >>> mytmpfile
+            '/home/guido/.scipy/cache/GUPhDv'
+
+        """
+
         _tmp, fname = mkstemp(suffix, prefix, self.path)
         return fname
 
     def filepath(self, uri):
+        """Return a path object to the uri in the cache.
+
+        *Parameters*:
+            uri : {string}
+                Filename to use in the returned path object.
+
+        *Returns*:
+            path_obj
+                Path object for the given uri.
+                
+        *Examples*
+
+            >>> mycache = datasource.Cache()
+            >>> mycache.filepath('xyzcoords.txt')
+            path('/home/guido/.scipy/cache/yzcoords.txt')
+
         """
-        Return the complete path + filename within the cache.
-        """
-        (_, netloc, upath, _, _, _) = urlparse(uri)
+        # TODO: Change to non-public?
+        # TODO: BUG: First character is removed in the returned path. Why?
+        #       It appears the Cache is designed to work with URLs only!
+
+        (_tmp, netloc, upath, _tmp, _tmp, _tmp) = urlparse(uri)
         return self.path.joinpath(netloc, upath[1:])
 
     def filename(self, uri):
-        """
-        Return the complete path + filename within the cache.
+        """Return the complete path + filename within the cache.
 
-        :Returns: ``string``
+        *Parameters*:
+            uri : {string}
+                Filename to usein the returned path.
+                
+        *Returns*:
+            filename
+
+        *Examples*
+
+            >>> mycache = datasource.Cache()
+            >>> mycache.filename('xyzcoords.txt')
+            '/home/guido/.scipy/cache/yzcoords.txt'
+
         """
+        # TODO: Change to non-public?
+                
         return str(self.filepath(uri))
 
     def cache(self, uri):
-        """
-        Copy a file into the cache.
+        """Copy a file into the cache.
 
         :Returns: ``None``
         """
         if self.iscached(uri):
             return
+
+        print 'cache uri:', uri
+        
         upath = self.filepath(uri)
+
+        print 'upath:', upath
+        
         ensuredirs(upath.dirname())
         try:
+            print 'uri:', uri
             openedurl = urlopen(uri)
         except:
             raise IOError("url not found: "+str(uri))
@@ -225,7 +293,8 @@
 class DataSource (object):
     """A generic data source class.
 
-    Data could be from a file, URL, cached file.
+    Data sets could be from a file, a URL, or a cached file.  They may also
+    be compressed or uncompressed.
 
     TODO: Improve DataSource docstring
 



More information about the Scipy-svn mailing list