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 = 'bloggs@example.com', ) 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 = 'bloggs@example.com', ) 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 = 'bloggs@example.com', ) 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 = 'bloggs@example.com', 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.