+++ /dev/null
-"""Conversion pipeline templates.\r
-\r
-The problem:\r
-------------\r
-\r
-Suppose you have some data that you want to convert to another format,\r
-such as from GIF image format to PPM image format. Maybe the\r
-conversion involves several steps (e.g. piping it through compress or\r
-uuencode). Some of the conversion steps may require that their input\r
-is a disk file, others may be able to read standard input; similar for\r
-their output. The input to the entire conversion may also be read\r
-from a disk file or from an open file, and similar for its output.\r
-\r
-The module lets you construct a pipeline template by sticking one or\r
-more conversion steps together. It will take care of creating and\r
-removing temporary files if they are necessary to hold intermediate\r
-data. You can then use the template to do conversions from many\r
-different sources to many different destinations. The temporary\r
-file names used are different each time the template is used.\r
-\r
-The templates are objects so you can create templates for many\r
-different conversion steps and store them in a dictionary, for\r
-instance.\r
-\r
-\r
-Directions:\r
------------\r
-\r
-To create a template:\r
- t = Template()\r
-\r
-To add a conversion step to a template:\r
- t.append(command, kind)\r
-where kind is a string of two characters: the first is '-' if the\r
-command reads its standard input or 'f' if it requires a file; the\r
-second likewise for the output. The command must be valid /bin/sh\r
-syntax. If input or output files are required, they are passed as\r
-$IN and $OUT; otherwise, it must be possible to use the command in\r
-a pipeline.\r
-\r
-To add a conversion step at the beginning:\r
- t.prepend(command, kind)\r
-\r
-To convert a file to another file using a template:\r
- sts = t.copy(infile, outfile)\r
-If infile or outfile are the empty string, standard input is read or\r
-standard output is written, respectively. The return value is the\r
-exit status of the conversion pipeline.\r
-\r
-To open a file for reading or writing through a conversion pipeline:\r
- fp = t.open(file, mode)\r
-where mode is 'r' to read the file, or 'w' to write it -- just like\r
-for the built-in function open() or for os.popen().\r
-\r
-To create a new template object initialized to a given one:\r
- t2 = t.clone()\r
-\r
-For an example, see the function test() at the end of the file.\r
-""" # '\r
-\r
-\r
-import re\r
-import os\r
-import tempfile\r
-import string\r
-\r
-__all__ = ["Template"]\r
-\r
-# Conversion step kinds\r
-\r
-FILEIN_FILEOUT = 'ff' # Must read & write real files\r
-STDIN_FILEOUT = '-f' # Must write a real file\r
-FILEIN_STDOUT = 'f-' # Must read a real file\r
-STDIN_STDOUT = '--' # Normal pipeline element\r
-SOURCE = '.-' # Must be first, writes stdout\r
-SINK = '-.' # Must be last, reads stdin\r
-\r
-stepkinds = [FILEIN_FILEOUT, STDIN_FILEOUT, FILEIN_STDOUT, STDIN_STDOUT, \\r
- SOURCE, SINK]\r
-\r
-\r
-class Template:\r
- """Class representing a pipeline template."""\r
-\r
- def __init__(self):\r
- """Template() returns a fresh pipeline template."""\r
- self.debugging = 0\r
- self.reset()\r
-\r
- def __repr__(self):\r
- """t.__repr__() implements repr(t)."""\r
- return '<Template instance, steps=%r>' % (self.steps,)\r
-\r
- def reset(self):\r
- """t.reset() restores a pipeline template to its initial state."""\r
- self.steps = []\r
-\r
- def clone(self):\r
- """t.clone() returns a new pipeline template with identical\r
- initial state as the current one."""\r
- t = Template()\r
- t.steps = self.steps[:]\r
- t.debugging = self.debugging\r
- return t\r
-\r
- def debug(self, flag):\r
- """t.debug(flag) turns debugging on or off."""\r
- self.debugging = flag\r
-\r
- def append(self, cmd, kind):\r
- """t.append(cmd, kind) adds a new step at the end."""\r
- if type(cmd) is not type(''):\r
- raise TypeError, \\r
- 'Template.append: cmd must be a string'\r
- if kind not in stepkinds:\r
- raise ValueError, \\r
- 'Template.append: bad kind %r' % (kind,)\r
- if kind == SOURCE:\r
- raise ValueError, \\r
- 'Template.append: SOURCE can only be prepended'\r
- if self.steps and self.steps[-1][1] == SINK:\r
- raise ValueError, \\r
- 'Template.append: already ends with SINK'\r
- if kind[0] == 'f' and not re.search(r'\$IN\b', cmd):\r
- raise ValueError, \\r
- 'Template.append: missing $IN in cmd'\r
- if kind[1] == 'f' and not re.search(r'\$OUT\b', cmd):\r
- raise ValueError, \\r
- 'Template.append: missing $OUT in cmd'\r
- self.steps.append((cmd, kind))\r
-\r
- def prepend(self, cmd, kind):\r
- """t.prepend(cmd, kind) adds a new step at the front."""\r
- if type(cmd) is not type(''):\r
- raise TypeError, \\r
- 'Template.prepend: cmd must be a string'\r
- if kind not in stepkinds:\r
- raise ValueError, \\r
- 'Template.prepend: bad kind %r' % (kind,)\r
- if kind == SINK:\r
- raise ValueError, \\r
- 'Template.prepend: SINK can only be appended'\r
- if self.steps and self.steps[0][1] == SOURCE:\r
- raise ValueError, \\r
- 'Template.prepend: already begins with SOURCE'\r
- if kind[0] == 'f' and not re.search(r'\$IN\b', cmd):\r
- raise ValueError, \\r
- 'Template.prepend: missing $IN in cmd'\r
- if kind[1] == 'f' and not re.search(r'\$OUT\b', cmd):\r
- raise ValueError, \\r
- 'Template.prepend: missing $OUT in cmd'\r
- self.steps.insert(0, (cmd, kind))\r
-\r
- def open(self, file, rw):\r
- """t.open(file, rw) returns a pipe or file object open for\r
- reading or writing; the file is the other end of the pipeline."""\r
- if rw == 'r':\r
- return self.open_r(file)\r
- if rw == 'w':\r
- return self.open_w(file)\r
- raise ValueError, \\r
- 'Template.open: rw must be \'r\' or \'w\', not %r' % (rw,)\r
-\r
- def open_r(self, file):\r
- """t.open_r(file) and t.open_w(file) implement\r
- t.open(file, 'r') and t.open(file, 'w') respectively."""\r
- if not self.steps:\r
- return open(file, 'r')\r
- if self.steps[-1][1] == SINK:\r
- raise ValueError, \\r
- 'Template.open_r: pipeline ends width SINK'\r
- cmd = self.makepipeline(file, '')\r
- return os.popen(cmd, 'r')\r
-\r
- def open_w(self, file):\r
- if not self.steps:\r
- return open(file, 'w')\r
- if self.steps[0][1] == SOURCE:\r
- raise ValueError, \\r
- 'Template.open_w: pipeline begins with SOURCE'\r
- cmd = self.makepipeline('', file)\r
- return os.popen(cmd, 'w')\r
-\r
- def copy(self, infile, outfile):\r
- return os.system(self.makepipeline(infile, outfile))\r
-\r
- def makepipeline(self, infile, outfile):\r
- cmd = makepipeline(infile, self.steps, outfile)\r
- if self.debugging:\r
- print cmd\r
- cmd = 'set -x; ' + cmd\r
- return cmd\r
-\r
-\r
-def makepipeline(infile, steps, outfile):\r
- # Build a list with for each command:\r
- # [input filename or '', command string, kind, output filename or '']\r
-\r
- list = []\r
- for cmd, kind in steps:\r
- list.append(['', cmd, kind, ''])\r
- #\r
- # Make sure there is at least one step\r
- #\r
- if not list:\r
- list.append(['', 'cat', '--', ''])\r
- #\r
- # Take care of the input and output ends\r
- #\r
- [cmd, kind] = list[0][1:3]\r
- if kind[0] == 'f' and not infile:\r
- list.insert(0, ['', 'cat', '--', ''])\r
- list[0][0] = infile\r
- #\r
- [cmd, kind] = list[-1][1:3]\r
- if kind[1] == 'f' and not outfile:\r
- list.append(['', 'cat', '--', ''])\r
- list[-1][-1] = outfile\r
- #\r
- # Invent temporary files to connect stages that need files\r
- #\r
- garbage = []\r
- for i in range(1, len(list)):\r
- lkind = list[i-1][2]\r
- rkind = list[i][2]\r
- if lkind[1] == 'f' or rkind[0] == 'f':\r
- (fd, temp) = tempfile.mkstemp()\r
- os.close(fd)\r
- garbage.append(temp)\r
- list[i-1][-1] = list[i][0] = temp\r
- #\r
- for item in list:\r
- [inf, cmd, kind, outf] = item\r
- if kind[1] == 'f':\r
- cmd = 'OUT=' + quote(outf) + '; ' + cmd\r
- if kind[0] == 'f':\r
- cmd = 'IN=' + quote(inf) + '; ' + cmd\r
- if kind[0] == '-' and inf:\r
- cmd = cmd + ' <' + quote(inf)\r
- if kind[1] == '-' and outf:\r
- cmd = cmd + ' >' + quote(outf)\r
- item[1] = cmd\r
- #\r
- cmdlist = list[0][1]\r
- for item in list[1:]:\r
- [cmd, kind] = item[1:3]\r
- if item[0] == '':\r
- if 'f' in kind:\r
- cmd = '{ ' + cmd + '; }'\r
- cmdlist = cmdlist + ' |\n' + cmd\r
- else:\r
- cmdlist = cmdlist + '\n' + cmd\r
- #\r
- if garbage:\r
- rmcmd = 'rm -f'\r
- for file in garbage:\r
- rmcmd = rmcmd + ' ' + quote(file)\r
- trapcmd = 'trap ' + quote(rmcmd + '; exit') + ' 1 2 3 13 14 15'\r
- cmdlist = trapcmd + '\n' + cmdlist + '\n' + rmcmd\r
- #\r
- return cmdlist\r
-\r
-\r
-# Reliably quote a string as a single argument for /bin/sh\r
-\r
-# Safe unquoted\r
-_safechars = frozenset(string.ascii_letters + string.digits + '@%_-+=:,./')\r
-\r
-def quote(file):\r
- """Return a shell-escaped version of the file string."""\r
- for c in file:\r
- if c not in _safechars:\r
- break\r
- else:\r
- if not file:\r
- return "''"\r
- return file\r
- # use single quotes, and put single quotes into double quotes\r
- # the string $'b is then quoted as '$'"'"'b'\r
- return "'" + file.replace("'", "'\"'\"'") + "'"\r