#!/usr/bin/python2.5

#

# Copyright 2009 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.

from __future__ import with_statement

"""Google Summer of Code Melange release script.

This script provides automation for the various tasks involved in

pushing a new release of Melange to the official Google Summer of Code

app engine instance.

It does not provide a turnkey autopilot solution. Notably, each stage

of the release process must be started by a human operator, and some

commands will request confirmation or extra details before

proceeding. It is not a replacement for a cautious human

operator.

Note that this script requires:

 - Python 2.5 or better (for various language features)

 - Subversion 1.5.0 or better (for working copy depth control, which

     cuts down checkout/update times by several orders of

     magnitude).

"""

__authors__ = [

    # alphabetical order by last name, please

    '"David Anderson" <dave@natulte.net>',

    ]

import functools

import os

import re

import subprocess

import sys

import error

import log

import util

# Default repository URLs for Melange and the Google release

# repository.

MELANGE_REPOS = 'http://soc.googlecode.com/svn'

GOOGLE_SOC_REPOS = 'https://soc-google.googlecode.com/svn'

# Regular expression matching an apparently well formed Melange

# release number.

MELANGE_RELEASE_RE = re.compile(r'\d-\d-\d{8}p\d+')

class Error(error.Error):

  pass

class AbortedByUser(Error):

  """The operation was aborted by the user."""

class ObstructionError(Error):

  """An operation was obstructed by existing data."""

class ExpectationFailed(Error):

  """An unexpected state was encountered by an automated step."""

class FileAccessError(Error):

  """An error occured while accessing a file."""

def getString(prompt):

  """Prompt for and return a string."""

  prompt += ' '

  log.stdout.write(prompt)

  log.stdout.flush()

  response = sys.stdin.readline()

  log.terminal_echo(prompt + response.strip())

  if not response:

    raise AbortedByUser('Aborted by ctrl+D')

  return response.strip()

def confirm(prompt, default=False):

  """Ask a yes/no question and return the answer.

  Will reprompt the user until one of "yes", "no", "y" or "n" is

  entered. The input is case insensitive.

  Args:

    prompt: The question to ask the user.

    default: The answer to return if the user just hits enter.

  Returns:

    True if the user answered affirmatively, False otherwise.

  """

  if default:

    question = prompt + ' [Yn]'

  else:

    question = prompt + ' [yN]'

  while True:

    answer = getString(question)

    if not answer:

      return default

    elif answer in ('y', 'yes'):

      return True

    elif answer in ('n', 'no'):

      return False

    else:

      log.error('Please answer yes or no.')

def getNumber(prompt):

  """Prompt for and return a number.

  Will reprompt the user until a number is entered.

  """

  while True:

    value_str = getString(prompt)

    try:

      return int(value_str)

    except ValueError:

      log.error('Please enter a number. You entered "%s".' % value_str)

def getChoice(intro, prompt, choices, done=None, suggest=None):

  """Prompt for and return a choice from a menu.

  Will reprompt the user until a valid menu entry is chosen.

  Args:

    intro: Text to print verbatim before the choice menu.

    prompt: The prompt to print right before accepting input.

    choices: The list of string choices to display.

    done: If not None, the list of indices of previously

          selected/completed choices.

    suggest: If not None, the index of the choice to highlight as

             the suggested choice.

  Returns:

    The index in the choices list of the selection the user made.

  """

  done = set(done or [])

  while True:

    print intro

    print

    for i, entry in enumerate(choices):

      done_text = ' (done)' if i in done else ''

      indent = '--> ' if i == suggest else '    '

      print '%s%2d. %s%s' % (indent, i+1, entry, done_text)

    print

    choice = getNumber(prompt)

    if 0 < choice <= len(choices):

      return choice-1

    log.error('%d is not a valid choice between %d and %d' %

              (choice, 1, len(choices)))

    print

def fileToLines(path):

  """Read a file and return it as a list of lines."""

  try:

    with file(path) as f:

      return f.read().split('\n')

  except (IOError, OSError), e:

    raise FileAccessError(str(e))

def linesToFile(path, lines):

  """Write a list of lines to a file."""

  try:

    with file(path, 'w') as f:

      f.write('\n'.join(lines))

  except (IOError, OSError), e:

    raise FileAccessError(str(e))

