Initial commit.

[chopwood] / cmdutil.py

### -*-python-*-
###
### Utilities for the various commands
###
### (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 dbmaint as D
import format as F
import operation as OP
import output as O
import service as S
import util as U

def check_user(user, must_exist_p = True):
  """
  Check the existence state of the USER.

  If MUST_EXIST_P is true (the default), ensure that USER exists; otherwise,
  ensure that it does not.  Raise an appropriate `ExpectedError' if the check
  fails.
  """

  D.DB.execute("SELECT 1 FROM users WHERE user = $user", user = user)
  existsp = D.DB.fetchone() is not None

  if must_exist_p and not existsp:
    raise U.ExpectedError, (400, "Unknown user `%s'" % user)
  elif not must_exist_p and existsp:
    raise U.ExpectedError, (400, "User `%s' already exists" % user)

def set_user(u):
  """Check that U is a known user, and, if so, store it in `USER'."""
  global USER
  D.opendb()
  check_user(u)
  USER = u

def check_service(service, must_config_p = True, must_records_p = None):
  """
  Check the existence state of the SERVICE.

  If MUST_CONFIG_P is true (the default), ensure that the service is
  configured, i.e., there is an entry in the `SERVICES' dictionary; if false,
  ensure tht it is not configured; if `None', then don't care either way.

  Similarly, if MUST_RECORDS_P is true, ensure that there is at least one
  account defined for the service in the database; if false, ensure that
  there are no accounts; and if `None' (the default), then don't care either
  way.

  Raise an appropriate `ExpectedError' if the check fails.  The return value
  on successful completion is the service object, or `None' if it is not
  configured.
  """

  try: svc = S.SERVICES[service]
  except KeyError: svc = None

  ## Check whether the service is configured.
  if must_config_p is not None:
    if must_config_p and not svc:
      raise U.ExpectedError, (400, "Unknown service `%s'" % service)
    elif not must_config_p and svc:
      raise U.ExpectedError, \
            (400, "Service `%s' is still configured" % service)

  ## Check whether the service has any accounts.
  if must_records_p is not None:
    D.DB.execute("SELECT 1 FROM services WHERE service = $service",
                 service = service)
    recordsp = D.DB.fetchone() is not None
    if must_records_p and not recordsp:
      raise U.ExpectedError, (400, "Service `%s' is unused" % service)
    elif not must_records_p and recordsp:
      raise U.ExpectedError, \
          (400, "Service `%s' is already in use" % service)

  ## Done.
  return svc

def resolve_accounts(user, services):
  """
  Resolve multiple accounts, returning a list of `acct' objects.
  """

  ## Make sure the user actually exists.
  check_user(user)

  ## Work through the list of services.
  accts = []
  for service in services:
    svc = check_service(service)

    ## Find the account record from the services table.
    with D.DB:
      D.DB.execute("""SELECT alias FROM services
                      WHERE user = $user AND service = $service""",
                   user = user, service = service)
      row = D.DB.fetchone()
      if row is None:
        raise U.ExpectedError, \
            (400, "No `%s' account for `%s'" % (service, user))

    ## Pick the result apart and extend the list.
    alias, = row
    if alias is None: alias = user
    accts.append(OP.acct(svc, alias))

  ## Done.
  return accts

def resolve_account(service, user):
  """
  Resolve a pair of SERVICE and USER names, and return a pair (SVC, ALIAS) of
  the (local or remote) service object, and the USER's alias for the service.
  Raise an appropriate `ExpectedError' if the service or user don't exist.
  """

  acct, = resolve_accounts(user, [service])
  return acct.svc, acct.user

def matching_items(want, tab, cond = [], tail = '', **kw):
  """
  Generate the matching items from a query constructed dynamically.

  Usually you wouldn't go through this palaver for a static query, but his
  function helps with building queries in pieces.  WANT should be a list of
  column names we should output, appropriately qualified if there are
  multiple tables; TAB should be a list of table names, in the form `FOO as
  F' if aliases are wanted; COND should be a list of SQL expressions all of
  which the generated records must satisfy; TAIL should be a string
  containing any other bits of the query wanted; and the remaining keyword
  arguments are made available to the query conditions via `$KEY'
  placeholders.
  """
  for row in D.DB.execute("SELECT %s FROM %s %s %s" %
                          (', '.join(want), ', '.join(tab),
                           cond and "WHERE " + " AND ".join(cond) or "",
                           tail),
                          **kw):
    yield row

class acctinfo (U.struct):
  """Information about an account, returned by `list_accounts'."""
  __slots__ = ['service', 'friendly', 'alias']

