#!/usr/bin/python2.5

#

# Copyright 2008 the Melange authors.

#

# Licensed under the Apache License, Version 2.0 (the "License");

# you may not use this file except in compliance with the License.

# You may obtain a copy of the License at

#

#   http://www.apache.org/licenses/LICENSE-2.0

#

# Unless required by applicable law or agreed to in writing, software

# distributed under the License is distributed on an "AS IS" BASIS,

# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

# See the License for the specific language governing permissions and

# limitations under the License.

"""Custom optparse OptionParser and functions for reading Python settings files.

Default values for trunk/scripts flags can be specified in valid Python syntax

in the ~/.soc_scripts_settings file.  For example, a default value for the

--user flag can be specified with a variable assignment in the settings file

like:

  user = 'joeuser'

Defaults in the ~/.soc_scripts_settings file can be explicitly overridden by

supplied the actual flag.  For example, supplying:

  --user=someotheruser

would override the default value present in the settings file.

  Option:  class derived from optparse.Option that adds a 'required' parameter

  OptionParser:  class derived from optparse.OptionParser for use with Option

  readPythonSettings():  interprets a valid Python file as a settings file

"""

__authors__ = [

  # alphabetical order by last name, please

  '"Todd Larsen" <tlarsen@google.com>',

]

import os

import optparse

import sys

DEF_SETTINGS_FILE_DIR = "~"

DEF_SETTINGS_FILE_NAME = '.soc_scripts_settings'

class Error(Exception):

  """Base exception class for all exceptions in the settings module."""

  pass

class Option(optparse.Option):

  """Class derived from optparse.Option that adds a 'required' parameter."""

  ATTRS = optparse.Option.ATTRS + ['required']

  def _check_required(self):

    """Insures that 'required' option can accept a value."""

    if self.required and (not self.takes_value()):

      raise optparse.OptionError(

          "'required' parameter set for option that does not take a value",

          self)

  # Make sure _check_required() is called from the constructor!

  CHECK_METHODS = optparse.Option.CHECK_METHODS + [_check_required]

  def process(self, opt, value, values, parser):

    optparse.Option.process(self, opt, value, values, parser)

    parser.option_seen[self] = 1

class OptionParser(optparse.OptionParser):

  """Class derived from optparse.OptionParser for use with Option."""

  def _init_parsing_state(self):

    """Sets up dict to track options seen so far."""

    optparse.OptionParser._init_parsing_state(self)

    self.option_seen = {}

  def error(self, *args):

    """Convert errors reported by optparse.OptionParser to Error exceptions.

    Args:

      *args:  passed through to the Error exception __init__() constructor,

        usually a list of strings

    Raises:

      Error with the supplied *args

    """

    raise Error(*args)

  def check_values(self, values, args):

    """Checks to make sure all required=True options were supplied.

    Args:

      values, args:  passed through unchanged (see Returns:)

    Returns:

      (values, args) unchanged.

    Raises:

      Error if an option was not supplied that had required=True;  exception

      positional arguments are the error message strings.

    """

    errors = []

    for option in self.option_list:

      if (isinstance(option, Option)

          and option.required

          and (not self.option_seen.has_key(option))):

        errors.append(

            'required %s option not supplied'

            ' (and default settings not allowed)' % option)

    if errors:

      self.error(*errors)

    return values, args

def printErrors(errors, exit_code=1):

  """Prints error message strings to sys.stderr and returns an exit code.

  Args:

    errors: error message string or list of error message strings to be printed

      to sys.stderr

    exit_code: exit code to return (so that this function can be used as an

      expression in sys.exit() for example); default is 1

  Returns:

    exit_code

  """

  sys.stderr.write('\nERRORS:\n')

  if (not isinstance(errors, tuple)) and (not isinstance(errors, list)):

    errors = [errors]

  for msg in errors:

    sys.stderr.write('  %s\n' % msg)

  sys.stderr.write('\n')

  return exit_code

def printErrorsAndUsage(errors, parser, exit_code=1):

  """Prints error messages and usage text to sys.stderr and returns exit code.

  Args:

    errors: error message string or list of error message strings to be printed

      to sys.stderr

    parser: OptionParser with a print_help() method

    exit_code: exit code to return (so that this function can be used as an

      expression in sys.exit() for example); default is 1

  Returns:

    exit_code

  """

  exit_code = printErrors(errors, exit_code=exit_code)

  parser.print_help(file=sys.stderr)

  return exit_code

def getExpandedPath(path):

  """Returns an expanded, normalized, absolute path.

  Args:

    path: path (possibly relative, possibly containing environment variables,

      etc.) to be expanded, normalized and made absolute

  Returns:

    absolute path, after expanding any environment variables and "~", then

    removing excess . and .. path elements

  """

  return os.path.abspath(

      os.path.normpath(

          os.path.expanduser(

              os.path.expandvars(path))))

