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

"""Functions used by multiple scripts to form Google App Engine images.

These utility functions are used by multiple scripts for creating and managing

Google App Engine "uploadable image" directories produced by combining a

specific Melange application (for example: trunk/apps/proto, trunk/apps/gsoc,

trunk/apps/ghop, etc.), the SoC framework in trunk/soc, and any /thirdparty/

packages, such as thirdparty/django.

The directory layout expected by Google App Engine is (approximately):

  <app>/

        app.yaml

        index.yaml

        content/     (a static content directory for the Melange application)

        main.py      (a WSGI wrapper for Django-based Google App Engine apps)

        settings.py  (application-specific Django settings)

        urls.py      (application-specific URL handler mappings)

The application itself can have application-specific code and templates, so

there is an additional subdirectory with the same name as the application

(to disambiguate modules in the Melange application with same-named modules

in the SoC framework):

  <app>/

        <app>/

              models/, templates/, views/, etc.

Google App Engine assumes that the root of package paths is <app>/, so all

packages are placed in sub-directories of <app>/, and the SoC framework

is considered a package:

  <app>/

        soc/

            models/, templates/, views/, etc.

For Django template based applications (which Melange applications are),

include the django distribution directory (which is one of the /thirdparty/

packages) and some Django-specific files:

  <app>/

        django/

               core/, db/, dispatch/, etc.

Any other /thirdparty/ packages would be included in the the Google App Engine

"uploadable image" directory similarly to Django above.

A NOTE ABOUT DIRECTORY NAMES RETURNED BY FUNCTIONS IN THIS MODULE

The functions in this module return directory names with a trailing / svn path

separator.  This is done by convention only (svn_helper functions normalize

the path names of directories in this same way).  The trailing separator is

kept to make it easier to combine paths (since the caller can always assume

directories end with the / separator) and to make it easier to distinguish

directories from files in human-readable output.

Some pysvn Client methods accept directories named this way, others raise

exceptions and expect a "canonical" form that does not include the trailing

/ separator.  This does not seem to be documented in the pysvn documentation,

so the trailing separator is removed in svn_helper when necessary.

"""

__authors__ = [

  # alphabetical order by last name, please

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

]

import sys

from trunk.scripts import svn_helper

def getRepoAppPath(repo, app):

  """Returns path to specified Melange app in the supplied svn repository.

  Args:

    repo: SVN repository URL

    app: Melange application name (expected to exist in trunk/apps)

  """

  # see note about directory names ending with / svn path separators in the

  # module __doc__ string

  return svn_helper.formatDirPath('%strunk/apps/%s' % (

      svn_helper.formatDirPath(repo), app))

def getRepoThirdPartyPath(repo):

  """Returns path to third-party packages in the supplied svn repository.

  Args:

    repo: SVN repository URL

  """

  # see note about directory names ending with / svn path separators in the

  # module __doc__ string

  return '%sthirdparty/' % svn_helper.formatDirPath(repo)

def getThirdPartyPackageNames(pkg_path, **svn_kwargs):

  """Returns a list of third-party packages in the supplied URL.

  Args:

    pkg_path: full SVN URL path to the directory containing third-party

      packages, usually the path formed by calling getRepoThirdPartyPath()

    **svn_kwargs: keyword arguments passed through to svn_helper.lsDirs()

      (for "advanced users")

  Returns:

    A list of third-party packages found in pkg_path.  Third-party "packages"

    are all of the directories is the pkg_path  directory (but not individual

    files in pkg_path) that do *not* begin with an underscore (_).  Individual

    files and directories beginning with underscores in the pkg_path directory

    are omitted from the results.

  """

  return [pkg for pkg in svn_helper.lsDirs(pkg_path, **svn_kwargs)

            if not pkg.startswith('_')]

def getRepoFrameworksPath(repo):

  """Returns path to Melange framework packages in the supplied svn repository.

  Args:

    repo: SVN repository URL

  """

  # see note about directory names ending with / svn path separators in the

  # module __doc__ string

  return '%strunk/' % svn_helper.formatDirPath(repo)

def getFrameworksNames():

  """Returns a list of Melange framework packages (currently a constant list).

  """

  # see note about directory names ending with / svn path separators in the

  # module __doc__ string

  return ['soc/']

def formDefaultAppBranchPath(branch, user, src, dest):

  """Returns a relative path to a to-be-created App Image branch.

  Args:

    branch: explicit branch name, if it was specified (or None, '', etc.

      instead, if it was not)

    user: subdirectory of /users/ representing a particular contributor

    src: sub-directory name of the specific Melange application to branch

    dest: alternate destination sub-directory name of the Melange application

      in its new, branched location, if it was specified (or None, '', etc.

      instead, if it was not)

  Returns:

    * branch if it was specified ("non-False"), or

    * users/user/dest/ if dest was specified, or

    * users/user/src/ otherwise

  """

  if not branch:

    if dest:

      branch = 'users/%s%s' % (svn_helper.formatDirPath(user), dest)

    else:

      branch = 'users/%s%s' % (svn_helper.formatDirPath(user), src)

  return svn_helper.formatDirPath(branch)