def list_accounts(user):
  """
  Return a list of `acctinfo' objets representing the USER's accounts.
  """
  def friendly_name(service):
    try: return S.SERVICES[service].friendly
    except KeyError: return "<unknown service `%s'>" % service
  return [acctinfo(service, friendly_name(service), alias)
          for service, alias in
          matching_items(['service', 'alias'], ['services'],
                         ['user = $user'], "ORDER BY service",
                         user = user)]

class userinfo (U.struct):
  """Information about a user, returned by `list_uesrs'."""
  __slots__ = ['user', 'email']

def list_users(service = None, pat = None):
  """
  Return a list of `userinfo' objects for the matching users.

  If SERVICE is given, return only users who have accounts for that service.
  If PAT is given, it should be a glob-like pattern; return only users whose
  names match it.
  """

  ## Basic pieces of the query.
  kw = {}
  tab = ['users AS u']
  cond = []

  ## Restrict according to the services.
  if service is not None:
    tab.append('services AS s')
    cond.append('u.user = s.user AND s.service = $service')
    kw['service'] = service

  ## Restrict according to the user name.
  if pat is not None:
    cond.append("u.user LIKE $pat ESCAPE '\\'")
    kw['pat'] = U.globtolike(pat)

  ## Build and return the list.
  return [userinfo(user, email) for user, email in
          matching_items(['u.user', 'u.email'],
                         tab, cond, "ORDER BY u.user", **kw)]

class column (U.struct):
  """Description of a column, to be passed to `format_list'."""
  __slots__ = ['head', 'format', 'width']
  DEFAULTS = dict(width = 0)

def format_list(items, columns):
  """
  Present the ITEMS in tabular form on the current output.

  The COLUMNS are a list of `column' objects, describing the columns in the
  table to be written: the `head' slot gives a string to be printed in the
  first line; the `format' slot gives a `format' string to produce the text
  for a given item, provided as the positional argument, in that column; and
  `width' gives the minimum width for the column, in characters.  Note that
  the column may be wider than requested.
  """

  ## First pass: format the items and work out the actual column widths.
  n = len(columns)
  wd = [c.width for c in columns]
  cells = []
  def addrow(row):
    for i in xrange(n):
      if len(row[i]) > wd[i]:
        wd[i] = len(row[i])
    cells.append(row)
  addrow([c.head for c in columns])
  for i in items:
    addrow([F.format(None, c.format, i) for c in columns])

  ## Second pass: print the table.  We've already formatted the items, but we
  ## need to set the column widths, so do that by compiling a formatter.
  ## Note that the width of the last column is irrelevant: in this way, we
  ## suppress trailing spaces.
  fmt = F.compile(F.format(None, "~{~#[~;~~~*A~:;~~~DA~]~^  ~}~~%", wd))
  for row in cells:
    F.format(O.OUT, fmt, *row)

def edit_records(table, cond, edits, **kw):
  """
  Edit some database records.

  This function modifies one or more records in TABLE (which, I suppose,
  could actually be a join of multiple tables), specifically the ones which
  match COND (with $TAG placeholders filled in from the keyword arguments),
  according to EDITS.

  EDITS is a list of tuples of the form (FIELD, VALUE, NULLP): FIELD names a
  field to be modified: VALUE, if it is not `None', is the new value to set;
  if NULLP is true, then set the field to SQL `NULL'.  If both actions are
  requested then raise an exception.

  Exceptions are also raised if there are no operations to perform, or if
  there are no records which match the condition.
  """

  ## We'll build up the query string in pieces.
  d = dict(kw)
  ops = []
  q = 0

  ## Work through the edits, building up the pieces of the query.
  for field, value, nullp in edits:
    if value is not None and nullp:
      raise U.ExpectedError, (400, "Can't set and clear `%s' field" % field)
    elif nullp:
      ops.append('%s = NULL' % field)
    elif value is not None:
      tag = 't%d' % q
      q += 1
      ops.append('%s = $%s' % (field, tag))
      d[tag] = value

  ## If there are no changes to be made, then we're done.
  if not ops: raise U.ExpectedError, (400, 'Nothing to do')

  ## See whether the query actually matches any records at all.
  D.DB.execute("SELECT 1 FROM %s WHERE %s" % (table, cond), **d)
  if D.DB.fetchone() is None:
    raise U.ExpectedError, (400, 'No records to edit')

  ## Go ahead and make the changes.
  D.DB.execute("UPDATE %s SET %s WHERE %s" % (table, ', '.join(ops), cond),
               **d)

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