plone.folder
============
Overview
--------
This package provides a base class for folderish content types based on `B-trees`_,
a.k.a. "large folders" in Plone_.
Storing content in such folders provides significant `performance benefits`_ over regular folders.
However, "large folders" do not support explicit ordering of their contents out-of-the box.
That is, you cannot manually specify the order of items within the folder,
you can only sort things according to a given criteria after fetching items from the folder.
.. _`B-tree`: http://en.wikipedia.org/wiki/B-tree
.. _`B-trees`: http://en.wikipedia.org/wiki/B-tree
.. _`Plone`: http://plone.org/
.. _`performance benefits`: http://plone.org/products/plone/roadmap/191
.. |---| unicode:: U+2014 .. em dash
Many times, though, it is desirable to be able to explicitly order a folder's content,
for example for items that are related to site navigation.
Sorting alphabetically often doesn't make sense here.
To compensate ``plone.folder`` provides ordering support for `B-tree`_ folders via the above mentioned base class,
which can make use of an adapter to store the actual order information.
It also comes with two sample adapter implementations:
* A default adapter handling order information for all objects contained in a folder.
This adapter can be used to build fully backwards-compatible drop-in replacements for folderish content.
In other words, when using this adapter `B-tree`_-based folders should behave just like the "regular" folder implementation,
but provide some of the performance benefits at the same time.
* An alternative adapter implementation that is targeted towards sites with only a relatively small percentage of content for which (explicit) order matters.
It'll only manage order information for certain content types (via a marker interface).
The latter allows to not having to separate such content from "non-orderable" content.
Up to now many large sites ended up storing "orderable" items |---|
for example everything related to navigation and typically only a few |---|
in regular folders and the bulk of the content in "large" folders,
most of the time solely for performance reasons.
This adapter will hopefully help avoid having to make this distinction in the future
and still provide the better performance characteristics of `B-tree`_ folders.
Source Code
===========
Contributors please read the document `Process for Plone core's development <https://docs.plone.org/develop/coredev/docs/index.html>`_
Sources are at the `Plone code repository hosted at Github <https://github.com/plone/plone.folder>`_.
Changelog
=========
.. You should *NOT* be adding new change log entries to this file.
You should create a file in the news directory instead.
For helpful instructions, please see:
https://github.com/plone/plone.releaser/blob/master/ADD-A-NEWS-ITEM.rst
.. towncrier release notes start
4.0.0 (2023-04-19)
------------------
Breaking changes:
- Drop python 2.7 support.
[gforcada] (#1)
Internal:
- Update configuration files.
[plone devs] (5cc689e5)
3.1.0 (2021-06-14)
------------------
New features:
- Restore webdav support [frapell] (#16)
3.0.3 (2020-06-24)
------------------
Bug fixes:
- Micro-optimization of often called loop in moveObjectsByDelta.
``x in y`` is up to 1000 times faster if y is a set and not a list.
[jensens] (#15)
3.0.2 (2020-04-20)
------------------
Bug fixes:
- Minor packaging updates. (#1)
3.0.1 (2019-10-12)
------------------
Bug fixes:
- - Fixes slow lookup of ``documentToKeyMap`` in GopipIndex.
About up to 66x speedup in some cases.
This may add up to seconds less on large navtree renderings.
[jensens] (#14)
3.0.0 (2018-10-31)
------------------
Breaking changes:
- move GopipIndex from `plone.app.folder` to `plone.folder`
[jmevissen, petschki]
Bug fixes:
- Fix KeyError when removing object that is not referenced
in ordering annotation
[vangheem]
2.0.1 (2018-09-23)
------------------
Bug fixes:
- Stabilize order of unordered items in partial ordering.
[davisagli]
- Fix ordering of content in folder in python 3.
[pbauer]
- Fix tests in py3.
[pbauer]
2.0.0 (2018-06-20)
------------------
Breaking changes:
- Drop support for Python 2.6/ Plone 4.3
[jensens]
Bug fixes:
- More Python 2 / 3 compatibility
[pbauer, ale-rt]
- Fix deprecated LazyMap import
[jensens]
1.0.11 (2018-04-08)
-------------------
New features:
- Improve logging in case ordered index is not consistent
[tomgross]
Bug fixes:
- Remove ancient buildout config
[tomgross]
- Replace deprecated testing assertion calls
[tomgross]
1.0.10 (2018-01-30)
-------------------
Bug fixes:
- Add Python 2 / 3 compatibility
[vincero]
1.0.9 (2016-08-08)
------------------
Bug fixes:
- Use zope.interface decorator.
[gforcada]
1.0.8 (2016-04-26)
------------------
Fixes:
- Update testing layers to use best practices and remove ZopeTestCase dependency,
which should fix its test isolation problems.
[gforcada]
1.0.7 (2015-07-29)
------------------
- Depend on ``Products.CMFCore`` and remove fake-cmf, because this confuses
more than it helps to reduce complexcity.
[jensens]
- Cleanup: PEP8 and do not use ``id`` built-in as identifier.
[jensens]
1.0.6 (2015-05-11)
------------------
- Whitespace cleanup, git ignores, cleanup package info.
[gforcada, rnixx, maurits]
1.0.5 (2013-12-07)
------------------
- Allow reversing the current order, without specifying a key for
sorting.
[maurits]
- Allow ordering by a method instead of an attribute.
[maurits]
1.0.4 (2012-08-30)
------------------
- Update manifest.in to fix packaging error.
[esteele]
1.0.3 (2012-08-29)
------------------
- In setup.py, name more dependencies explicitly.
[thet]
1.0.2 (2012-07-02)
------------------
- Update notifyContainerModified import location.
[hannosch]
- Add MANIFEST.in.
[WouterVH]
1.0.1 - 2010-08-08
------------------
- Added objectValues and objectItems method to the ordered folder
implementation, which use objectIds and thus the ordering information. In
Zope 2.13 BTreeFolder2 was optimized to loop over the internal _tree data
structure avoiding the objectIds indirection.
[hannosch]
1.0 - 2010-07-18
----------------
- Avoid dangerous memoization in the DefaultOrdering adapter.
[hannosch]
- Update license to GPL version 2 only.
[hannosch]
1.0b5 - 2010-03-06
------------------
- Remove support for setting ``__parent__`` and ``__name__`` for content
providing ``IContained`` as it can cause severe performance issues when
used on Zope 2.x.
[witsch]
1.0b4 - 2010-02-17
------------------
- Register all ordering adapter by default now that they can co-exist.
[witsch]
- Add `__getitem__` support to the default ordering adapter to help
previous/next support in `plone.app.folder`.
[witsch]
1.0b3 - 2010-02-09
------------------
- Make sure order changes are persisted when using the partial ordering
adapter.
[hannosch, witsch]
1.0b2 - 2010-01-28
------------------
- Make the dependency on `Products.CMFCore` a soft one.
[witsch]
- Added an 'unordered' adapter which can be used when no explicit ordering
is needed.
[davisagli]
- Allow the use of different named adapters to ``IOrdering``, with the name
determined by the folder's ``_ordering`` attribute.
[davisagli]
1.0b1 - 2009-10-10
------------------
- Fix the WebDAV content creation process by properly returning a
``NullResource`` when required.
[optilude]
1.0a3 - 2009-05-11
------------------
- Let ``objectIds`` always return all object ids, even with partial ordering.
[witsch]
1.0a2 - 2009-05-07
------------------
- Fix a bug in the default ordering that would cause the ``pos`` dict to get
out of sync when an item is deleted.
[optilude]
- Declare ``IContainer`` support.
[optilude]
- Properly set ``__parent__`` and ``__name__`` for ``IContained`` in
``_setOb()``.
[optilude]
- Add ``__getitem__``, needed when not using the CMF mix-in.
[optilude]
- Added ``__setitem__``, ``__contains__`` and ``__delitem__`` to support a
dict-like API.
[optilude]
- Fix issue with removing non-orderable content for partial ordering support.
[witsch]
- Fix ``getObjectPosition`` to return a value representing "no position" for
non-orderable content instead of raising an error.
[witsch]
- Fix boolean value of the btree-based folder base class.
[witsch]
- Factor CMF out of the base classes for the new btree-based folder class
and simplify things a bit afterwards.
[witsch]
- Add adapter providing explicit ordering only for "orderable" content.
[witsch]
- Clean up tests and their setup.
[witsch]
1.0a1 - 2008-05-27
------------------
- Initial release
[optilude, tesdal, witsch]
Raw data
{
"_id": null,
"home_page": "https://pypi.org/project/plone.folder",
"name": "plone.folder",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "folder btree order",
"author": "Plone Foundation",
"author_email": "plone-developers@lists.sourceforge.net",
"download_url": "https://files.pythonhosted.org/packages/78/80/0564d421aa0fa93aa4639416e42e9c38823b00999dc3bd48b6cfe6ed4733/plone.folder-4.0.0.tar.gz",
"platform": "Any",
"description": "plone.folder\n============\n\nOverview\n--------\n\nThis package provides a base class for folderish content types based on `B-trees`_,\na.k.a. \"large folders\" in Plone_.\nStoring content in such folders provides significant `performance benefits`_ over regular folders.\nHowever, \"large folders\" do not support explicit ordering of their contents out-of-the box.\nThat is, you cannot manually specify the order of items within the folder,\nyou can only sort things according to a given criteria after fetching items from the folder.\n\n .. _`B-tree`: http://en.wikipedia.org/wiki/B-tree\n .. _`B-trees`: http://en.wikipedia.org/wiki/B-tree\n .. _`Plone`: http://plone.org/\n .. _`performance benefits`: http://plone.org/products/plone/roadmap/191\n .. |---| unicode:: U+2014 .. em dash\n\nMany times, though, it is desirable to be able to explicitly order a folder's content,\nfor example for items that are related to site navigation.\nSorting alphabetically often doesn't make sense here.\n\nTo compensate ``plone.folder`` provides ordering support for `B-tree`_ folders via the above mentioned base class,\nwhich can make use of an adapter to store the actual order information.\nIt also comes with two sample adapter implementations:\n\n* A default adapter handling order information for all objects contained in a folder.\n This adapter can be used to build fully backwards-compatible drop-in replacements for folderish content.\n In other words, when using this adapter `B-tree`_-based folders should behave just like the \"regular\" folder implementation,\n but provide some of the performance benefits at the same time.\n\n* An alternative adapter implementation that is targeted towards sites with only a relatively small percentage of content for which (explicit) order matters.\n It'll only manage order information for certain content types (via a marker interface).\n\nThe latter allows to not having to separate such content from \"non-orderable\" content.\nUp to now many large sites ended up storing \"orderable\" items |---|\nfor example everything related to navigation and typically only a few |---|\nin regular folders and the bulk of the content in \"large\" folders,\nmost of the time solely for performance reasons.\nThis adapter will hopefully help avoid having to make this distinction in the future\nand still provide the better performance characteristics of `B-tree`_ folders.\n\nSource Code\n===========\n\nContributors please read the document `Process for Plone core's development <https://docs.plone.org/develop/coredev/docs/index.html>`_\n\nSources are at the `Plone code repository hosted at Github <https://github.com/plone/plone.folder>`_.\n\nChangelog\n=========\n\n.. You should *NOT* be adding new change log entries to this file.\n You should create a file in the news directory instead.\n For helpful instructions, please see:\n https://github.com/plone/plone.releaser/blob/master/ADD-A-NEWS-ITEM.rst\n\n.. towncrier release notes start\n\n4.0.0 (2023-04-19)\n------------------\n\nBreaking changes:\n\n\n- Drop python 2.7 support.\n [gforcada] (#1)\n\n\nInternal:\n\n\n- Update configuration files.\n [plone devs] (5cc689e5)\n\n\n3.1.0 (2021-06-14)\n------------------\n\nNew features:\n\n\n- Restore webdav support [frapell] (#16)\n\n\n3.0.3 (2020-06-24)\n------------------\n\nBug fixes:\n\n\n- Micro-optimization of often called loop in moveObjectsByDelta.\n ``x in y`` is up to 1000 times faster if y is a set and not a list.\n [jensens] (#15)\n\n\n3.0.2 (2020-04-20)\n------------------\n\nBug fixes:\n\n\n- Minor packaging updates. (#1)\n\n\n3.0.1 (2019-10-12)\n------------------\n\nBug fixes:\n\n\n- - Fixes slow lookup of ``documentToKeyMap`` in GopipIndex.\n About up to 66x speedup in some cases.\n This may add up to seconds less on large navtree renderings.\n [jensens] (#14)\n\n\n3.0.0 (2018-10-31)\n------------------\n\nBreaking changes:\n\n- move GopipIndex from `plone.app.folder` to `plone.folder`\n [jmevissen, petschki]\n\nBug fixes:\n\n- Fix KeyError when removing object that is not referenced\n in ordering annotation\n [vangheem]\n\n\n2.0.1 (2018-09-23)\n------------------\n\nBug fixes:\n\n- Stabilize order of unordered items in partial ordering.\n [davisagli]\n\n- Fix ordering of content in folder in python 3.\n [pbauer]\n\n- Fix tests in py3.\n [pbauer]\n\n\n2.0.0 (2018-06-20)\n------------------\n\nBreaking changes:\n\n- Drop support for Python 2.6/ Plone 4.3\n [jensens]\n\nBug fixes:\n\n- More Python 2 / 3 compatibility\n [pbauer, ale-rt]\n\n- Fix deprecated LazyMap import\n [jensens]\n\n\n1.0.11 (2018-04-08)\n-------------------\n\nNew features:\n\n- Improve logging in case ordered index is not consistent\n [tomgross]\n\nBug fixes:\n\n- Remove ancient buildout config\n [tomgross]\n\n- Replace deprecated testing assertion calls\n [tomgross]\n\n\n1.0.10 (2018-01-30)\n-------------------\n\nBug fixes:\n\n- Add Python 2 / 3 compatibility\n [vincero]\n\n\n1.0.9 (2016-08-08)\n------------------\n\nBug fixes:\n\n- Use zope.interface decorator.\n [gforcada]\n\n\n1.0.8 (2016-04-26)\n------------------\n\nFixes:\n\n- Update testing layers to use best practices and remove ZopeTestCase dependency,\n which should fix its test isolation problems.\n [gforcada]\n\n\n1.0.7 (2015-07-29)\n------------------\n\n- Depend on ``Products.CMFCore`` and remove fake-cmf, because this confuses\n more than it helps to reduce complexcity.\n [jensens]\n\n- Cleanup: PEP8 and do not use ``id`` built-in as identifier.\n [jensens]\n\n\n1.0.6 (2015-05-11)\n------------------\n\n- Whitespace cleanup, git ignores, cleanup package info.\n [gforcada, rnixx, maurits]\n\n\n1.0.5 (2013-12-07)\n------------------\n\n- Allow reversing the current order, without specifying a key for\n sorting.\n [maurits]\n\n- Allow ordering by a method instead of an attribute.\n [maurits]\n\n\n1.0.4 (2012-08-30)\n------------------\n\n- Update manifest.in to fix packaging error.\n [esteele]\n\n\n1.0.3 (2012-08-29)\n------------------\n\n- In setup.py, name more dependencies explicitly.\n [thet]\n\n\n1.0.2 (2012-07-02)\n------------------\n\n- Update notifyContainerModified import location.\n [hannosch]\n\n- Add MANIFEST.in.\n [WouterVH]\n\n\n1.0.1 - 2010-08-08\n------------------\n\n- Added objectValues and objectItems method to the ordered folder\n implementation, which use objectIds and thus the ordering information. In\n Zope 2.13 BTreeFolder2 was optimized to loop over the internal _tree data\n structure avoiding the objectIds indirection.\n [hannosch]\n\n\n1.0 - 2010-07-18\n----------------\n\n- Avoid dangerous memoization in the DefaultOrdering adapter.\n [hannosch]\n\n- Update license to GPL version 2 only.\n [hannosch]\n\n\n1.0b5 - 2010-03-06\n------------------\n\n- Remove support for setting ``__parent__`` and ``__name__`` for content\n providing ``IContained`` as it can cause severe performance issues when\n used on Zope 2.x.\n [witsch]\n\n\n1.0b4 - 2010-02-17\n------------------\n\n- Register all ordering adapter by default now that they can co-exist.\n [witsch]\n\n- Add `__getitem__` support to the default ordering adapter to help\n previous/next support in `plone.app.folder`.\n [witsch]\n\n\n1.0b3 - 2010-02-09\n------------------\n\n- Make sure order changes are persisted when using the partial ordering\n adapter.\n [hannosch, witsch]\n\n\n1.0b2 - 2010-01-28\n------------------\n\n- Make the dependency on `Products.CMFCore` a soft one.\n [witsch]\n\n- Added an 'unordered' adapter which can be used when no explicit ordering\n is needed.\n [davisagli]\n\n- Allow the use of different named adapters to ``IOrdering``, with the name\n determined by the folder's ``_ordering`` attribute.\n [davisagli]\n\n\n1.0b1 - 2009-10-10\n------------------\n\n- Fix the WebDAV content creation process by properly returning a\n ``NullResource`` when required.\n [optilude]\n\n\n1.0a3 - 2009-05-11\n------------------\n\n- Let ``objectIds`` always return all object ids, even with partial ordering.\n [witsch]\n\n\n1.0a2 - 2009-05-07\n------------------\n\n- Fix a bug in the default ordering that would cause the ``pos`` dict to get\n out of sync when an item is deleted.\n [optilude]\n\n- Declare ``IContainer`` support.\n [optilude]\n\n- Properly set ``__parent__`` and ``__name__`` for ``IContained`` in\n ``_setOb()``.\n [optilude]\n\n- Add ``__getitem__``, needed when not using the CMF mix-in.\n [optilude]\n\n- Added ``__setitem__``, ``__contains__`` and ``__delitem__`` to support a\n dict-like API.\n [optilude]\n\n- Fix issue with removing non-orderable content for partial ordering support.\n [witsch]\n\n- Fix ``getObjectPosition`` to return a value representing \"no position\" for\n non-orderable content instead of raising an error.\n [witsch]\n\n- Fix boolean value of the btree-based folder base class.\n [witsch]\n\n- Factor CMF out of the base classes for the new btree-based folder class\n and simplify things a bit afterwards.\n [witsch]\n\n- Add adapter providing explicit ordering only for \"orderable\" content.\n [witsch]\n\n- Clean up tests and their setup.\n [witsch]\n\n\n1.0a1 - 2008-05-27\n------------------\n\n- Initial release\n [optilude, tesdal, witsch]\n",
"bugtrack_url": null,
"license": "GPL version 2",
"summary": "BTree-based folder implementation with order support",
"version": "4.0.0",
"split_keywords": [
"folder",
"btree",
"order"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "53117ff3c12183a49801420f49d1f14834668f3a9dfa3e2dce77ccdd68a2c451",
"md5": "06fd93d8aa1ae85cc602abe551542e1f",
"sha256": "154aad1bd683178c8d4552ed0d0989afa96476cfc56767badca4adb1f83ebf60"
},
"downloads": -1,
"filename": "plone.folder-4.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "06fd93d8aa1ae85cc602abe551542e1f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 25886,
"upload_time": "2023-04-19T07:18:37",
"upload_time_iso_8601": "2023-04-19T07:18:37.188595Z",
"url": "https://files.pythonhosted.org/packages/53/11/7ff3c12183a49801420f49d1f14834668f3a9dfa3e2dce77ccdd68a2c451/plone.folder-4.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "78800564d421aa0fa93aa4639416e42e9c38823b00999dc3bd48b6cfe6ed4733",
"md5": "d29a8745719a01c7057d8511e68a11d2",
"sha256": "09a684b9cc4bc4c34221bc70a3ab711a6f97e650988f104a38ba68b5a07f53e0"
},
"downloads": -1,
"filename": "plone.folder-4.0.0.tar.gz",
"has_sig": false,
"md5_digest": "d29a8745719a01c7057d8511e68a11d2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 30207,
"upload_time": "2023-04-19T07:18:39",
"upload_time_iso_8601": "2023-04-19T07:18:39.667868Z",
"url": "https://files.pythonhosted.org/packages/78/80/0564d421aa0fa93aa4639416e42e9c38823b00999dc3bd48b6cfe6ed4733/plone.folder-4.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-19 07:18:39",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "plone.folder"
}
JSON