#!/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.

"""Helper functions that wrap the pysvn Python svn bindings.

ls(): returns list of selected directory entries from an SVN repository
lsDirs(): wrapper around ls() that only returns node_kind.dir entries
lsFiles(): wrapper around ls() that only returns node_kind.files entries
exists(): returns True if repo_path exists in the svn repository

PYSVN_ALL_NODE_KINDS: all directory entry node_kinds supported by pysvn
PYSVN_FILE_DIR_NODE_KINDS: actual file and directory node_kinds

This module requires that the pysvn module be installed.
"""

__authors__ = [
  # alphabetical order by last name, please
  '"Todd Larsen" <tlarsen@google.com>',
]


import os
import pysvn

from trunk.scripts import settings


#: all of the directory entry node_kinds supported py pysvn
PYSVN_ALL_NODE_KINDS = set([pysvn.node_kind.none, pysvn.node_kind.dir,
                            pysvn.node_kind.file, pysvn.node_kind.unknown])

#: actual file and directory node_kinds (includes dir and file, but excludes
#: the "non-file" none and unknown)
PYSVN_FILE_DIR_NODE_KINDS = set([pysvn.node_kind.dir, pysvn.node_kind.file])


# pysvn Client object initialized lazily the first time getPySvnClient()
# is called.
_client = None


def getPySvnClient():
  """Returns the module-global pysvn Client object (creating one if needed).

  Lazily initializes a global pysvn Client object, returning the same one
  once it exists.
  """
  global _client

  if not _client:
    _client = pysvn.Client()

  return _client


def formatDirPath(path):
  """Appends trailing separator to non-empty path if it is missing.

  Args:
    path:  path string, which may be with or without a trailing separator,
      or even empty or None

  Returns:
    path unchanged if path evaluates to False or already ends with a trailing
    separator; otherwise, a / separator is appended
  """
  if path and not path.endswith('/'):
    path = path + '/'
  return path


def formatDirPaths(*args):
  """Apply formatDirPath() to all supplied arguments, returning them in order.
  """
  return tuple([formatDirPath(arg) for arg in args])


def getCanonicalSvnPath(path):
  """Returns the supplied svn repo path *without* the trailing / character.

  Some pysvn methods raise exceptions if svn directory URLs end with a
  trailing / ("non-canonical form") and some do not.  Go figure...
  """
  if path and path.endswith('/'):
    path = path[:-1]
  return path


def useLocalOsSep(path):
  """Return path with all / characters replaced with os.sep, to be OS-agnostic.

  Args:
    path: an SVN path (either working copy path or relative path, but not a
      full repository URL) that uses the canonical / separators
  """
  return path.replace('/', os.sep)


def getExpandedWorkingCopyPath(path, wc_root=None):
  """Returns expanded, local, native filesystem working copy path.

  Args:
    path: path to expand and convert to local filesystem directory separators
    wc_root: if present, prepended to path first
  """
  path = useLocalOsSep(path)

  if wc_root:
    # prepend (Windows-compatible) working copy root if one was supplied
    path = os.path.join(useLocalOsSep(wc_root), path)

  path = settings.getExpandedPath(path)

  if not path.endswith(os.sep):
    path = path + os.sep

  return path


def encodeRevision(rev):
  """Encode supplied revision into a pysvn.Revision instance.

  This function is currently very simplistic and does not produce all possible
  types of pysvn.Revision object.  See below for current limitations.

  Args:
    rev: integer revision number or None

  Returns:
    HEAD pysvn.Revision object if rev is None,
    otherwise a pysvn.opt_revision_kind.number pysvn.Revision object created
    using the supplied integer revision number
  """
  if rev is None:
    return pysvn.Revision(pysvn.opt_revision_kind.head)

  return pysvn.Revision(pysvn.opt_revision_kind.number, int(rev))


def ls(repo_path, client=None, keep_kinds=PYSVN_FILE_DIR_NODE_KINDS, **kwargs):
  """Returns a list of (possibly recursive) svn repo directory entries.

  Args:
    repo_path: absolute svn repository path URL, including the server and
      directory path within the repo
    client: pysvn Client instance; default is None, which will use the pysvn
      Client created by first call to getPySvnClient() (or create one if
      necessary)
    keep_kinds: types of directory entries to keep in the returned list; a
      collection of pysvn.node_kind objects; default is
      PYSVN_FILE_DIR_NODE_KINDS
    **kwargs: keyword arguments passed on to Client.list(), including:
      recurse: indicates if return results should include entries from
        subdirectories of repo_path as well; default is False

  Returns:
    list of (Unicode, coming from pysvn) strings representing the entries
    of types indicated by keep_kinds; strings are altered to match the
    output of the actual 'svn ls' command: repo_path prefix is removed,
    directories end with the / separator.
  """
  if not client:
    client = getPySvnClient()

  raw_entries = client.list(repo_path, **kwargs)
  entries = []

  # Find shortest repos_path that is a 'dir' entry; will be prefix of all
  # other entries, since Client.list() always returns repo_path as one of
  # the entries.  It is easier and more reliable to do this search than to
  # try to manipulate repo_path into the prefix (since the user could supply
  # any number of valid, but different, formats).
  shortest_path = raw_entries[0][0].repos_path

  for svn_list, _ in raw_entries:
    if svn_list.kind == pysvn.node_kind.dir:
      entry_path = svn_list.repos_path

      if len(entry_path) < len(shortest_path):
        shortest_path = entry_path

  # normalize the path name of entry_prefix to include a trailing separator
  entry_prefix = formatDirPath(shortest_path)

  for svn_list,_ in raw_entries:
    # only include requested node kinds (dir, file, etc.)
    if svn_list.kind not in keep_kinds:
      continue

    entry_path = svn_list.repos_path

    # omit the repo_path directory entry itself (simiilar to omitting '.' as
    # is done by the actual 'svn ls' command)
    if entry_path == shortest_path:
      continue

    # all entry_paths except for the shortest should start with that
    # shortest entry_prefix, so assert that and remove the prefix
    assert entry_path.startswith(entry_prefix)
    entry_path = entry_path[len(entry_prefix):]

    # normalize directory entry_paths to include a trailing separator
    if ((svn_list.kind == pysvn.node_kind.dir)
        and (not entry_path.endswith('/'))):
      entry_path = entry_path + '/'

    entries.append(entry_path)

  return entries


