Metadata-Version: 1.0
Name: Products.BTreeFolder2
Version: 2.13.4
Summary: A BTree based implementation for Zope 2's OFS.
Home-page: http://pypi.python.org/pypi/Products.BTreeFolder2
Author: Zope Foundation and Contributors
Author-email: zope-dev@zope.org
License: ZPL 2.1
Description: Overview
        ========
        
        BTreeFolder2 is a Zope product that acts like a Zope 2 OFS folder but can
        store many more items.
        
        When you fill a Zope folder with too many items, both Zope and your
        browser get overwhelmed.  Zope has to load and store a large folder
        object, and the browser has to render large HTML tables repeatedly.
        Zope can store a lot of objects, but it has trouble storing a lot of
        objects in a single standard folder.
        
        Zope Corporation once had an extensive discussion on the subject.  It
        was decided that we would expand standard folders to handle large
        numbers of objects gracefully.  Unfortunately, Zope folders are used
        and extended in so many ways today that it would be difficult to
        modify standard folders in a way that would be compatible with all
        Zope products.
        
        So the BTreeFolder product was born.  It stored all subobjects in a
        ZODB BTree, a structure designed to allow many items without loading
        them all into memory.  It also rendered the contents of the folder as
        a simple select list rather than a table.  Most browsers have no
        trouble rendering large select lists.
        
        But there was still one issue remaining.  BTreeFolders still stored
        the ID of all subobjects in a single database record.  If you put tens
        of thousands of items in a single BTreeFolder, you would still be
        loading and storing a multi-megabyte folder object.  Zope can do this,
        but not quickly, and not without bloating the database.
        
        BTreeFolder2 solves this issue.  It stores not only the subobjects but
        also the IDs of the subobjects in a BTree.  It also batches the list
        of items in the UI, showing only 1000 items at a time.  So if you
        write your application carefully, you can use a BTreeFolder2 to store
        as many items as will fit in physical storage.
        
        There are products that depend on the internal structure of the
        original BTreeFolder, however.  So rather than risk breaking those
        products, the product has been renamed.  You can have both products
        installed at the same time.  If you're developing new applications,
        you should use BTreeFolder2.
        
        
        Usage
        =====
        
        The BTreeFolder2 user interface shows a list of items rather than a
        series of checkboxes. To visit an item, select it in the list and
        click the "edit" button.
        
        BTreeFolder2 objects provide Python dictionary-like methods to make them
        easier to use in Python code than standard folders::
        
            has_key(key)
            keys()
            values()
            items()
            get(key, default=None)
            __len__()
        
        keys(), values(), and items() return sequences, but not necessarily
        tuples or lists.  Use len(folder) to call the __len__() method.  The
        objects returned by values() and items() have acquisition wrappers.
        
        BTreeFolder2 also provides a method for generating unique,
        non-overlapping IDs::
        
            generateId(prefix='item', suffix='', rand_ceiling=999999999)
        
        The ID returned by this method is guaranteed to not clash with any
        other ID in the folder.  Use the returned value as the ID for new
        objects.  The generated IDs tend to be sequential so that objects that
        are likely related in some way get loaded together.
        
        BTreeFolder2 implements the full Folder interface, with the exception
        that the superValues() method does not return any items.  To implement
        the method in the way the Zope codebase expects would undermine the
        performance benefits gained by using BTreeFolder2.
        
        Changelog
        =========
        
        2.13.4 (2011-12-12)
        -------------------
        
        - Provide security declaration for `BTreeFolder2Base.hasObject` method.
        
        - Add some tests for correct `getattr` behavior.
        
        - Minor `__getattr__` and `_getOb` optimizations.
        
        2.13.3 (2011-03-15)
        -------------------
        
        - `keys`, `values` and `items` methods are now exactly the same as
          `objectIds`, `objectValues` and `objectItems`. They did the same before
          already but duplicated the code.
        
        2.13.2 (2011-03-08)
        -------------------
        
        - `objectValues` and `objectItems` no longer do a special handling when no
          special `spec` is requested as `objectIds` already does the correct
          handling.
        
        2.13.1 (2010-08-04)
        -------------------
        
        - Make sure that methods returning objects return them Acquisition wrapped.
        
        - Be more careful in calling our own keys, values and items methods, as
          sub-classes might have overridden some of them.
        
        2.13.0 (2010-07-11)
        -------------------
        
        - Changed the `objectIds`, `objectItems` and `objectValues` methods to use the
          internal OOBTree methods directly if no `spec` argument is passed.
        
        - Change implementation of `keys`, `items` and `values` method to access the
          `self._tree` OOBTree methods directly. This avoids lookups in the meta_types
          structures.
        
        - Implement the full dictionary protocol including `__getitem__`,
          `__delitem__`, `__setitem__`, `__nonzero__`, `__iter__` and `__contains__`.
        
        - Released as separate package.
        
Platform: UNKNOWN