def readPythonSettings(defaults={},  # {} OK since defaults is always copied

                       settings_dir=DEF_SETTINGS_FILE_DIR,

                       settings_file=DEF_SETTINGS_FILE_NAME):

  """Executes a Python-syntax settings file and returns the local variables.

  Args:

    defaults:  dict of default values to use when settings are not present

      in the settings file (or if no settings file is present at all);  this

      dict is *copied* and is not altered at all

    settings_dir:  optional directory containing settings_file

    settings_file:  optional settings file name found in settings_dir

  Returns:

    dict of setting name/value pairs (possibly including some values from the

    defaults parameter).  Since the settings file is full-fledged Python

    source, the values could be any valid Python object.

  Raises:

    Error if some error occurred parsing the present settings file;  exception

    positional arguments are the error message strings.

  """

  # do not let the original defaults be altered

  defaults = defaults.copy()

  # form absolute path to the settings file, expanding any environment

  # variables and "~", then removing excess . and .. path elements

  path = getExpandedPath(os.path.join(settings_dir, settings_file))

  # empty dict to capture the local variables in the settings file

  settings_locals = {}

  try:

    # execute the Python source file and recover the local variables as settings

    execfile(path, {}, settings_locals)

  except IOError:

    # If the settings file is not present, there are no defaults.

    pass

  except Exception, error:

    # Other exceptions usually mean a faulty settings file.

    raise Error(

        'faulty settings file:',

        ('  %s: %s' % (error.__class__.__name__, str(error))),

        ('  %s' % path))

  # overwrite defaults copy with values from the (possibly empty) settings file

  defaults.update(settings_locals)

  return defaults

def readPythonSettingsOrDie(parser=None, **kwargs):

  """Calls readPythonSettings(), calling sys.exit() on any errors.

  Args:

    parser: if supplied, an OptionParser instance used to call print_help()

      to print usage information if errors occur

    **kwargs: see readPythonSettings()

  Returns:

    On success, returns results of readPythonSettings().

  Exits:

    On any error from readPythonSettings(), prints error messages to stderr,

    possibly prints usage information, and calls sys.exit(1).

  """

  try:

    return readPythonSettings(**kwargs)

  except Error, error:

    if parser:

      sys.exit(printErrorsAndUsage(error.args, parser))

    else:

      sys.exit(printErrors(error.args))

def makeOptionParserOrDie(*args, **kwargs):

  """Creates and returns an OptionParser, calling sys.exit() on any errors.

  Args:

    *args, **kwargs: supplied directly to OptionParser constructor

  Returns:

    On success, returns an OptionParser instance.

  Exits:

    On any error, prints error messages to stderr and calls sys.exit(1).

  """

  try:

    return OptionParser(*args, **kwargs)

  except Error, error:

    sys.exit(printErrors(error.args))

def parseOptionsOrDie(parser, args):

  """Parses command-line options, calling sys.exit() on any errors.

  Args:

    parser: an OptionParser instance

    args: list of command-line arguments to supply to parser

  Returns:

    On success, returns (options, args) returned by parser.parse_args(args).

  Exits:

    On any error, prints error messages and usage information to stderr and

    calls sys.exit(1).

  """

  try:

    return parser.parse_args(args)

  except Error, error:

    sys.exit(printErrorsAndUsage(error.args, parser))

def checkCommonSvnOptions(options):

  """Checks a common subset of command-line options.

  Multiple scripts accept a subset of common command-line options.  This

  function does some sanity checks on these flags.  These checks are collected

  here because they were being duplicated in multiple scripts.

  Args:

    options: OptionParser.parse_args() options instance to check

  Returns:

    list of error message strings, or an empty list if no errors

  """

  errors = []

  if not options.repo:

    errors.extend(

        ['--repo must be supplied or have a settings file default'])

  if not options.wc:

    errors.extend(

        ['--wc must be supplied or have a settings file default'])

  if not options.branch:

    if not options.user:

      errors.extend(

          ['at least one of --branch or --user must be supplied'])

  return errors

def checkCommonSvnOptionsOrDie(options, parser):

  """Checks subset of command-line options, calling sys.exit() on any errors.

  Args:

    options: see checkCommonSvnOptions()

    parser: an OptionParser instance used to call print_help() to print

      usage information if errors occur

  Exits:

    On any error messages returned by checkCommonSvnOptions(), prints error

    messages and usage information to stderr and calls sys.exit(1).

  """

  errors = checkCommonSvnOptions(options)

  if errors:

    sys.exit(printErrorsAndUsage(errors, parser))