def lsDirs(repo_path, **kwargs):
  """Wrapper around ls() that only returns node_kind.dir entries.
  """
  return ls(repo_path, keep_kinds=(pysvn.node_kind.dir,), **kwargs)


def lsFiles(repo_path, **kwargs):
  """Wrapper around ls() that only returns node_kind.files entries.
  """
  return ls(repo_path, keep_kinds=(pysvn.node_kind.file,), **kwargs)


def exists(repo_path, client=None):
  """Returns True if repo_path exists in the svn repository."""
  if not client:
    client = getPySvnClient()

  try:
    raw_entries = client.list(repo_path)
    return True
  except pysvn._pysvn.ClientError:
    # Client.list() raises an exception if the path is not present in the repo
    return False


def branchItems(src, dest, items, rev=None, client=None):
  """Branch a list of items (files and/or directories).

  Using the supplied pysvn client object, a list of items (expected to be
  present in the src directory) is branched from the absolute svn repo src
  path URL to the relative working client dest directory.

  Args:
    src: absolute svn repository source path URL, including the server and
      directory path within the repo
    dest: relative svn repository destination path in the current working copy
    items: list of relative paths of items in src/ to branch to dest/ (no item
      should begin with the / separator)
    client: pysvn Client instance; default is None, which will use the pysvn
      Client created by first call to getPySvnClient() (or create one if
      necessary)
  """
  if not client:
    client = getPySvnClient()

  src = formatDirPath(src)
  dest = useLocalOsSep(formatDirPath(dest))

  for item in items:
    assert not item.startswith('/')
    src_item = getCanonicalSvnPath(src + item)
    # attempt to be compatible with Windows working copy paths
    item = useLocalOsSep(item)
    client.copy(src_item, dest + item, src_revision=encodeRevision(rev))


def branchDir(src, dest, client=None, rev=None):
  """Branch one directory to another.

  Using the supplied pysvn client object, the absolute svn repo path URL src
  directory is branched to the relative working client dest directory.

  Args:
    src: absolute svn repository source path URL, including the server and
      directory path within the repo
    dest: relative svn repository destination path in the current working copy
    client: pysvn Client instance; default is None, which will use the pysvn
      Client created by first call to getPySvnClient() (or create one if
      necessary)
  """
  if not client:
    client = getPySvnClient()

  src = getCanonicalSvnPath(src)
  dest = useLocalOsSep(formatDirPath(dest))

  client.copy(src, dest, src_revision=encodeRevision(rev))


def exportItems(src, dest, items, rev=None, client=None):
  """Export a list of items (files and/or directories).

  Using the supplied pysvn client object, a list of items (expected to be
  present in the src directory) is exported from the absolute svn repo src
  path URL to the local filesystem directory.

  Args:
    src: absolute svn repository source path URL, including the server and
      directory path within the repo
    dest: local filesystem destination path
    items: list of relative paths of items in src/ to export to dest/ (no item
      should begin with the / separator)
    client: pysvn Client instance; default is None, which will use the pysvn
      Client created by first call to getPySvnClient() (or create one if
      necessary)
  """
  if not client:
    client = getPySvnClient()

  src = formatDirPath(src)
  dest = useLocalOsSep(formatDirPath(dest))

  for item in items:
    assert not item.startswith('/')
    src_item = getCanonicalSvnPath(src + item)
    # attempt to be compatible with Windows local filesystem paths
    dest_item = useLocalOsSep(getCanonicalSvnPath(dest + item))
    client.export(src_item, dest_item, revision=encodeRevision(rev))


def exportDir(src, dest, client=None, rev=None):
  """Export one directory to another.

  Using the supplied pysvn client object, the absolute svn repo path URL src
  directory is exported to the the local filesystem directory.

  Args:
    src: absolute svn repository source path URL, including the server and
      directory path within the repo
    dest: local filesystem destination path
    client: pysvn Client instance; default is None, which will use the pysvn
      Client created by first call to getPySvnClient() (or create one if
      necessary)
  """
  if not client:
    client = getPySvnClient()

  src = getCanonicalSvnPath(src)
  dest = useLocalOsSep(getCanonicalSvnPath(dest))

  client.export(src, dest, revision=encodeRevision(rev))