Make use of add-ons via eggs

Might be outdated! This document hasn't been reviewed for Grok 1.0 and may be outdated. If you would like to review the document, please read this post. 

Purpose

A new egg has been released that will give your application lots more functionality or bling. The developer was nice enough to release it as an egg to the community via the Python packaging index (pypi). The steps below will explain how to get the new functionality into your application.

Prerequisities

I'm assuming that you already have grok installed using grokproject. For this howto, I'm using a grokproject called 'megrokformexample'. The directory structure is represented below. The key files for this exercise are setup.py and configure.zcml, they are highlighted below:

megrokformexample/
|-- bin
|-- buildout.cfg
|-- develop-eggs
|   `-- megrokformexample.egg-link
|-- parts
|-- setup.py
`-- src
    |-- megrokformexample
    |   |-- __init__.py
    |   |-- app.py
    |   |-- app_templates
    |   |   `-- index.pt
    |   |-- configure.zcml
    |   |-- ftesting.zcml
    |   `-- testing.py
    `-- megrokformexample.egg-info

Step by step

Step 1 - Identify the package that you would like to use

the listing at pypi looks like screenshot below:

Step 2 - Add the package information to the setup.py and configure.zcml of your project

looks like:

from setuptools import setup, find_packages

version = '0.0'

setup(name='megrokformexample',
      version=version,
      description="",
      long_description="""\
""",
      # Get strings from http://www.python.org/pypi?%3Aaction=list_classifiers
      classifiers=[],
      keywords="",
      author="",
      author_email="",
      url="",
      license="",
      package_dir={'': 'src'},
      packages=find_packages('src'),
      include_package_data=True,
      zip_safe=False,
      install_requires=['setuptools',
                        'grok',
                        'megrok.form',
                        # Add extra requirements here
                        ],
      entry_points="""
      # Add entry points here
      """,
      )

This is what src/megrokformexample/configure.zcml looks like:

<configure xmlns="http://namespaces.zope.org/zope"
           xmlns:grok="http://namespaces.zope.org/grok">
  <include package="grok" />
  <include package="megrok.form" />
  <grok:grok package="." />
</configure>

Step 3 - run bin/buildout

While inside the megrokformexample directory run bin/buildout:

bin/buildout

The output should look similar to this:

Develop: '/home/david/megrokform/megrokformexample/.'
Updating app.
Getting distribution for 'megrok.form'.
Got megrok.form 0.1.
Getting distribution for 'collective.namedfile'.
Got collective.namedfile 1.1.
Getting distribution for 'zc.datetimewidget'.
Got zc.datetimewidget 0.6.1dev-r72453.
Getting distribution for 'z3c.widget'.
Got z3c.widget 0.1.7.
Getting distribution for 'zc.resourcelibrary'.
Got zc.resourcelibrary 1.0.0.
Getting distribution for 'zc.i18n>=0.5'.
Got zc.i18n 0.6.1dev-r72454.
Getting distribution for 'zope.app.cache'.
Got zope.app.cache 3.4.0.
Getting distribution for 'z3c.schema'.
Got z3c.schema 0.1-r73916.
Getting distribution for 'z3c.javascript'.
Got z3c.javascript 0.2-r80712.
Getting distribution for 'z3c.i18n'.
Got z3c.i18n 0.1.1.
Generated script '/home/david/megrokform/megrokformexample/parts/app/runzope'.
Generated script '/home/david/megrokform/megrokformexample/parts/app/debugzope'.
Updating data.
Updating zopectl.
Updating i18n.
The recipe for i18n doesn't define an update method. Using its install method.
i18n: setting up i18n tools
Generated script 'bin/i18nextract'.
Generated script 'bin/i18nmergeall'.
Updating test.
Generated script '/home/david/megrokform/megrokformexample/bin/test'.

Further information

Always read the information about the package at pypi. This is helpful in cases where a package may need additional things before it will install.