def verbosePrint(verbose, fmt_str, *fmt_args, **fmt_kwargs):

  """If verbosity level greater than zero, print out formatted string.

  Since app_image.py is a utility module most often used by scripts, many

  of its functions print to stdout.  For cases when printed output may not

  be desired, functions should supply a 'verbose' parameter to disable

  output.  The functions in app_image.py use this function to implement

  that selective printing capability.

  Args:

    verbose: verbosity level integer, any value greater than 0 enables

      output

    fmt_str: required format string

    *fmt_args: if present, positional arguments supplied to fmt_str

    **fmt_kwargs: if *fmt_args is not present, named arguments supplied to

      fmt_str, which is expected to contain named format specifiers, for

      example: '%(foo)s'

  """

  if verbose > 0:

    if not fmt_args:

      fmt_args = fmt_kwargs

    print fmt_str % fmt_args

def branchFromSrcApp(app, repo, dest, verbose=1, **svn_kwargs):

  """Branch one Melange app in /trunk/apps/ to form basis of App Engine image.

  Args:

    app: Melange application name in /trunk/apps/

    repo: svn repository root URL

    dest: working copy destination path of the image branch

    verbose: print status if greater than 0; default is 1

    **svn_kwargs: keyword arguments passed on to svn_helper.branchDir()

  """

  repo_app = getRepoAppPath(repo, app)

  verbosePrint(verbose, 'Branching %s from:\n %s\nto:\n %s\n',

               app, repo_app, dest)

  svn_helper.branchDir(repo_app, dest, **svn_kwargs)

def branchFromThirdParty(repo, dest, verbose=1, **svn_kwargs):

  """Branch all subdirectories in /thirdparty/ into a new App Engine image.

  Subdirectories (except for those with names beginning with underscores) in

  /thirdparty/ represent third-party packages that are to be placed in each

  Google App Engine "image" branch.  Files in the root of /thirdparty/ (that

  is, not in a package) and, as previously mentioned, subdrectories beginning

  with underscores, are *not* branched.

  Args:

    repo: svn repository root URL

    dest: working copy destination path of the image branch

    verbose: print status if greater than 0; default is 1

    **svn_kwargs: keyword arguments passed on to svn_helper.branchItems()

  """

  pkg_dir = getRepoThirdPartyPath(repo)

  packages = getThirdPartyPackageNames(pkg_dir)

  verbosePrint(verbose,

      'Branching third-party packages:\n %s\nfrom:\n %s\ninto:\n %s\n',

      '  '.join(packages), pkg_dir, dest)

  svn_helper.branchItems(pkg_dir, dest, packages, **svn_kwargs)

def branchFromFramework(repo, dest, verbose=1, **svn_kwargs):

  """Branch the SoC framework into a new App Engine image branch.

  The SoC framework current consists of only the contents of /trunk/soc/.

  Args:

    repo: svn repository root URL

    dest: working copy destination path of the image branch

    verbose: print status if greater than 0; default is 1

    **svn_kwargs: keyword arguments passed on to svn_helper.branchItems()

  """

  framework_dir = getRepoFrameworksPath(repo)

  packages = getFrameworksNames()

  verbosePrint(verbose,

      'Branching framework components:\n %s\nfrom:\n %s\ninto:\n %s\n',

      '  '.join(packages), framework_dir, dest)

  svn_helper.branchItems(framework_dir, dest, packages, **svn_kwargs)

def exportFromSrcApp(app, repo, dest, verbose=1, **svn_kwargs):

  """Export one Melange app in /trunk/apps/ to form basis of App Engine image.

  Args:

    app: Melange application name in /trunk/apps/

    repo: svn repository root URL

    dest: local filesystem destination path of the exported image

    verbose: print status if greater than 0; default is 1

    **svn_kwargs: keyword arguments passed on to svn_helper.exportDir()

  """

  repo_app = getRepoAppPath(repo, app)

  verbosePrint(verbose, 'Exporting %s from:\n %s\nto:\n %s\n',

               app, repo_app, dest)

  svn_helper.exportDir(repo_app, dest, **svn_kwargs)

def exportFromThirdParty(repo, dest, verbose=1, **svn_kwargs):

  """Export all subdirectories in /thirdparty/ into a new App Engine image.

  Subdirectories (except for those with names beginning with underscores) in

  /thirdparty/ represent third-party packages that are to be placed in each

  Google App Engine "image".  Files in the root of /thirdparty/ (that is,

  not in a package) and, as previously mentioned, subdirectories beginning

  with underscores, are *not* exported.

  Args:

    repo: svn repository root URL

    dest: local filesystem destination path of the exported image

    verbose: print status if greater than 0; default is 1

    **svn_kwargs: keyword arguments passed on to svn_helper.exportItems()

  """

  pkg_dir = getRepoThirdPartyPath(repo)

  packages = getThirdPartyPackageNames(pkg_dir)

  verbosePrint(verbose,

      'Exporting third-party packages:\n %s\nfrom:\n %s\ninto:\n  %s\n',

      '  '.join(packages), pkg_dir, dest)

  svn_helper.exportItems(pkg_dir, dest, packages, **svn_kwargs)

def exportFromFramework(repo, dest, verbose=1, **svn_kwargs):

  """Export the SoC framework into a new App Engine image.

  The SoC framework current consists of only the contents of /trunk/soc/.

  Args:

    repo: svn repository root URL

    dest: local filesystem destination path of the exported image

    verbose: print status if greater than 0; default is 1

    **svn_kwargs: keyword arguments passed on to svn_helper.exportItems()

  """

  framework_dir = getRepoFrameworksPath(repo)

  packages = getFrameworksNames()

  verbosePrint(verbose,

      'Exporting framework components:\n %s\nfrom:\n %s\ninto:\n %s\n',

      '  '.join(packages), framework_dir, dest)

  svn_helper.exportItems(framework_dir, dest, packages, **svn_kwargs)