Daniel Nouri's Old Blog

Getting Paste Script

Just easy_install Paste Script like so:

easy_install PasteScript

This will download the latest Paste Script and all its dependencies from the Cheese Shop.

If you don't want easy_install to put the downloaded packages into your standard site-packages directory, consider using workingenv or look at Custom Installation Locations.

Using Paste Script

This is where it gets interesting. When we invoke the paster create command, we'll be asked a couple of questions, most of which we can answer by hitting enter and thereby using the default value:

$ paster create
Selected and implied templates:
  PasteScript#basic_package  A basic setuptools-enabled package

Enter project name: MyFancyNewProject
Variables:
  package:  myfancynewproject
  project:  MyFancyNewProject
Creating template basic_package
Enter version (Version (like 0.1)) ['']:
Enter description (One-line description of the package) ['']: This is a fancy project

...

After answering the questions, Paste Script will set up the files for our project:

Creating directory ./MyFancyNewProject
  Recursing into +package+
    Creating ./MyFancyNewProject/myfancynewproject/
    Copying __init__.py to ./MyFancyNewProject/myfancynewproject/__init__.py
  Recursing into +project+.egg-info
    Creating ./MyFancyNewProject/MyFancyNewProject.egg-info/
  Recursing into docs
    Creating ./MyFancyNewProject/docs/
  Copying setup.cfg to ./MyFancyNewProject/setup.cfg
  Copying setup.py_tmpl to ./MyFancyNewProject/setup.py
Running /usr/bin/python setup.py egg_info

Your newly started project is now ready for distribution!

Paste Script and Subversion

By the way, there's also a handy --svn-repository=REPOS argument to the paster create command which will create a basic Subversion layout for your project. Pass the Subversion directory that you want to be used as the parent of your project's directory like so:

$ paster create --svn-repository=http://mysubversionserver/myprojects/

This will create a MyFancyNewProject directory under myprojects/ and it'll create trunk, branches and tags subdirectories therein.

Pluggability

Adding your own set of templates to Paste Script is fairly simple. The Paste Script developer documentation explains how to do that.

Based on that, I've had the idea of creating a simple set of templates for quickstarting a Zope project. There's already the skeletor project which aims to do something similar for Zope 2. When I looked at skeletor though, I decided that it does a bit much and it's fairly complex. I also ran into a few tracebacks while trying to use the tool. Which led me to trying out Paste Script.

ZopeSkel project

I've started a small project which I call ZopeSkel. The only purpose of ZopeSkel is to add a couple of templates to the existing ones of Paste Script. Right now, ZopeSkel contains only one template called basic_zope, which is very bare bones. Take a look at the project's templates directory.

You can think of ZopeSkel as a minimal example of creating your own templates package for use with Paste Script. I want to look and see if I can create a good set of templates. Please tell me what kinds of templates would be helpful for you!

To install the latest ZopeSkel from Subversion do easy_install http://svn.plone.org/svn/collective/ZopeSkel/trunk#egg=ZopeSkel-dev. After installing, you can see that the list of templates available to paster create has been extended:

$ paster create --list-templates
Available templates:
  basic_package:  A basic setuptools-enabled package
  basic_zope:     A Zope project
  paste_deploy:   A web application deployed through paste.deploy

Try paster create --help to find out more about the create command.

setuptools Development Mode

When developing setuptools enabled projects, setuptool's Development Mode is essential. In Development Mode, you can edit code inside the checkout directory and immediatley see the effects of your changes when running the program. (If you make any changes to the project's setup script or C extensions, you need to run python setup.py develop).

Building the egg

1. Checkout a bundle of Plone that contains all the necessary products in the Products/ subdirectory
2. Run setup.py bdist_egg. This requires you to have setuptools installed.

The egg should be now in dist/Plone*egg, ready for installation. You can distribute your egg at this point.

Note: Currently there is a problem that prevents ATContentTypes' thirdparty package from being included. This should probably be fixed in ATContentTypes. For now, you need to put an empty __init__.py file into the Products/ATContentTypes/thirdparty directory.

