[Assorted-commits] SF.net SVN: assorted:[1631] python-commons/tags

[<yan...@us...>]

Revision: 1631
          http://assorted.svn.sourceforge.net/assorted/?rev=1631&view=rev
Author:   yangzhang
Date:     2010-04-18 00:46:17 +0000 (Sun, 18 Apr 2010)

Log Message:
-----------
tagged 0.7 release

Added Paths:
-----------
    python-commons/tags/0.7/
    python-commons/tags/0.7/README
    python-commons/tags/0.7/publish.bash
    python-commons/tags/0.7/setup.py
    python-commons/tags/0.7/src/commons/__init__.py
    python-commons/tags/0.7/src/commons/files.py

Removed Paths:
-------------
    python-commons/tags/0.7/README
    python-commons/tags/0.7/publish.bash
    python-commons/tags/0.7/setup.py
    python-commons/tags/0.7/src/commons/__init__.py
    python-commons/tags/0.7/src/commons/files.py

Deleted: python-commons/tags/0.7/README
===================================================================
--- python-commons/trunk/README	2010-04-18 00:18:13 UTC (rev 1625)
+++ python-commons/tags/0.7/README	2010-04-18 00:46:17 UTC (rev 1631)
@@ -1,93 +0,0 @@
-[documentation](doc)
-
-Overview
---------
-
-Python Commons is a general-purpose library for Python. To get a sense of
-what it provides, please glance over the [documentation](doc).
-
-Requirements
-------------
-
-- [Python](http://python.org/) 2.5
-- [setuptools](http://peak.telecommunity.com/DevCenter/setuptools) 0.6
-
-Certain sub-modules have extra requirements:
-
-- `async` requires [Twisted](http://twistedmatrix.com/trac/) 2.5
-- `files` requires [path](http://www.jorendorff.com/articles/python/path/) 2.2
-
-This library has only been tested on Linux.
-
-Setup
------
-
-To install, run `easy_install python-commons`, or download the source tarball
-and run `python setup.py install`.
-
-Related Work
-------------
-
-- [ASPN Cookbook]: a valuable repository of Python snippets
-- [AIMA Utilities]: accompaniment to a popular AI textbook
-
-[ASPN Cookbook]: http://aspn.activestate.com/ASPN/Cookbook/Python
-[AIMA Utilities]: http://aima.cs.berkeley.edu/python/utils.py
-
-Changes
--------
-
-version 0.6, 2008-10-??
-
-- to strs added unwrap, indent, unindent, remove_empty_lines, underline,
-  dos2unix, quotejs, unicode2html, html2unicode, nat_lang_join, or_join,
-  and_join
-- to misc added sendmail, days, settimeout, run, TerminalController
-- imported and updated jorendorff's path.py
-- to startup added command_name
-- to files added read_file, write_file, write_or_rm, is_nonempty_file
-- added sqlhash and sqlhash backend for shelf
-- to structs added dicts2structs, structs2dicts; FreeStruct renamed to
-  free_struct
-- to seqs added span, group_as_subseqs
-- decs.pickle_memoized uses protocol 2
-- general tweaks; epydoc fixes
-- python 2.6-ready
-- released for [Mailing List Filter], [MIT 6.00] courseware
-
-[Mailing List Filter]: http://assorted.sourceforge.net/mailing-list-filter/
-[MIT 6.00]: http://web.mit.edu/~6.00/
-
-version 0.5, 2008-05-14
-
-- added `cp1252_to_unicode()`
-- made `setup()` more flexible
-- released for
-  [gbookmark2delicious](http://gbookmark2delicious.googlecode.com/)
-
-version 0.4, 2008-05-08
-
-- removed extraneous debug print statements
-- added `logout()` context manager
-- added `seq()`, `default_if_none()`
-- fixed missing `import` bug
-- released for [Mailing List
-  Filter](http://assorted.sf.net/mailing-list-filter/)
-
-version 0.3, 2008-04-30
-
-- added versioned guards
-- added file memoization
-- added retry with exp backoff
-- added `countstep()`
-- released for
-  [gbookmark2delicious](http://gbookmark2delicious.googlecode.com/)
-
-version 0.2, 2008-02-04
-
-- added `clients`, `setup`
-- released for [icedb](http://cartel.csail.mit.edu/icedb/)
-
-version 0.1, 2007-03-24
-
-- initial release

Copied: python-commons/tags/0.7/README (from rev 1627, python-commons/trunk/README)
===================================================================
--- python-commons/tags/0.7/README	                        (rev 0)
+++ python-commons/tags/0.7/README	2010-04-18 00:46:17 UTC (rev 1631)
@@ -0,0 +1,117 @@
+[documentation](doc)
+
+Overview
+========
+
+Python Commons is a general-purpose library for Python. To get a sense of
+what it provides, please glance over the [documentation](doc).
+
+Requirements
+============
+
+- [Python](http://python.org/) 2.6
+- [setuptools](http://peak.telecommunity.com/DevCenter/setuptools) 0.6
+
+Certain sub-modules have extra requirements:
+
+- `async` requires [Twisted](http://twistedmatrix.com/trac/) 2.5
+
+This library has only been tested on Linux.
+
+Setup
+=====
+
+To install, run `easy_install python-commons`, or download the source tarball
+and run `python setup.py install`.
+
+Related
+=======
+
+The code here generally tries to complement the code already available in a
+number of other general-purpose utility libraries for Python:
+
+- [AIMA Utilities]: accompanies a popular AI textbook
+- [itools]
+- [Grizzled]
+- [PyUtilib]
+- [Py]
+
+See also:
+
+- [ASPN Cookbook]: a valuable repository of Python snippets
+
+[ASPN Cookbook]: http://aspn.activestate.com/ASPN/Cookbook/Python
+[AIMA Utilities]: http://aima.cs.berkeley.edu/python/utils.py
+[itools]: http://www.hforge.org/itools
+[Grizzled]: http://bmc.github.com/grizzled/
+[PyUtilib]: https://software.sandia.gov/trac/pyutilib
+[Py]: http://codespeak.net/py/dist/
+
+Changes
+=======
+
+version 0.7, 2010-04-17
+
+- released for gbookmark2delicious
+- enhanced free_struct
+- added recursion_guard decorator
+- complete html2unicode
+- wrap keys and values as strings in sqlhash
+- logger should append by default
+- added inet_nltoa, inet_hltoa
+- internally use commons.path instead of (unmaintained) path.py
+
+version 0.6, 2009-06-03
+
+- to strs added unwrap, indent, unindent, remove_empty_lines, underline,
+  dos2unix, quotejs, unicode2html, html2unicode, nat_lang_join, or_join,
+  and_join
+- to misc added sendmail, days, settimeout, run, TerminalController
+- imported and updated jorendorff's path.py
+- to startup added command_name
+- to files added read_file, write_file, write_or_rm, is_nonempty_file
+- added sqlhash and sqlhash backend for shelf
+- to structs added dicts2structs, structs2dicts; FreeStruct renamed to
+  free_struct
+- to seqs added span, group_as_subseqs
+- decs.pickle_memoized uses protocol 2
+- general tweaks; epydoc fixes
+- python 2.6-ready
+- released for [Mailing List Filter], [MIT 6.00] courseware
+
+[Mailing List Filter]: http://assorted.sourceforge.net/mailing-list-filter/
+[MIT 6.00]: http://web.mit.edu/~6.00/
+
+version 0.5, 2008-05-14
+
+- added `cp1252_to_unicode()`
+- made `setup()` more flexible
+- released for
+  [gbookmark2delicious](http://gbookmark2delicious.googlecode.com/)
+
+version 0.4, 2008-05-08
+
+- removed extraneous debug print statements
+- added `logout()` context manager
+- added `seq()`, `default_if_none()`
+- fixed missing `import` bug
+- released for [Mailing List
+  Filter](http://assorted.sf.net/mailing-list-filter/)
+
+version 0.3, 2008-04-30
+
+- added versioned guards
+- added file memoization
+- added retry with exp backoff
+- added `countstep()`
+- released for
+  [gbookmark2delicious](http://gbookmark2delicious.googlecode.com/)
+
+version 0.2, 2008-02-04
+
+- added `clients`, `setup`
+- released for [icedb](http://cartel.csail.mit.edu/icedb/)
+
+version 0.1, 2007-03-24
+
+- initial release

Deleted: python-commons/tags/0.7/publish.bash
===================================================================
--- python-commons/trunk/publish.bash	2010-04-18 00:18:13 UTC (rev 1625)
+++ python-commons/tags/0.7/publish.bash	2010-04-18 00:46:17 UTC (rev 1631)
@@ -1,15 +0,0 @@
-#!/usr/bin/env bash
-
-post-stage() {
-  epydoc -v -o $stagedir/doc src/commons/
-}
-
-echo 'Remember to keep versions in sync in all three locations:'
-echo '__init__.py, README (Changes), setup.bash, and setup.py'
-
-fullname='Python Commons'
-version=0.6
-license=psf
-websrcs=( README )
-rels=( pypi: )
-. assorted.bash "$@"

Copied: python-commons/tags/0.7/publish.bash (from rev 1630, python-commons/trunk/publish.bash)
===================================================================
--- python-commons/tags/0.7/publish.bash	                        (rev 0)
+++ python-commons/tags/0.7/publish.bash	2010-04-18 00:46:17 UTC (rev 1631)
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+post-stage() {
+  epydoc -v -o $stagedir/doc src/commons/
+}
+
+echo 'Remember to keep versions in sync in all three locations:'
+echo '__init__.py, README (Changes), setup.bash, and setup.py'
+
+fullname='Python Commons'
+version=0.7
+license=psf
+websrcs=( README )
+rels=( pypi: )
+. assorted.bash "$@"

Deleted: python-commons/tags/0.7/setup.py
===================================================================
--- python-commons/trunk/setup.py	2010-04-18 00:18:13 UTC (rev 1625)
+++ python-commons/tags/0.7/setup.py	2010-04-18 00:46:17 UTC (rev 1631)
@@ -1,43 +0,0 @@
-#!/usr/bin/env python
-# -*- mode: python; tab-width: 4; indent-tabs-mode: nil; py-indent-offset: 4; -*-
-# vim:ft=python:et:sw=4:ts=4
-
-import os,sys
-sys.path.insert( 0, os.path.join( os.path.dirname( sys.argv[0] ), 'src' ) )
-from commons import setup
-
-pkg_info_text = """
-Metadata-Version: 1.1
-Name: python-commons
-Version: 0.6
-Author: Yang Zhang
-Author-email: yaaang NOSPAM at REMOVECAPS gmail
-Home-page: http://assorted.sourceforge.net/python-commons
-Summary: Python Commons
-License: Python Software Foundation License
-Description: General-purpose library of utilities and extensions to the
-        standard library.
-Keywords: Python,common,commons,utility,utilities,library,libraries
-Platform: any
-Provides: commons
-Classifier: Development Status :: 4 - Beta
-Classifier: Environment :: No Input/Output (Daemon)
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Python Software Foundation License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python
-Classifier: Topic :: Communications
-Classifier: Topic :: Database
-Classifier: Topic :: Internet
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Topic :: System
-Classifier: Topic :: System :: Filesystems
-Classifier: Topic :: System :: Logging
-Classifier: Topic :: System :: Networking
-Classifier: Topic :: Text Processing
-Classifier: Topic :: Utilities
-"""
-
-setup.run_setup( pkg_info_text,
-                 #scripts = ['frontend/py_hotshot.py'],
-                 )

Copied: python-commons/tags/0.7/setup.py (from rev 1628, python-commons/trunk/setup.py)
===================================================================
--- python-commons/tags/0.7/setup.py	                        (rev 0)
+++ python-commons/tags/0.7/setup.py	2010-04-18 00:46:17 UTC (rev 1631)
@@ -0,0 +1,43 @@
+#!/usr/bin/env python
+# -*- mode: python; tab-width: 4; indent-tabs-mode: nil; py-indent-offset: 4; -*-
+# vim:ft=python:et:sw=4:ts=4
+
+import os,sys
+sys.path.insert( 0, os.path.join( os.path.dirname( sys.argv[0] ), 'src' ) )
+from commons import setup
+
+pkg_info_text = """
+Metadata-Version: 1.1
+Name: python-commons
+Version: 0.7
+Author: Yang Zhang
+Author-email: yaaang NOSPAM at REMOVECAPS gmail
+Home-page: http://assorted.sourceforge.net/python-commons
+Summary: Python Commons
+License: Python Software Foundation License
+Description: General-purpose library of utilities and extensions to the
+        standard library.
+Keywords: Python,common,commons,utility,utilities,library,libraries
+Platform: any
+Provides: commons
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: No Input/Output (Daemon)
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Python Software Foundation License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Topic :: Communications
+Classifier: Topic :: Database
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: System :: Logging
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Text Processing
+Classifier: Topic :: Utilities
+"""
+
+setup.run_setup( pkg_info_text,
+                 #scripts = ['frontend/py_hotshot.py'],
+                 )

Deleted: python-commons/tags/0.7/src/commons/__init__.py
===================================================================
--- python-commons/trunk/src/commons/__init__.py	2010-04-18 00:18:13 UTC (rev 1625)
+++ python-commons/tags/0.7/src/commons/__init__.py	2010-04-18 00:46:17 UTC (rev 1631)
@@ -1,40 +0,0 @@
-# -*- mode: python; tab-width: 4; indent-tabs-mode: nil; py-indent-offset: 4; -*-
-# vim:ft=python:et:sw=4:ts=4
-
-"""
-U{Python Commons<http://assorted.sf.net/python-commons>} is a
-general-purpose library.
-
-@author: Yang Zhang
-@copyright: Yang Zhang unless otherwise noted
-@license: PSF
-"""
-
-__version__ = ( 0, 6, 0 )
-__all__ = [ 'async',
-            'control',
-            'decs',
-            'environ',
-            'exceps',
-            'files',
-            'interp',
-            'log',
-            'misc',
-            'networking',
-            'progress',
-            'seqs',
-            'servers',
-            'startup',
-            'strs',
-            'structs',
-            'threads',
-            'trace' ]
-
-# TODO more resources:
-# http://aima.cs.berkeley.edu/python/utils.py
-# http://aspn.activestate.com/ASPN/Cookbook/Python
-# http://aspn.activestate.com/ASPN/Cookbook/Python?&recipe_status=editors
-# http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/413486
-# interesting:
-# http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/259174
-# http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/473790

Copied: python-commons/tags/0.7/src/commons/__init__.py (from rev 1629, python-commons/trunk/src/commons/__init__.py)
===================================================================
--- python-commons/tags/0.7/src/commons/__init__.py	                        (rev 0)
+++ python-commons/tags/0.7/src/commons/__init__.py	2010-04-18 00:46:17 UTC (rev 1631)
@@ -0,0 +1,28 @@
+"""
+U{Python Commons<http://assorted.sf.net/python-commons>} is a
+general-purpose library.
+
+@author: Yang Zhang
+@copyright: Yang Zhang unless otherwise noted
+@license: PSF
+"""
+
+__version__ = ( 0, 7, 0 )
+__all__ = [ 'async',
+            'control',
+            'decs',
+            'environ',
+            'exceps',
+            'files',
+            'interp',
+            'log',
+            'misc',
+            'networking',
+            'progress',
+            'seqs',
+            'servers',
+            'startup',
+            'strs',
+            'structs',
+            'threads',
+            'trace' ]

Deleted: python-commons/tags/0.7/src/commons/files.py
===================================================================
--- python-commons/trunk/src/commons/files.py	2010-04-18 00:18:13 UTC (rev 1625)
+++ python-commons/tags/0.7/src/commons/files.py	2010-04-18 00:46:17 UTC (rev 1631)
@@ -1,205 +0,0 @@
-# -*- mode: python; tab-width: 4; indent-tabs-mode: nil; py-indent-offset: 4; -*-
-# vim:ft=python:et:sw=4:ts=4
-
-"""
-File and directory manipulation.
-
-@var invalid_filename_chars: The characters which are usually
-prohibited on most modern file systems.
-
-@var invalid_filename_chars_regex: A regex character class constructed
-from L{invalid_filename_chars}.
-"""
-
-from __future__ import with_statement
-
-__all__ = '''
-soft_makedirs
-temp_dir
-cleanse_filename
-invalid_filename_chars
-invalid_filename_chars_regex
-disk_double_buffer
-versioned_guard
-versioned_cache
-read_file
-write_file
-write_or_rm
-is_nonempty_file
-'''.split()
-
-import os, re, tempfile
-from cPickle import *
-from path import path
-
-def soft_makedirs( path ):
-    """
-    Emulate C{mkdir -p} (doesn't complain if it already exists).
-
-    @param path: The path of the directory to create.
-    @type path: str
-
-    @raise OSError: If it cannot create the directory. It only
-    swallows OS error 17.
-    """
-    try:
-        os.makedirs( path )
-    except OSError, ex:
-        if ex.errno == 17:
-            pass
-        else:
-            raise
-
-def temp_dir( base_dir_name, do_create_subdir = True ):
-    """
-    Get a temporary directory without polluting top-level /tmp. This follows
-    Ubuntu's conventions, choosing a temporary directory name based on
-    the given name plus the user name to avoid user conflicts.
-
-    @param base_dir_name: The "name" of the temporary directory. This
-    is usually identifies the purpose of the directory, or the
-    application to which the temporary directory belongs. E.g., if joe
-    calls passes in C{"ssh-agent"} on a standard Linux/Unix system,
-    then the full path of the temporary directory will be
-    C{"/tmp/ssh-agent-joe"}.
-    @type base_dir_name: str
-
-    @param do_create_subdir: If C{True}, then creates a
-    sub-sub-directory within the temporary sub-directory (and returns
-    the path to that). The sub-sub-directory's name is randomized
-    (uses C{tempfile.mkdtemp}).
-    @type do_create_subdir: bool
-
-    @return: The path to the temporary (sub-)sub-directory.
-    @rtype: str
-    """
-    base_dir_name += '-' + os.environ[ 'USER' ]
-    base_dir = path( tempfile.gettempdir() ) / base_dir_name
-    soft_makedirs( base_dir )
-    if do_create_subdir:
-        return tempfile.mkdtemp( dir = base_dir )
-    else:
-        return base_dir
-
-invalid_filename_chars = r'*|\/:<>?'
-invalid_filename_chars_regex = r'[*|\\\/:<>?]'
-
-def cleanse_filename( filename ):
-    """
-    Replaces all problematic characters in a filename with C{"_"}, as
-    specified by L{invalid_filename_chars}.
-
-    @param filename: The filename to cleanse.
-    @type filename: str
-    """
-    pattern = invalid_filename_chars_regex
-    return re.sub( pattern, '_', filename )
-
-class disk_double_buffer( object ):
-    """
-    A simple disk double-buffer. One file is for reading, the other is for
-    writing, and a facility for swapping the two roles is provided.
-    """
-    def __init__( self, path_base, do_persist = True ):
-        self.paths = map( path, [ path_base + '.0', path_base + '.1' ] )
-        self.do_persist = do_persist
-        self.switch_status = path( path_base + '.switched' )
-        if not do_persist or not self.switch_status.exists():
-            self.w, self.r = 0, 1 # default
-        else:
-            self.w, self.r = 1, 0
-        self.reload_files()
-    def reload_files( self ):
-        self.writer = file( self.paths[ self.w ], 'w' )
-        if not self.paths[ self.r ].exists():
-            self.paths[ self.r ].touch()
-        self.reader = file( self.paths[ self.r ] )
-    def switch( self ):
-        self.close()
-        if self.do_persist:
-            if self.w == 0: self.switch_status.touch()
-            else:           self.switch_status.remove()
-        self.r, self.w = self.w, self.r
-        self.reload_files()
-    def write( self, x ):
-        self.writer.write( x )
-    def read( self, len = 8192 ):
-        return self.reader.read( len )
-    def close( self ):
-        self.reader.close()
-        self.writer.close()
-
-def versioned_guard(path, fresh_version):
-    """
-    Maintain a version object.  This is useful for working with versioned
-    caches.
-
-    @param path: The path to the file containing the cached version object.
-    @type path: str
-
-    @param fresh_version: The actual latest version that the cached version
-    should be compared against.
-    @type fresh_version: object (any type that can be compared)
-
-    @return: True iff the cached version is obsolete (less than the fresh
-    version or doesn't exist).
-    @rtype: bool
-    """
-    cache_version = None
-    try:
-        with file( path ) as f: cache_version = load(f)
-    except IOError, (errno, errstr):
-        if errno != 2: raise
-    if cache_version is None or fresh_version > cache_version:
-        with file( path, 'w' ) as f: dump(fresh_version, f)
-        return True
-    else:
-        return False
-
-def versioned_cache(version_path, fresh_version, cache_path, cache_func):
-    """
-    If fresh_version is newer than the version in version_path, then invoke
-    cache_func and cache the result in cache_path (using pickle).
-
-    Note the design flaw with L{versioned_guard}: the updated version value is
-    stored immediately, rather than after updating the cache.
-
-    @param version_path: The path to the file version.
-    @type version_path: str
-
-    @param fresh_version: The actual, up-to-date version value.
-    @type fresh_version: object (any type that can be compared)
-
-    @param cache_path: The path to the cached data.
-    @type cache_path: str
-
-    @param cache_func: The function that produces the fresh data to be cached.
-    @type cache_func: function (no arguments)
-    """
-    if versioned_guard( version_path, fresh_version ):
-        # cache obsolete, force-fetch new data
-        result = cache_func()
-        with file(cache_path, 'w') as f: dump(result, f)
-        return result
-    else:
-        # cache up-to-date (should be available since dlcs-timestamp exists!)
-        with file(cache_path) as f: return load(f)
-
-def read_file(path):
-    f = file(path)
-    try: return f.read()
-    finally: f.close()
-
-def write_file(path, contents):
-    f = file(path,'w')
-    try: f.write(contents)
-    finally: f.close()
-
-def write_or_rm(p, contents):
-    'Write the file or remove it if contents is empty.'
-    p = path(p)
-    if contents.strip(): write_file(p, contents)
-    elif p.isfile(): p.remove()
-
-def is_nonempty_file(path):
-    return path.isfile() and read_file(path).strip() != ''

Copied: python-commons/tags/0.7/src/commons/files.py (from rev 1626, python-commons/trunk/src/commons/files.py)
===================================================================
--- python-commons/tags/0.7/src/commons/files.py	                        (rev 0)
+++ python-commons/tags/0.7/src/commons/files.py	2010-04-18 00:46:17 UTC (rev 1631)
@@ -0,0 +1,205 @@
+# -*- mode: python; tab-width: 4; indent-tabs-mode: nil; py-indent-offset: 4; -*-
+# vim:ft=python:et:sw=4:ts=4
+
+"""
+File and directory manipulation.
+
+@var invalid_filename_chars: The characters which are usually
+prohibited on most modern file systems.
+
+@var invalid_filename_chars_regex: A regex character class constructed
+from L{invalid_filename_chars}.
+"""
+
+from __future__ import with_statement
+
+__all__ = '''
+soft_makedirs
+temp_dir
+cleanse_filename
+invalid_filename_chars
+invalid_filename_chars_regex
+disk_double_buffer
+versioned_guard
+versioned_cache
+read_file
+write_file
+write_or_rm
+is_nonempty_file
+'''.split()
+
+import os, re, tempfile
+from cPickle import *
+from commons.path import path
+
+def soft_makedirs( path ):
+    """
+    Emulate C{mkdir -p} (doesn't complain if it already exists).
+
+    @param path: The path of the directory to create.
+    @type path: str
+
+    @raise OSError: If it cannot create the directory. It only
+    swallows OS error 17.
+    """
+    try:
+        os.makedirs( path )
+    except OSError, ex:
+        if ex.errno == 17:
+            pass
+        else:
+            raise
+
+def temp_dir( base_dir_name, do_create_subdir = True ):
+    """
+    Get a temporary directory without polluting top-level /tmp. This follows
+    Ubuntu's conventions, choosing a temporary directory name based on
+    the given name plus the user name to avoid user conflicts.
+
+    @param base_dir_name: The "name" of the temporary directory. This
+    is usually identifies the purpose of the directory, or the
+    application to which the temporary directory belongs. E.g., if joe
+    calls passes in C{"ssh-agent"} on a standard Linux/Unix system,
+    then the full path of the temporary directory will be
+    C{"/tmp/ssh-agent-joe"}.
+    @type base_dir_name: str
+
+    @param do_create_subdir: If C{True}, then creates a
+    sub-sub-directory within the temporary sub-directory (and returns
+    the path to that). The sub-sub-directory's name is randomized
+    (uses C{tempfile.mkdtemp}).
+    @type do_create_subdir: bool
+
+    @return: The path to the temporary (sub-)sub-directory.
+    @rtype: str
+    """
+    base_dir_name += '-' + os.environ[ 'USER' ]
+    base_dir = path( tempfile.gettempdir() ) / base_dir_name
+    soft_makedirs( base_dir )
+    if do_create_subdir:
+        return tempfile.mkdtemp( dir = base_dir )
+    else:
+        return base_dir
+
+invalid_filename_chars = r'*|\/:<>?'
+invalid_filename_chars_regex = r'[*|\\\/:<>?]'
+
+def cleanse_filename( filename ):
+    """
+    Replaces all problematic characters in a filename with C{"_"}, as
+    specified by L{invalid_filename_chars}.
+
+    @param filename: The filename to cleanse.
+    @type filename: str
+    """
+    pattern = invalid_filename_chars_regex
+    return re.sub( pattern, '_', filename )
+
+class disk_double_buffer( object ):
+    """
+    A simple disk double-buffer. One file is for reading, the other is for
+    writing, and a facility for swapping the two roles is provided.
+    """
+    def __init__( self, path_base, do_persist = True ):
+        self.paths = map( path, [ path_base + '.0', path_base + '.1' ] )
+        self.do_persist = do_persist
+        self.switch_status = path( path_base + '.switched' )
+        if not do_persist or not self.switch_status.exists():
+            self.w, self.r = 0, 1 # default
+        else:
+            self.w, self.r = 1, 0
+        self.reload_files()
+    def reload_files( self ):
+        self.writer = file( self.paths[ self.w ], 'w' )
+        if not self.paths[ self.r ].exists():
+            self.paths[ self.r ].touch()
+        self.reader = file( self.paths[ self.r ] )
+    def switch( self ):
+        self.close()
+        if self.do_persist:
+            if self.w == 0: self.switch_status.touch()
+            else:           self.switch_status.remove()
+        self.r, self.w = self.w, self.r
+        self.reload_files()
+    def write( self, x ):
+        self.writer.write( x )
+    def read( self, len = 8192 ):
+        return self.reader.read( len )
+    def close( self ):
+        self.reader.close()
+        self.writer.close()
+
+def versioned_guard(path, fresh_version):
+    """
+    Maintain a version object.  This is useful for working with versioned
+    caches.
+
+    @param path: The path to the file containing the cached version object.
+    @type path: str
+
+    @param fresh_version: The actual latest version that the cached version
+    should be compared against.
+    @type fresh_version: object (any type that can be compared)
+
+    @return: True iff the cached version is obsolete (less than the fresh
+    version or doesn't exist).
+    @rtype: bool
+    """
+    cache_version = None
+    try:
+        with file( path ) as f: cache_version = load(f)
+    except IOError, (errno, errstr):
+        if errno != 2: raise
+    if cache_version is None or fresh_version > cache_version:
+        with file( path, 'w' ) as f: dump(fresh_version, f)
+        return True
+    else:
+        return False
+
+def versioned_cache(version_path, fresh_version, cache_path, cache_func):
+    """
+    If fresh_version is newer than the version in version_path, then invoke
+    cache_func and cache the result in cache_path (using pickle).
+
+    Note the design flaw with L{versioned_guard}: the updated version value is
+    stored immediately, rather than after updating the cache.
+
+    @param version_path: The path to the file version.
+    @type version_path: str
+
+    @param fresh_version: The actual, up-to-date version value.
+    @type fresh_version: object (any type that can be compared)
+
+    @param cache_path: The path to the cached data.
+    @type cache_path: str
+
+    @param cache_func: The function that produces the fresh data to be cached.
+    @type cache_func: function (no arguments)
+    """
+    if versioned_guard( version_path, fresh_version ):
+        # cache obsolete, force-fetch new data
+        result = cache_func()
+        with file(cache_path, 'w') as f: dump(result, f)
+        return result
+    else:
+        # cache up-to-date (should be available since dlcs-timestamp exists!)
+        with file(cache_path) as f: return load(f)
+
+def read_file(path):
+    f = file(path)
+    try: return f.read()
+    finally: f.close()
+
+def write_file(path, contents):
+    f = file(path,'w')
+    try: f.write(contents)
+    finally: f.close()
+
+def write_or_rm(p, contents):
+    'Write the file or remove it if contents is empty.'
+    p = path(p)
+    if contents.strip(): write_file(p, contents)
+    elif p.isfile(): p.remove()
+
+def is_nonempty_file(path):
+    return path.isfile() and read_file(path).strip() != ''


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.