Metadata-Version: 1.0
Name: z3c.boiler
Version: 0.1.0
Summary: A utility to help jump start Zope 3 projects
Home-page: http://pypi.python.org/pypi/z3c.boiler
Author: Paul Carduner, Stephan Richter, and hopefully others...
Author-email: zope-dev@zope.org
License: ZPL 2.1
Description: This package provides the ZBoiler Zope Features.
        
        
        Detailed Documentation
        **********************
        
        
        ======================================
        ZBoiler - A Quick Way to Boil Projects
        ======================================
        
        The ZBoiler package provides a small script to generate the boilerplate of a
        project from a simple, high-level feature XML file. An example of such a
        configuration file is `sample-project.xml`.
        
        >>> from z3c.boiler import script
        
        >>> def boil(args, showLog=False):
        ...     try:
        ...         script.main(args)
        ...     except SystemExit, err:
        ...         print 'Exit Code: %i' % err.code
        ...     else:
        ...         print 'Error: No proper exit.'
        
        Let's generate the project using the script. We need to specify the
        configuration file and a target directory.
        
        >>> import os
        >>> featureFile = os.path.join(
        ...     os.path.dirname(script.__file__), 'sample-project.xml')
        
        >>> boil(['-i', featureFile, '-o', buildPath])
        INFO - Creating directory .../z3c.sampleproject
        INFO - Creating file .../z3c.sampleproject/bootstrap.py
        INFO - Creating file .../z3c.sampleproject/setup.py
        INFO - Creating file .../z3c.sampleproject/buildout.cfg
        INFO - Creating directory .../z3c.sampleproject/src
        INFO - Creating directory .../z3c.sampleproject/src/z3c
        INFO - Creating directory .../z3c.sampleproject/src/z3c/sampleproject
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/application.zcml
        INFO - Creating directory .../z3c.sampleproject/src/z3c/sampleproject/browser
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/browser/configure.zcml
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/browser/message.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/browser/__init__.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/configure.zcml
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/interfaces.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/index.txt
        INFO - Creating directory .../z3c.sampleproject/src/z3c/sampleproject/tests
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/tests/test_doc.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/tests/__init__.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/README.txt
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/message.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/__init__.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/__init__.py
        INFO - Creating file .../z3c.sampleproject/ZBOILER.txt
        INFO - Build finished
        Exit Code: 0
        
        Let's now have a look at the generated directory:
        
        >>> ls(buildPath)
        z3c.sampleproject/
        ZBOILER.txt
        bootstrap.py
        buildout.cfg
        setup.py
        src/
        z3c/
        __init__.py
        sampleproject/
        README.txt
        __init__.py
        application.zcml
        configure.zcml
        index.txt
        interfaces.py
        message.py
        browser/
        __init__.py
        configure.zcml
        message.pytests/
        __init__.py
        test_doc.py
        
        When we try to regenerate the project again, we get a failure, since the
        directory already exists:
        
        >>> boil(['-i', featureFile, '-o', buildPath])
        CRITICAL - Failed building package because file .../z3c.sampleproject
        already exists.  Use --force to overwrite it.
        Exit Code: 1
        
        We can, however, force the directory to be overwritten as the message
        mentions:
        
        >>> boil(['-f', '-i', featureFile, '-o', buildPath])
        INFO - Creating directory .../z3c.sampleproject
        INFO - Creating file .../z3c.sampleproject/bootstrap.py
        INFO - Creating file .../z3c.sampleproject/setup.py
        INFO - Creating file .../z3c.sampleproject/buildout.cfg
        INFO - Creating directory .../z3c.sampleproject/src
        INFO - Creating directory .../z3c.sampleproject/src/z3c
        INFO - Creating directory .../z3c.sampleproject/src/z3c/sampleproject
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/application.zcml
        INFO - Creating directory .../z3c.sampleproject/src/z3c/sampleproject/browser
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/browser/configure.zcml
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/browser/message.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/browser/__init__.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/configure.zcml
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/interfaces.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/index.txt
        INFO - Creating directory .../z3c.sampleproject/src/z3c/sampleproject/tests
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/tests/test_doc.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/tests/__init__.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/README.txt
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/message.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/__init__.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/__init__.py
        INFO - Creating file .../z3c.sampleproject/ZBOILER.txt
        INFO - Build finished
        Exit Code: 0
        
        If we want less information, we can simply tell the script to be quiet:
        
        >>> boil(['-q', '-f', '-i', featureFile, '-o', buildPath])
        Exit Code: 0
        
        Fatal messages are still displayed:
        
        >>> boil(['-q', '-i', featureFile, '-o', buildPath])
        CRITICAL - Failed building package because file .../z3c.sampleproject
        already exists.  Use --force to overwrite it.
        Exit Code: 1
        
        We can also ask for more information:
        
        >>> boil(['-v', '-f', '-i', featureFile, '-o', buildPath])
        DEBUG - Updating <SimpleFileBuilder u'bootstrap.py'>
        DEBUG - Updating <PartBuilder u'versions'>
        DEBUG - Updating <PartBuilder u'zope3'>
        DEBUG - Updating <PartBuilder u'z3c.sampleproject-app'>
        DEBUG - Updating <PartBuilder u'z3c.sampleproject'>
        DEBUG - Updating <PartBuilder u'database'>
        DEBUG - Updating <PartBuilder u'docs'>
        DEBUG - Updating <PartBuilder u'python'>
        DEBUG - Updating <PartBuilder u'test'>
        DEBUG - Updating <PartBuilder u'coverage-test'>
        DEBUG - Updating <PartBuilder u'coverage-report'>
        DEBUG - Updating <PackageBuilder u'z3c'>
        DEBUG - Updating <PackageBuilder u'sampleproject'>
        DEBUG - Updating <PackageBuilder u'browser'>
        DEBUG - Updating <ModuleBuilder u'message.py'>
        DEBUG - Updating <ModuleBuilder u'interfaces.py'>
        DEBUG - Updating <PackageBuilder u'tests'>
        DEBUG - Updating <SimpleFileBuilder u'test_doc.py'>
        DEBUG - Updating <SimpleFileBuilder u'README.txt'>
        DEBUG - Updating <ModuleBuilder u'message.py'>
        DEBUG - Updating <FeatureDocBuilder u'ZBOILER.txt'>
        INFO - Creating directory .../z3c.sampleproject
        INFO - Creating file .../z3c.sampleproject/bootstrap.py
        INFO - Creating file .../z3c.sampleproject/setup.py
        INFO - Creating file .../z3c.sampleproject/buildout.cfg
        INFO - Creating directory .../z3c.sampleproject/src
        INFO - Creating directory .../z3c.sampleproject/src/z3c
        INFO - Creating directory .../z3c.sampleproject/src/z3c/sampleproject
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/application.zcml
        INFO - Creating directory .../z3c.sampleproject/src/z3c/sampleproject/browser
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/browser/configure.zcml
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/browser/message.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/browser/__init__.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/configure.zcml
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/interfaces.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/index.txt
        INFO - Creating directory .../z3c.sampleproject/src/z3c/sampleproject/tests
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/tests/test_doc.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/tests/__init__.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/README.txt
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/message.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/sampleproject/__init__.py
        INFO - Creating file .../z3c.sampleproject/src/z3c/__init__.py
        INFO - Creating file .../z3c.sampleproject/ZBOILER.txt
        INFO - Build finished
        Exit Code: 0
        
        It is also possible to use a built in project template as a basis for
        a new project.  To see an available list of built in templates, we use
        the --list option.
        
        >>> boil(['--list'])
        Available Templates:
        <BLANKLINE>
        zope-project   "Zope 3 Web Application"
        Includes all the features you would want for a Zope 3 Web Application.
        command-line   "Command Line Program"
        Includes all the features you would want for a command line program.
        python-package "Python Package"
        Just a simple python package with few bells and whistles.
        Exit Code: 0
        
        If we try to use a template that does not exist, then we are told to
        use --list:
        
        >>> boil(['-t','foobar'])
        Could not find the template "foobar".
        Use --list to see available templates.
        Exit Code: 1
        
        
        Last but not least, we also have some help for the `boil` script:
        
        >>> boil(['-h'])
        Usage: test [options]
        <BLANKLINE>
        Options:
        -h, --help            show this help message and exit
        -i FILE, --input-file=FILE
        The file containing the XML definition of the project.
        -t TEMPLATE, --template=TEMPLATE
        A project template.  Use --list to see available
        templates
        -l, --list            Show a list of available templates for use with
        --template
        -k, --interactive     When specified, runs in interactive mode prompting you
        to enter missing values.
        -o DIR, --output-dir=DIR
        The directory where project files should be generated.
        -q, --quiet           When specified, no messages are displayed.
        -v, --verbose         When specified, debug information is created.
        -f, --force           Force the package to be generated even overwriting any
        existing files.
        Exit Code: 0
        
        When no arguments are specified, help is also shown:
        
        >>> boil([])
        Usage: test [options]
        ...
        Exit Code: 0
        
        
        =======
        CHANGES
        =======
        
        Version 0.2.0 (2009-??-??)
        --------------------------
        
        
        Version 0.1.0 (2009-03-27)
        --------------------------
        
        - Initial Release
        
Keywords: zope3 project builder boiler
Platform: UNKNOWN
