======================
p01.recipe.setup:paste
======================

This Zope 3 recipes allows us to point to scripts which the recipe will install
a execute script hook for us. You can use this if you need to run a python
script which knows about some egg packages.


Options
~~~~~~~

The 'script' recipe accepts the following options:

eggs
  The names of one or more eggs, with their dependencies that should
  be included in the Python path of the generated scripts.

module
  The ``module`` which contains the ``method`` to be executed.

method
  The ``method`` which get called from the ``module``.

arguments
  Use the option ``arguments`` to pass arguments to the script.
  All the string will be copied to the script 1:1.
  So what you enter here is what you get.

environment
  The environement if needed by your script


Test
~~~~

Lets define a egg that we can use in our application:

  >>> mkdir('hello')
  >>> write('hello', 'setup.py',
  ... '''
  ... from setuptools import setup
  ... setup(name='hello')
  ... ''')

And let's define a python module which we use for our test:

  >>> write('hello', 'helloworld.py',
  ... """
  ... def helloWorld(*args):
  ...     print 'Hello World'
  ...     for a in args:
  ...         print a
  ... """)

Alos add a `__init__` to the `hello` package:

  >>> write('hello', '__init__.py', '#make package')

We'll create a `buildout.cfg` file that defines our script:

  >>> write('buildout.cfg',
  ... '''
  ... [buildout]
  ... develop = hello
  ... parts = helloworld
  ... newest = false
  ...
  ... [helloworld]
  ... recipe = p01.recipe.setup:script
  ... eggs = hello
  ... module = helloworld
  ... method = helloWorld
  ...
  ... ''' % globals())

Let's run buildout again:

  >>> print system(join('bin', 'buildout')),
  Develop: '/sample-buildout/hello'
  Installing helloworld.
  Generated script '/sample-buildout/bin/helloworld'.

And check the script again. Now we see the `helloWorld()` method is used:

  >>> cat('bin', 'helloworld')
  import sys
  sys.path[0:0] = [
      '/sample-buildout/hello',
      ]
  import os
  sys.argv[0] = os.path.abspath(sys.argv[0])
  import helloworld
  if __name__ == '__main__':
      sys.exit(helloworld.helloWorld())

Now we can call the script:

  >>> print system(join('bin', 'helloworld')),
  Hello World


Test with parameters
--------------------

Of the same script defined above.

Use the option ``arguments = `` to pass arguments to the script.
All the string will be copied to the script ``1:1``.
So what you enter here is what you get.

We'll create a ``buildout.cfg`` file that defines our script:

  >>> write('buildout.cfg',
  ... '''
  ... [buildout]
  ... develop = hello
  ... parts = helloworld
  ... newest = false
  ...
  ... [helloworld]
  ... recipe = p01.recipe.setup:script
  ... eggs = hello
  ... module = helloworld
  ... method = helloWorld
  ... arguments = 'foo', 'bar'
  ...
  ... ''' % globals())

Let's run buildout again:

  >>> print system(join('bin', 'buildout')),
  Develop: '/sample-buildout/hello'
  Uninstalling helloworld.
  Installing helloworld.
  Generated script '/sample-buildout/bin/helloworld'.

And check the script again. Now we see the `helloWorld()` method is used:

  >>> cat('bin', 'helloworld')
  #!C:\Python24\python.exe
  <BLANKLINE>
  import sys
  sys.path[0:0] = [
    '/sample-buildout/hello',
    ]
  <BLANKLINE>
  import os
  sys.argv[0] = os.path.abspath(sys.argv[0])
  <BLANKLINE>
  <BLANKLINE>
  import helloworld
  <BLANKLINE>
  if __name__ == '__main__':
      sys.exit(helloworld.helloWorld('foo', 'bar'))

Now we can call the script:

  >>> print system(join('bin', 'helloworld')),
  Hello World
  foo
  bar