Metadata-Version: 1.0
Name: rod.recipe.appengine
Version: 1.7.0
Summary: ZC Buildout recipe for setting up a Google App Engine development environment.
Home-page: http://code.google.com/p/rodrecipes
Author: Tobias Rodaebel
Author-email: tobias.rodaebel@googlemail.com
License: LGPL 3
Description: ====================
        rod.recipe.appengine
        ====================
        
        The rod.recipe.appengine is a zc.buildout recipe to build, test and deploy
        projects for the Google App Engine. It makes it easy to use eggs and resolve
        their dependencies automatically.
        
        To be honest, this is a recipe for scrambled eggs. It produces a zip file
        containing all configured external packages in a traditional folder hierarchy.
        
        
        Copyright and license
        =====================
        
        Copyright 2009, 2010, 2011 Tobias Rodaebel
        
        This software is released under the GNU Lesser General Public License,
        Version 3.
        
        
        Credits
        =======
        
        Thanks to Attila Olah who provided a patch which fixes two issues where the
        recipe wasn't able to find the original pkg_resources.py file. He also enabled
        the recipe to be used together with distribute as a replacement for setuptools.
        
        Attila Olah also provided a patch for supporting regular expressions when using
        the exclude option.
        
        Thanks to Tom Lynn for submitting a patch which fixes an issue with symlink on
        platforms other than UNIX.
        
        A brief documentation
        =====================
        
        This recipe takes a number of options:
        
        appengine-lib
        Path to an already installed appengine library
        
        eggs
        List of required eggs
        
        exclude
        A list of basenames and regular expressions to be excluded when setting up
        the application files, e.g. the whole 'tests' directory.
        
        packages
        A list of packages to be included into the zip archive, which will be
        uploaded to the appspot.
        
        patch
        Specifies a patch file for patching the SDK source-tree. This option is
        not allowed if appengine-lib is specified.
        
        patch-options
        List of patch options separated by blanks. (Default=-p1)
        
        server-script
        The name of the script to run the development server.
        
        src
        The directory which contains the project source files.
        
        url
        The url for fetching the google appengine distribution
        
        use_setuptools_pkg_resources
        Flag whether the recipe shall copy setuptool's pkg_resources.py into the
        app directory rather than writing a dummy version. (Default=False)
        
        zip-name
        The name of the zip archive containing all external packages ready
        to deploy.
        
        zip-packages
        Flag whether external packages shall be zipped into a single zip file.
        (Default=True)
        
        
        Tests
        =====
        
        We will define a buildout template used by the recipe:
        
        >>> buildout_template = """
        ... [buildout]
        ... develop = %(dev)s
        ... parts = sample
        ...
        ... [sample]
        ... recipe = rod.recipe.appengine
        ... eggs = foo.bar
        ... packages =
        ...     bazpkg
        ...     tinypkg
        ... server-script = dev_appserver
        ... zip-packages = False
        ... exclude = .*foo/bar/test.*$
        ... url = http://googleappengine.googlecode.com/files/google_appengine_1.5.0.zip
        ... """
        
        We'll start by creating a buildout:
        
        >>> import os.path
        >>> import rod.recipe.appengine.tests as tests
        >>> egg_src = os.path.join(os.path.split(tests.__file__)[0], 'foo.bar')
        >>> baz_pkg = os.path.join(os.path.split(tests.__file__)[0], 'bazpkg')
        >>> tiny_pkg = os.path.join(os.path.split(tests.__file__)[0], 'tinypkg')
        >>> write('buildout.cfg', buildout_template %
        ...       {'dev': egg_src+' '+baz_pkg+' '+tiny_pkg})
        
        Running the buildout gives us:
        
        >>> output = system(buildout)
        >>> if output.endswith("Google App Engine distribution...\n"): True
        ... else: print output
        True
        
        And now we try to run the appserver script:
        
        >>> print system(os.path.join('bin', 'dev_appserver'))
        <BLANKLINE>
        ...
        Invalid arguments
        <BLANKLINE>
        
        There should be a configuration script in bin as well:
        
        >>> print system(os.path.join('bin', 'appcfg'))
        Usage: appcfg [options] <action>
        <BLANKLINE>
        ...
        <BLANKLINE>
        
        Let's see if the 'tests' directory has been excluded:
        
        >>> l = os.listdir(os.sep.join(['parts', 'sample', 'foo', 'bar']))
        >>> assert 'tests' not in l
        
        There should be a baz package within our application directory:
        
        >>> assert 'baz' in os.listdir(os.sep.join(['parts', 'sample']))
        
        Let's define another buildout template used by the recipe:
        
        >>> buildout_template = """
        ... [buildout]
        ... develop = %(dev)s
        ... parts = second_sample
        ...
        ... [second_sample]
        ... recipe = rod.recipe.appengine
        ... eggs = foo.bar
        ... use_setuptools_pkg_resources = True
        ... packages =
        ...     bazpkg
        ...     tinypkg
        ... patch = %(patch)s
        ... patch-options = -p1
        ... zip-packages = False
        ... exclude = tests
        ... url = http://googleappengine.googlecode.com/files/google_appengine_1.5.0.zip
        ... """
        
        We'll start by creating a buildout:
        
        >>> import os.path
        >>> import rod.recipe.appengine.tests as tests
        >>> egg_src = os.path.join(os.path.split(tests.__file__)[0], 'foo.bar')
        >>> baz_pkg = os.path.join(os.path.split(tests.__file__)[0], 'bazpkg')
        >>> tiny_pkg = os.path.join(os.path.split(tests.__file__)[0], 'tinypkg')
        >>> patch = os.path.join(os.path.split(tests.__file__)[0], 'patch.diff')
        >>> write('buildout.cfg', buildout_template %
        ...       {'dev': egg_src+' '+baz_pkg+' '+tiny_pkg, 'patch': patch})
        
        Running the buildout gives us:
        
        >>> output = system(buildout)
        >>> if output.endswith(
        ...     "patching file lib/patched/patched.txt\n"): True
        ... else: print output
        True
        
        And now we try to run the appserver script:
        
        >>> print system(os.path.join('bin', 'second_sample'))
        <BLANKLINE>
        ...
        Invalid arguments
        <BLANKLINE>
        
        Let's have a look if all dependent packages are copied into our application
        directory:
        
        >>> os.path.isfile(os.path.join('parts', 'second_sample', 'tinymodule.py'))
        True
        >>> os.path.isdir(os.path.join('parts', 'second_sample', 'baz'))
        True
        
        Setuptool's original pkg_resources.py file should be copied into our app
        directory:
        
        >>> pkg_resources = os.path.join(
        ...     'parts', 'second_sample', 'pkg_resources.py')
        >>> os.path.isfile(pkg_resources)
        True
        >>> pkg_resources_file = open(pkg_resources, "r")
        >>> pkg_resources_file.read().startswith('def _dummy_func')
        False
        >>> pkg_resources_file.close()
        
        We've configured the recipe to patch the SDK's source tree:
        
        >>> gae_sdk_root = os.path.join('parts', 'google_appengine')
        >>> patched_dir = os.listdir(os.path.join(gae_sdk_root, 'lib'))
        >>> patched_file = open(
        ...     os.path.join(gae_sdk_root, 'google', 'appengine', 'tools',
        ...                  'dev_appserver.py')).read()[:1300]
        >>> 'patched' in patched_dir
        True
        >>> '# This file is patched by the patch command.' in patched_file
        True
        
        Changes
        =======
        
        1.7.0 2011-05-16
        ----------------
        
        - Adds support for regular expression excludes.
        
        - Minor refactoring and clean-up.
        
        
        1.6.2 2010-04-18
        ----------------
        
        - Fixes an issue where symlink fails on platforms other than UNIX.
        
        
        1.6.1 2010-04-03
        ----------------
        
        - Fixes an issue where the patch option can't be used without patch-options.
        
        
        1.6.0 2010-04-03
        ----------------
        
        - New option to specify a patch file for modifying the Google App Engine
        SDK source tree.
        
        
        1.5.1 2010-03-27
        ----------------
        
        - Fixes an issue where setuptools wasn't found.
        
        - Distribute can be used as a replacement for setuptools.
        
        - Added credits for Attila Olah.
        
        
        1.5.0 2010-03-27
        ----------------
        
        - Adds option to copy setuptool's original pkg_resources.py file into app
        directory rather than writing a dummy stub.
        
        
        1.4.1 2010-01-18
        ----------------
        
        - Fixes an issue where egg contents which are just single modules aren't
        copied into the project.
        
        - http://code.google.com/p/rodrecipes/source/detail?r=14
        
        
        1.4.0 2009-08-26
        ----------------
        
        - Added server-script option.
        - Tests added.
        
        
        1.3.1 2009-07-15
        ----------------
        
        - Fixed issue when copying egg contents.
        
        
        1.3.0 2009-07-04
        ----------------
        
        - Added options zip-packages and exclude.
        
        
        1.2.1 2009-07-03
        ----------------
        
        - Uses a much better method for excluding optional c extensions and compiled
        modules.
        - A step forward in platform independence.
        
        
        1.2.0 2009-06-24
        ----------------
        
        - Creates appcfg script.
        
        
        1.1.1 2009-06-07
        ----------------
        
        - Makes symbolic links for application files.
        - Downloads stay untouched.
        
        
        1.1.0 2009-04-08
        ----------------
        
        - Mostly rewritten.
        - Installs google appengine as part.
        - Adding dummy pkg_resources module to handle namespace package relicts.
        - Tests added.
        - Ready for Google App Engine SDK 1.2.0
        
        
        1.0.0b5 2009-01-20
        ------------------
        
        - Requires Google App Engine SDK 1.1.8
        
        
        1.0.0b4 2008-09-04
        ------------------
        
        - Create and use PROJECT_HOME/var to place temporary project files like
        data base files.
        
        
        1.0.0b3 2008-09-02
        ------------------
        
        - Copy package contents to temporary library directory.
        
        
        1.0.0b2 2008-09-02
        ------------------
        
        - Installs the whole distribution in the parts directory now. So it is ready
        to test and deploy.
        
        
        1.0.0b1 2008-09-01
        ------------------
        
        - First beta release.
        
Keywords: appengine gae zc.buildout recipe zope
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Buildout
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