Installing the egg

You can install the egg site-wide. With the effect that the Products will be available for import implicitly for every Zope 2 instance in the site. Doing this is very simple:

easy_install dist/Plone*egg

Because Zope 2 will automatically scan all packages inside Products, there is no way to control exclusion of a Product in your instance. This is less than ideal. If our Product were not to use Zope2's Products namespace (which is well doable using Rocky Burt's pythonproducts), we could have more control of what is included, using Five's new registerPackage directive. (Note that pythonproducts was merged into Five.)

Now that all packages in Plone use the Products namespace, we'll have to think about a way to deal with this. Fortunately, easy_install comes with the --multi-version command line option, which allows you to have more control over which packages are available at runtime.

Using --multi-version, we can install our egg into the instance's lib/python directory to effectively make our egg only available in that instance:

easy_install --multi-version \
             --install-dir=$INSTANCE_HOME/lib/python/ \
             --site-dirs=$INSTANCE_HOME/lib/python/ \
             dist/Plone*egg

When you install something --multi-version, client code that uses your package has to be aware of that and do an explicit import pkg_resources; pkg_resources.require(name). In our example, we need to require('Plone') somewhen in our Zope process. I had the idea of requiring packages in zcml, similiar to how pythonproducts registers ordinary Python packages as Products. There's a pending patch for pythonproducts that enables this, although pythonproducts is maybe the wrong place to implement this:

Index: src/pythonproducts/fivedirectives.py
===================================================================
--- src/pythonproducts/fivedirectives.py      (revision 26757)
+++ src/pythonproducts/fivedirectives.py      (working copy)
@@ -16,6 +16,7 @@
 """

 from zope.interface import Interface
+from zope.schema import BytesLine
 from zope.configuration.fields import GlobalObject


@@ -35,4 +36,11 @@
                     u'with a ProductContext instance',
         required=False
         )
-
\ No newline at end of file
+
+class IRequireDistributionDirective(Interface):
+    """pkg_resources.require() a distribution."""
+
+    name = BytesLine(
+        title=u'Target distribution',
+        required=True,
+        )
Index: src/pythonproducts/meta.zcml
===================================================================
--- src/pythonproducts/meta.zcml      (revision 26757)
+++ src/pythonproducts/meta.zcml      (working copy)
@@ -12,6 +12,12 @@
        handler="Products.pythonproducts.pythonproducts.registerPackage"
        />

+    <meta:directive
+       name="requireDistribution"
+       schema="Products.pythonproducts.fivedirectives.IRequireDistributionDirective"
+       handler="Products.pythonproducts.pythonproducts.requireDistribution"
+       />
+
   </meta:directives>

 </configure>
Index: src/pythonproducts/pythonproducts.py
===================================================================
--- src/pythonproducts/pythonproducts.py      (revision 26757)
+++ src/pythonproducts/pythonproducts.py      (working copy)
@@ -37,6 +37,13 @@
         args = (package,initialize)
         )

+def requireDistribution(_context, name):
+    """ZCML directive function for requiring a distribution using
+    pkg_resources.
+    """
+
+    import pkg_resources
+    pkg_resources.require(name)

 def _registerPackage(module_, initFunc=None):
     """Registers the given python package as a Zope 2 style product

After applying this patch to your pythonproducts installation, you can go ahead and include Plone in your instance using zcml. Create a $INSTANCE_HOME/etc/package-includes/plone-configure.zcml file and put the following in it:

<configure xmlns="http://namespaces.zope.org/zope"
           xmlns:five="http://namespaces.zope.org/five">
    <five:requireDistribution name="Plone" />
</configure>

Please refer to the pythonproducts README for details on where to add zcml and why.

Now start up your Zope and hopefully see Plone getting loaded.

Note that for packages which are not in the Products namespace package, i.e. for Product-less Python packages you would need to use pythonproducts' registerPackage directive as well. (Which is a good thing.) For these packages, the whole process becomes a lot easier, because you can just easy_install away and be done, or if you need instance- specific versions/packages, use --multi-version and the requireDistribution directive.