On Oct 31, 2006, at 11:30 AM, Daniel Nouri wrote:

Tres Seaver wrote:
Daniel Nouri wrote:
whit wrote:
<snap>
We still have to handle the Products issue for add ons(mcdonc, donde estamos con Basketos?). But if Basket is added to 2.11, this might not
be such a big deal.
From what I know, Basket has been abandoned and there's even no good
reason for using it. Inside a workingenv you can just go and install
egged Products without problems.

Basket gives Zope the framework to tickle the 'initialize' entry point
in eggs, which is *not* unnecessary AFAIK.

'intialize' will be called for eggs that use the Products namespace
package.  If the Product lives outside of Products, it must use the
'five:registerPackage' directive so that its 'initialize' is called.

I know nothing of five:registerPackage, but Basket's model doesn't care whether or not a package is in the Products namespace. It has two modes: DWIM mode, which calls "initialize" for all packages in eggs which have a "zope2.initialize" entry point, and a non-DWIM mode under which you must spell out the packages that should be initialized in a separate INI file (this is akin to using ZCML to spell out each of them). Note that in the model that basket uses, an egg might contain more than one Product as well. The egg contains a 'zope2.initialize' entry point for each product which the egg contains. I've pasted the Basket readme to the end of this email, which explains all of this.


One thing to note is that if you install such an egg that has a Products namespace system-wide, it will be 'initialize'd in every Zope instance. So it's advisable to 1) not use the Products namespace package and rely on 'five:registerPackage' if you need 'initialize' and 2) use workingenv
or zc.buildout to install the eggs.

I think the reason that Phillip put entry points in the egg spec is just for this sort of thing. I'm not sure if they're being used now for Zope 2 eggs (or if there even is such a thing), but imo they probably should be.

- C

Basket Overview

  Basket is a Zope 2 product which allows you to employ the Python Egg
  format to deploy other Zope 2 products.

Where Do Eggs Go?

  You can put Product eggs anywhere on your Zope 2 instance's
  PYTHONPATH.  A "safe" place to put them is
  '$INSTANCE_HOME/lib/python' which is on the PYTHONPATH of every
  post-2.6 Zope 2 installation.

Definitions

  Product -- A Python package that (optionally) includes an
  initialization function which gets called at Zope startup time.
  Products may be packaged as eggs using Basket; otherwise they are
  typically packaged as tarballs which are meant to be unpacked in a
  Zope 2 "Products" directory.

Egg Product -- a Product packaged up as part of a Product Distribution.

  Product Distribution -- A Python "egg" which contains one or more
  Zope 2 Products.

How Does Basket Determine Which Products To Install?

  Default: Implicit

    By default, Basket will scan your PYTHONPATH for files or
    directories ending with the extension ".egg".  These are known as
    "distributions".  For each of these distributions Basket finds, it
    will introspect the content of the file or directory.  If the file
    is a zip file and its egg metadata contains one or more
    "zope2.initialize" "entry points", this distribution will be
    considered to be a Product distribution and its constituent
    Products will be considered for initialization.  The same action
    will happen if the .egg is a directory.  If two versions of the
    same distribution are found on the PYTHONPATH, Basket will prevent
    startup from occurring by raising a
    pkg_resources.VersionConflictError.  If Basket detects a situation
    in which two distinct Product distributions contain a Product that
    has the same name (a case which is not caught by pkg_resources),
    Basket will prevent startup by raising an exception.

  Optional: Explicit

    If you create a file in your INSTANCE_HOME/etc directory named
    PRODUCT_DISTRIBUTIONS.txt, Basket will not scan the PYTHONPATH for
    Product distributions.  Instead, Basket will attempt to load
    Product distributions based only on the explicit Python Egg-format
    Product distribution names on each line within the
    PRODUCT_DISTRIBUTIONS.txt file.  The eggs representing these
    distributions must be somewhere on the PYTHONPATH.  If a line in
    the file names a distribution that cannot be in the PYTHONPATH,
    Basket will prevent startup from occurring by raising a
    pkg_resources.DistribtionNotFound error.  If the
    PRODUCT_DISTRIBUTIONS.txt contains directives that cause two or
    more versions of the same distribution to be considered, a
    pkg_resources.VersionConflictError will be raised.  If Basket
    detects a situation in which two distinct Product distributions
    contain a Product that has the same name (a case which is not
    caught by pkg_resources), Basket will prevent startup by raising
    an exception if Zope is in debug mode.

