service.py: Yet more unqualified names needing qualification.

[chopwood] / output.py

### -*-python-*-
###
### Output machinery
###
### (c) 2013 Mark Wooding
###

###----- Licensing notice ---------------------------------------------------
###
### This file is part of Chopwood: a password-changing service.
###
### Chopwood is free software; you can redistribute it and/or modify
### it under the terms of the GNU Affero General Public License as
### published by the Free Software Foundation; either version 3 of the
### License, or (at your option) any later version.
###
### Chopwood is distributed in the hope that it will be useful,
### but WITHOUT ANY WARRANTY; without even the implied warranty of
### MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
### GNU Affero General Public License for more details.
###
### You should have received a copy of the GNU Affero General Public
### License along with Chopwood; if not, see
### <http://www.gnu.org/licenses/>.

from __future__ import with_statement

import contextlib as CTX
from cStringIO import StringIO
import sys as SYS

import util as U

### There are a number of interesting things to do with output.
###
### The remote-service interface needs to prefix its output lines with `INFO'
### tokens so that they get parsed properly.
###
### The CGI interface needs to prefix its output with at least a
### `Content-Type' header.

###--------------------------------------------------------------------------
### Utilities.

def http_headers(**kw):
  """
  Generate mostly-formatted HTTP headers.

  KW is a dictionary mapping HTTP header names to values.  Each name is
  converted to external form by changing underscores `_' to hyphens `-', and
  capitalizing each constituent word.  The values are converted to strings.
  If a value is a list, a header is produced for each element.  Subsequent
  lines in values containing internal line breaks have a tab character
  prepended.
  """
  def hack_header(k, v):
    return '%s: %s' % ('-'.join(i.title() for i in k.split('_')),
                       str(v).replace('\n', '\n\t'))
  for k, v in kw.iteritems():
    if isinstance(v, list):
      for i in v: yield hack_header(k, i)
    else:
      yield hack_header(k, v)

###--------------------------------------------------------------------------
### Protocol.

class BasicOutputDriver (object):
  """
  A base class for output drivers, providing trivial implementations of most
  of the protocol.

  The main missing piece is the `_write' method, which should write its
  argument to the output with as little ceremony as possible.  Any fancy
  formatting should be applied by overriding `write'.
  """

  def __init__(me):
    """Trivial constructor."""
    pass

  def writeln(me, msg):
    """Write MSG, as a complete line."""
    me.write(str(msg) + '\n')

  def write(me, msg):
    """Write MSG to the output, with any necessary decoration."""
    me._write(str(msg))

  def close(me):
    """Wrap up when everything that needs saying has been said."""
    pass

  def header(me, **kw):
    """Emit HTTP-style headers in a distinctive way."""
    for h in http_headers(**kw):
      PRINT('[%s]' % h)

class BasicLineOutputDriver (BasicOutputDriver):
  """
  Mixin class for line-oriented output formatting.

  We override `write' to buffer partial lines; complete lines are passed to
  `_writeln' to be written, presumably through the low-level `_write' method.
  """

  def __init__(me, *args, **kw):
    """Contructor."""
    super(BasicLineOutputDriver, me).__init__(*args, **kw)
    me._buf = None

  def _flush(me):
    """Write any incomplete line accumulated so far, and clear the buffer."""
    if me._buf:
      me._writeln(me._buf.getvalue())
      me._buf = None

  def write(me, msg):
    """Write MSG, sending any complete lines to the `_writeln' method."""

    if '\n' not in msg:
      ## If there's not a complete line here then we just accumulate the
      ## message into our buffer.

      if not me._buf: me._buf = StringIO()
      me._buf.write(msg)

    else:
      ## There's at least one complete line here.  We take the final
      ## incomplete line off the end.

      lines = msg.split('\n')
      tail = lines.pop()

      ## If there's a partial line already buffered then add whatever new
      ## stuff we have and flush it out.
      if me._buf:
        me._buf.write(lines[0])
        me._flush()

      ## Write out any other complete lines.
      for line in lines:
        me._writeln(line)

      ## If there's a proper partial line, then start a new buffer.
      if tail:
        me._buf = StringIO()
        me._buf.write(tail)

  def close(me):
    """If there's any partial line buffered, flush it out."""
    me._flush()

###--------------------------------------------------------------------------
### Implementations.

class FileOutput (BasicOutputDriver):
  """Output driver for writing stuff to a file."""
  def __init__(me, file = SYS.stdout, *args, **kw):
    """Constructor: send output to FILE (default is stdout)."""
    super(FileOutput, me).__init__(*args, **kw)
    me._file = file
  def _write(me, text):
    """Output protocol: write TEXT to the ouptut file."""
    me._file.write(text)

class RemoteOutput (FileOutput, BasicLineOutputDriver):
  """Output driver for decorating lines with `INFO' tags."""
  def _writeln(me, line):
    """Line output protocol: write a complete line with an `INFO' tag."""
    me._write('INFO %s\n' % line)

###--------------------------------------------------------------------------
### Context.

class DelegatingOutput (BasicOutputDriver):
  """Fake output driver which delegates to some other driver."""

  def __init__(me, default = None):
    """Constructor: send output to DEFAULT."""
    me._fluid = U.Fluid(target = default)

  @CTX.contextmanager
  def redirect_to(me, target):
    """Temporarily redirect output to TARGET, closing it when finished."""
    try:
      with me._fluid.bind(target = target):
        yield
    finally:
      target.close()

  ## Delegating methods.
  def write(me, msg): me._fluid.target.write(msg)
  def writeln(me, msg): me._fluid.target.writeln(msg)
  def close(me): me._fluid.target.close()
  def header(me, **kw): me._fluid.target.header(**kw)

  ## Delegating properties.
  @property
  def headerp(me): return me._fluid.target.headerp

## The selected output driver.  Set this with `output_to'.
OUT = DelegatingOutput()

def PRINT(msg = ''):
  """Write the MSG as a line to the current output."""
  OUT.writeln(msg)

###----- That's all, folks --------------------------------------------------