class Subversion(util.Paths):

  """Wrapper for operations on a Subversion working copy.

  An instance of this class is bound to a specific working copy

  directory, and provides an API to perform various Subversion

  operations on this working copy.

  Some methods take a 'depth' argument. Depth in Subversion is a

  feature that allows the creation of arbitrarily shallow or deep

  working copies on a per-directory basis. Possible values are

  'none' (no files or directories), 'files' (only files in .),

  'immediates' (files and directories in ., directories checked out

  at depth 'none') or 'infinity' (a normal working copy with

  everything).

  This class also provides a few static functions that run the 'svn'

  tool against remote repositories to gather information or retrieve

  data.

  Note that this wrapper also doubles as a Paths object, offering an

  easy way to get or check the existence of paths in the working

  copy.

  """

  def __init__(self, wc_dir):

    util.Paths.__init__(self, wc_dir)

  def _unknownAndMissing(self, path):

    """Returns lists of unknown and missing files in the working copy.

    Args:

      path: The working copy path to scan.

    Returns:

      Two lists. The first is a list of all unknown paths

      (subversion has no knowledge of them), the second is a list

      of missing paths (subversion knows about them, but can't

      find them). Paths in either list are relative to the input

      path.

    """

    assert self.exists()

    unknown = []

    missing = []

    for line in self.status(path):

      if not line.strip():

        continue

      if line[0] == '?':

        unknown.append(line[7:])

      elif line[0] == '!':

        missing.append(line[7:])

    return unknown, missing

  def checkout(self, url, depth='infinity'):

    """Check out a working copy from the given URL.

    Args:

      url: The Subversion repository URL to check out.

      depth: The depth of the working copy root.

    """

    assert not self.exists()

    util.run(['svn', 'checkout', '--depth=' + depth, url, self.path()])

  def update(self, path='', depth=None):

    """Update a working copy path, optionally changing depth.

    Args:

      path: The working copy path to update.

      depth: If set, change the depth of the path before updating.

    """

    assert self.exists()

    if depth is None:

      util.run(['svn', 'update', self.path(path)])

    else:

      util.run(['svn', 'update', '--set-depth=' + depth, self.path(path)])

  def revert(self, path=''):

    """Recursively revert a working copy path.

    Note that this command is more zealous than the 'svn revert'

    command, as it will also delete any files which subversion

    does not know about.

    """

    util.run(['svn', 'revert', '-R', self.path(path)])

    unknown, missing = self._unknownAndMissing(path)

    unknown = [os.path.join(self.path(path), p) for p in unknown]

    if unknown:

      # rm -rf makes me uneasy. Verify that all paths to be deleted

      # are within the release working copy.

      for p in unknown:

        assert p.startswith(self.path())

      util.run(['rm', '-rf', '--'] + unknown)

  def ls(self, dir=''):

    """List the contents of a working copy directory.

    Note that this returns the contents of the directory as seen

    by the server, not constrained by the depth settings of the

    local path.

    """

    assert self.exists()

    return util.run(['svn', 'ls', self.path(dir)], capture=True)

  def copy(self, src, dest):

    """Copy a working copy path.

    The copy is only scheduled for commit, not committed.

    Args:

      src: The source working copy path.

      dst: The destination working copy path.

    """

    assert self.exists()

    util.run(['svn', 'cp', self.path(src), self.path(dest)])

  def propget(self, prop_name, path):

    """Get the value of a property on a working copy path.

    Args:

      prop_name: The property name, eg. 'svn:externals'.

      path: The working copy path on which the property is set.

    """

    assert self.exists()

    return util.run(['svn', 'propget', prop_name, self.path(path)],

            capture=True)

  def propset(self, prop_name, prop_value, path):

    """Set the value of a property on a working copy path.

    The property change is only scheduled for commit, not committed.

    Args:

      prop_name: The property name, eg. 'svn:externals'.

      prop_value: The value that should be set.

      path: The working copy path on which to set the property.

    """

    assert self.exists()

    util.run(['svn', 'propset', prop_name, prop_value, self.path(path)])

  def add(self, paths):

    """Schedule working copy paths for addition.

    The paths are only scheduled for addition, not committed.

    Args:

      paths: The list of working copy paths to add.

    """

    assert self.exists()

    paths = [self.path(p) for p in paths]

    util.run(['svn', 'add'] + paths)

  def remove(self, paths):

    """Schedule working copy paths for deletion.

    The paths are only scheduled for deletion, not committed.

    Args:

      paths: The list of working copy paths to delete.

    """

    assert self.exists()

    paths = [self.path(p) for p in paths]

    util.run(['svn', 'rm'] + paths)

  def status(self, path=''):

    """Return the status of a working copy path.

    The status returned is the verbatim output of 'svn status' on

    the path.

    Args:

      path: The path to examine.

    """

    assert self.exists()

    return util.run(['svn', 'status', self.path(path)], capture=True)

  def addRemove(self, path=''):

    """Perform an "addremove" operation a working copy path.

    An "addremove" runs 'svn status' and schedules all the unknown

    paths (listed as '?') for addition, and all the missing paths

    (listed as '!') for deletion. Its main use is to synchronize

    working copy state after applying a patch in unified diff

    format.

    Args:

      path: The path under which unknown/missing files should be

        added/removed.

    """

    assert self.exists()

    unknown, missing = self._unknownAndMissing(path)

    if unknown:

      self.add(unknown)

    if missing:

      self.remove(missing)

  def commit(self, message, path=''):

    """Commit scheduled changes to the source repository.

    Args:

      message: The commit message to use.

      path: The path to commit.

    """

    assert self.exists()

    util.run(['svn', 'commit', '-m', message, self.path(path)])

  @staticmethod

  def export(url, revision, dest_path):

    """Export the contents of a repository to a local path.

    Note that while the underlying 'svn export' only requires a

    URL, we require that both a URL and a revision be specified,

    to fully qualify the data to export.

    Args:

      url: The repository URL to export.

      revision: The revision to export.

      dest_path: The destination directory for the export. Note

           that this is an absolute path, NOT a working copy

           relative path.

    """

    assert os.path.isabs(dest_path)

    if os.path.exists(dest_path):

      raise ObstructionError('Cannot export to obstructed path %s' %

                   dest_path)

    util.run(['svn', 'export', '-r', str(revision), url, dest_path])

  @staticmethod

  def find_tag_rev(url):

    """Return the revision at which a remote tag was created.

    Since tags are immutable by convention, usually the HEAD of a

    tag should be the tag creation revision. However, mistakes can

    happen, so this function will walk the history of the given

    tag URL, stopping on the first revision that was created by

    copy.

    This detection is not foolproof. For example: it will be

    fooled by a tag that was created, deleted, and recreated by

    copy at a different revision. It is not clear what the desired

    behavior in these edge cases are, and no attempt is made to

    handle them. You should request user confirmation before using

    the result of this function.

    Args:

      url: The repository URL of the tag to examine.

    """

    try:

      output = util.run(['svn', 'log', '-q', '--stop-on-copy', url],

                capture=True)

    except util.SubprocessFailed:

      raise ExpectationFailed('No tag at URL ' + url)

    first_rev_line = output[-2]

    first_rev = int(first_rev_line.split()[0][1:])

    return first_rev

  @staticmethod

  def diff(url, revision):

    """Retrieve a revision from a remote repository as a unified diff.

    Args:

      url: The repository URL on which to perform the diff.

      revision: The revision to extract at the given url.

    Returns:

      A string containing the changes extracted from the remote

      repository, in unified diff format suitable for application

      using 'patch'.

    """

    try:

      return util.run(['svn', 'diff', '-c', str(revision), url],

              capture=True, split_capture=False)

    except util.SubprocessFailed:

      raise ExpectationFailed('Could not get diff for r%d '

                  'from remote repository' % revision)

#

# Decorators for use in ReleaseEnvironment.

#

def pristine_wc(f):

  """A decorator that cleans up the release repository."""

  @functools.wraps(f)

  def revert_wc(self, *args, **kwargs):

    self.wc.revert()

    return f(self, *args, **kwargs)

  return revert_wc

def requires_branch(f):

  """A decorator that checks that a release branch is active."""

  @functools.wraps(f)

  def check_branch(self, *args, **kwargs):

    if self.branch is None:

      raise ExpectationFailed(

        'This operation requires an active release branch')

    return f(self, *args, **kwargs)

  return check_branch