How Do I Create Eggs that are Compatible with Basket?

  The only hard-and-fast requirement for creating a Product
  distribution is that you must create a "built
  egg":http://peak.telecommunity.com/DevCenter/PkgResources.  A
  Product distribution is are simply a set of Python packages which
  includes one or more initialization functions which Zope will call
  during its startup process.

  For your egg to be recognized as a Zope Product, you will need to
  define one or more "entry points" of type 'zope2.initialize' in your
  setup.py 'setup' call indicating which functions should be called
  during initialization.  If your product distribution contains only
  one Product, this "entry point" is conventionally just
  'SomePackageName:initialize'.  If the object that the entry point
  definition points to is a callable, it will be called with a
  "ProductContext" instance during Zope startup.  However, the object
  that the entry point definition "points" to needn't be a callable.
  If it is not a callable, Basket will not attempt to call it.  For
  Zope products that don't implement an "initialize" function,
  something like "SomePackageName:__name__" is a good "dummy" entry
  point definition.

  Products that are packaged as 'zip-safe' egg files must not attempt
  to use Zope API functions that expect Product files to exist within
  a filesystem structure.  If your Zope product does this (either
  directly or indirectly by use of a library which attempts to access
  Product files), you must ensure that you package your Product as
  "non-zip-safe".  This means that you must add a 'zip_safe = False'
  argument to your setup.py's setup call.  By doing this, your product
  will still be packaged as a zipfile and can be distributed as one,
  but Basket will know that it needs to uncompress the zipfile to a
  temporary directory at startup to make use of it.  CMF/Plone
  products which use CMF versions up to 1.6 (and perhaps beyond) need
  to be packaged as non-zip-safe because they use libraries that
  access the filesystem (such as filesystem directory views).

  A Product distribution may include a "Products" namespace package,
  but it is not required.  Each package within a Product distribution
  which directly contains a 'zope2.initialize' function will be
  considered a separate "Product".  This means that the name of a
  non-module package which directly contains the 'zope2.initialize'
  function will be used as a Product name in Zope's control panel and
  for legacy Zope API methods which expect to be able to use a Product
  name to access constructor functions.  Note that the behavior of
  Products packaged within Product distributions differs slightly from
  that of "legacy" Products inasmuch as "egg Products" will not be
  imported at Zope startup time and will not show up in the
  ControlPanel list unless their packaging specifies a
  'zope2.initialize' entry point.

Hello World (with Products Namespace Package)

  filesystem layout::

    |
    |-- setup.py
    |
    |-- Products --
                  |
                  |-- __init__.py
                  |
                  |-- product1 --
                                 |
                                 |-- __init__.py

  setup.py::

    from setuptools import setup, find_packages
    import ez_setup
    ez_setup.use_setuptools()

    setup(
        name = 'product1',
        version = '0.1',
        packages = find_packages(),
        namespace_packages=['Products'],
        entry_points = {'zope2.initialize':
                        ['initialize=Products.product1:initialize']},
        url = 'http://www.example.com/product1',
        author = 'Joe Bloggs',
        author_email = '[EMAIL PROTECTED]',
        )

  Products/__init__.py::

     # this is a namespace package

  Products/product1/__init__.py::

     # this is a product initializer
     def initialize(self):
        return "product1 initialized"

Hello World (no namespace packages)

  filesystem layout::

    |
    |-- setup.py
    |
    |-- product1 --
                   |
                   |-- __init__.py

  setup.py::

    from setuptools import setup, find_packages
    import ez_setup
    ez_setup.use_setuptools()

    setup(
        name = 'product1',
        version = '0.1',
        packages = find_packages(),
        entry_points = {'zope2.initialize':
                        ['initialize=product1:initialize']},
        url = 'http://www.example.com/product1',
        author = 'Joe Bloggs',
        author_email = '[EMAIL PROTECTED]',
        )

  product1/__init__.py::

     # this is a product initializer
     def initialize(self):
        return "product1 initialized"

Multiple Products In A Single Distribution


  filesystem layout::

    |
    |-- setup.py
    |
    |-- product1 --
    |              |
    |              |-- __init__.py
    |
    |-- product2 --
                   |
                   |-- __init__.py

  setup.py::

    from setuptools import setup, find_packages
    import ez_setup
    ez_setup.use_setuptools()

    setup(
        name = 'products1and2',
        version = '0.1',
        packages = find_packages(),
        entry_points = {'zope2.initialize':
                        ['initialize1=product1:initialize',
                         'initialize2=product2:initialize']},
        url = 'http://www.example.com/products1and2',
        author = 'Joe Bloggs',
        author_email = '[EMAIL PROTECTED]',
        )

  product1/__init__.py::

     # this is a product initializer
     def initialize(self):
        return "product1 initialized"

  product2/__init__.py::

     # this is a product initializer
     def initialize(self):
        return "product2 initialized"

Non-Zip-Safe Product

  filesystem layout::

    |
    |-- setup.py
    |
    |-- product --
                  |
                  |-- __init__.py

  setup.py::

    from setuptools import setup, find_packages
    import ez_setup
    ez_setup.use_setuptools()

    setup(
        name = 'product',
        version = '0.1',
        packages = find_packages(),
        entry_points = {'zope2.initialize':
                        ['initialize=product:initialize']},
        url = 'http://www.example.com/product1',
        author = 'Joe Bloggs',
        author_email = '[EMAIL PROTECTED]',
        zip_safe = False,
        )

  product/__init__.py::

     # this is a product initializer
     def initialize(self):
        return "non-zip-safe product initialized"

Building a Product Distribution

'python setup.py bdist_egg'

The ".egg" file created in dist is the Product distribution.  Refer
to the "setuptools
documentation":http://peak.telecommunity.com/DevCenter/setuptools for
advanced options.

Replacements for File-Bound Classes

  The following Zope classes may not be sucessfully used within a
  Product packaged as a 'zip-safe' egg::

   Globals.DTMLFile
   Globals.ImageFile
   Products.PageTemplates.PageTemplateFile.PageTemplateFile

Instead, use these replacement classes (which have compatible constructors
  and are monkey-patched into place by Basket)::

   Globals.DTMLResource
   Globals.ImageResource
   Products.PageTemplates.PageTemplateResource

  CMF's "Filesystem Directory View" and its supporting classes like
  "FSFile", "FSPageTemplate", et. al may also not be used in Products
  packaged as zipfiles.  Work to make the CMF filesystem skin
  machinery understand zipfiles is underway in a SVN branch at the
  time of this writing but is not yet released.

  Custom code within your product that expects to be able to use
  package resources as files on a filesystem (e.g. by using
  "os.listdir", "open", "os.stat", etc.) against files in the product
  package will fail.  Replace this code with the equivalent calls from
  the "pkg_resources" module (which may be imported via "import
  pkg_resources" when Basket is installed).  See the "pkg_resources
  documentation":http://peak.telecommunity.com/DevCenter/setuptools
  for more information.

Broken Objects

  If objects in your root folder show up as "Broken" that are
  instances of classes which are defined in an egg, put the following
  statement in your instance's etc/zope.conf file::

    %import Products.Basket

  This causes the Basket product to "pre-initialize" much earlier than
  it would have otherwise done so, hopefully preventing the machinery
  which marks things as broken from doing so for egg-based objects.

Forward Compatibility Notices

  Basket ships with a Python 2.3-compatible version of setuptools'
  pkg_resources module.  At Basket initialization time, this module is
  inserted into sys.modules as "pkg_resources" (possibly shadowing
  another pkg_resources module you've imported).  This is necessary
  unless we want to require people to install setuptools before using
  Basket.

  Note that the use of PRODUCT_DISTRIBUTIONS.txt may vanish in a later
  release of Basket in favor of a special section within the Zope 2
  main configuration file.

  The implicit load-all-product-distributions behavior may become
  non-default in a later release in favor of using explicit
  distribution naming.

  The "Basket" product is a stopgap solution to the problem of being
  able to package Zope products as Python eggs.  Its functionality
  will be folded into a later Zope release, at which point it will
  cease to be useful and disappear (although eggs created which make
  use of its facilities will continue to work).  Therefore, you should
  not depend on importing or otherwise using the "Products.Basket"
  package or its contents anywhere in your own Zope code.
_______________________________________________
Zope-Dev maillist  -  Zope-Dev@zope.org
http://mail.zope.org/mailman/listinfo/zope-dev
**  No cross posts or HTML encoding!  **
(Related lists - http://mail.zope.org/mailman/listinfo/zope-announce
http://mail.zope.org/mailman/listinfo/zope )

Reply via email to