diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 7ff44ed..7e31530 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -69,7 +69,7 @@ repos: rev: "0.24.2" hooks: - id: check-python-versions - args: ['--only', 'setup.py,tox.ini'] + args: ['--only', 'pyproject.toml,tox.ini'] - repo: https://github.com/collective/i18ndude rev: "6.3.0" hooks: diff --git a/README.rst b/README.rst index 3026d34..53df48e 100644 --- a/README.rst +++ b/README.rst @@ -5,3 +5,116 @@ This package includes facilities for creating a batched sequence. It originated from the the PloneBatch module written for Plone which in itself has been based on Zope2's ZTUtils.Batch. + +Usage +===== + +A batch defined in plone.batching usually consists of two things: + + 1. A batch object. + This is usually a wrapper for a sequence, which provides slices of information. + + #. A batch view. + This is needed for display. + It contains links to navigate to the slices defined in 1. + +Both elements can be defined and accessed in Python code AND pagetemplates. + +Batch navigation in templates +----------------------------- + +For the use of batching features in Page Templates *plone.batching* the first thing you have to do is to create a sequence batch and put it in a template variable named *batch*. +You should do this in a view class if possible:: + +
+ +or you can do it in the template itself if necessary:: + +
+ +For the navigation you add the following snippet to your template:: + + + +For backwards compatibility *plone.batching* provides a drop in metal macro *navigation* in the *batch_macros* template. +Add it to the template like this:: + +
+ + +Usage in Python code +-------------------- + +A batch is instantiated like this:: + + >>> from plone.batching import Batch + >>> batch = Batch(range(100), size=15, orphan=10) + +This generates 5 subbatches with 15 items from the sequence [0, 1, ..., 99] and one subbatch with the last 25 items (including 10 orphaned items). +For a detailed description of available parameters for a batch look at the API of the BaseBatch class. + +Another way to instaniate a batch is like this:: + + >>> batch = Batch.fromPagenumber(range(100), pagesize=15, pagenumber=1) + +This results in 6 batches with 15 items and one batch with the last 10 items. +This way of creating a batch is meant as a short cut and does not support all the options the canonical constructor supports. + +For big sequences there is another base class provided by the package: *QuantumBatch*. +This batch generates quantum leaps for quicker navigation. + +:: + + >>> from plone.batching.batch import QuantumBatch + >>> qb = QuantumBatch(range(1000), 10, start=500, quantumleap=1) + >>> qb.leapforward + [69, 84] + >>> qb.leapback + [18, 33] + +It is possible to navigate the batch stored in the two attributes *leapback* and *leapforward* with 5 clicks. + +Usage in Views +-------------- + +Plone.batching comes with a customizable batch View *batchnavigation* with the view class *BatchView*. +The view comes with a template. +All you have to do, if you want to customize it, is to override the make_link-method. +This method should return a string with the link to the given *pagenumber*. +Here is an example from the folder_contents implementation in plone.app.content:: + + >>> from plone.batching.browser import BatchView + >>> from ZTUtils import make_query + + >>> class MyBatchView(BatchView): + ... def make_link(self, pagenumber): + ... batchlinkparams = self.request.form.copy() + ... return '%s?%s' % (self.request.ACTUAL_URL, + ... make_query(batchlinkparams, {'pagenumber': pagenumber})) + +One thing you have to keep in mind is to call the batch view with a batch as the first argument. + +:: + + >>> from Products.Five import BrowserView + >>> class MyContentView(BrowserView): + ... def batch(self): + ... " " # see above how a batch is defined + ... + ... def batching(self): + ... return MyBatchView(self.context, self.request)(self.batch) + +Now you can use this in the template of your view. + +:: + +
+ +Incompatibilities +----------------- + +XXX __len__ method diff --git a/docs/usage.rst b/docs/usage.rst deleted file mode 100644 index f19e0dd..0000000 --- a/docs/usage.rst +++ /dev/null @@ -1,113 +0,0 @@ -Usage -===== - -A batch defined in plone.batching usually consists of two things: - - 1. A batch object. - This is usually a wrapper for a sequence, which provides slices of information. - - #. A batch view. - This is needed for display. - It contains links to navigate to the slices defined in 1. - -Both elements can be defined and accessed in Python code AND pagetemplates. - -Batch navigation in templates ------------------------------ - -For the use of batching features in Page Templates *plone.batching* the first thing you have to do is to create a sequence batch and put it in a template variable named *batch*. -You should do this in a view class if possible:: - -
- -or you can do it in the template itself if necessary:: - -
- -For the navigation you add the following snippet to your template:: - - - -For backwards compatibility *plone.batching* provides a drop in metal macro *navigation* in the *batch_macros* template. -Add it to the template like this:: - -
- - -Usage in Python code --------------------- - -A batch is instantiated like this:: - - >>> from plone.batching import Batch - >>> batch = Batch(range(100), size=15, orphan=10) - -This generates 5 subbatches with 15 items from the sequence [0, 1, ..., 99] and one subbatch with the last 25 items (including 10 orphaned items). -For a detailed description of available parameters for a batch look at the API of the BaseBatch class. - -Another way to instaniate a batch is like this:: - - >>> batch = Batch.fromPagenumber(range(100), pagesize=15, pagenumber=1) - -This results in 6 batches with 15 items and one batch with the last 10 items. -This way of creating a batch is meant as a short cut and does not support all the options the canonical constructor supports. - -For big sequences there is another base class provided by the package: *QuantumBatch*. -This batch generates quantum leaps for quicker navigation. - -:: - - >>> from plone.batching.batch import QuantumBatch - >>> qb = QuantumBatch(range(1000), 10, start=500, quantumleap=1) - >>> qb.leapforward - [69, 84] - >>> qb.leapback - [18, 33] - -It is possible to navigate the batch stored in the two attributes *leapback* and *leapforward* with 5 clicks. - -Usage in Views --------------- - -Plone.batching comes with a customizable batch View *batchnavigation* with the view class *BatchView*. -The view comes with a template. -All you have to do, if you want to customize it, is to override the make_link-method. -This method should return a string with the link to the given *pagenumber*. -Here is an example from the folder_contents implementation in plone.app.content:: - - >>> from plone.batching.browser import BatchView - >>> from ZTUtils import make_query - - >>> class MyBatchView(BatchView): - ... def make_link(self, pagenumber): - ... batchlinkparams = self.request.form.copy() - ... return '%s?%s' % (self.request.ACTUAL_URL, - ... make_query(batchlinkparams, {'pagenumber': pagenumber})) - -One thing you have to keep in mind is to call the batch view with a batch as the first argument. - -:: - - >>> from Products.Five import BrowserView - >>> class MyContentView(BrowserView): - ... def batch(self): - ... " " # see above how a batch is defined - ... - ... def batching(self): - ... return MyBatchView(self.context, self.request)(self.batch) - -Now you can use this in the template of your view. - -:: - -
- -Incompatibilities ------------------ - -XXX __len__ method - diff --git a/news/+setup-to-pyproject.internal b/news/+setup-to-pyproject.internal new file mode 100644 index 0000000..72ce34a --- /dev/null +++ b/news/+setup-to-pyproject.internal @@ -0,0 +1,2 @@ +Move package metadata from ``setup.py`` to ``pyproject.toml``. +[plone devs] diff --git a/pyproject.toml b/pyproject.toml index d6d4b32..170178a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,6 +6,61 @@ requires = ["setuptools>=68.2,<83", "wheel"] +# START-MARKER-MANUAL-CONFIG +# Anything from here until END-MARKER-MANUAL-CONFIG +# will be kept by plone.meta + +[project] +name = "plone.batching" +version = "3.0.1.dev0" +description = "Batching facilities used in Plone" +classifiers = [ + "Development Status :: 5 - Production/Stable", + "Environment :: Web Environment", + "Framework :: Plone", + "Framework :: Plone :: 6.2", + "Framework :: Plone :: Core", + "Framework :: Zope :: 5", + "Operating System :: OS Independent", + "Programming Language :: Python", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: 3.14", +] +license = "GPL-2.0-only" +dynamic = ["readme"] +requires-python = ">=3.10" +authors = [ + {name = "Plone Foundation",email = "plone-developers@lists.sourceforge.net"}, +] +maintainers = [ + {name = "Plone Foundation and contributors",email = "plone-developers@lists.sourceforge.net"}, +] +dependencies = [ + "AccessControl", + "Zope", + "zope.interface", + "zope.schema", +] +keywords = ["Plone"] + +[project.optional-dependencies] +test = [ + "zope.component", + "zope.publisher", +] + +[project.urls] +Source = "https://github.com/plone/plone.batching" +Issues = "https://github.com/plone/Products.CMFPlone/issues" +Changelog = "https://github.com/plone/plone.batching/blob/master/CHANGES.rst" + +[tool.setuptools.dynamic] +readme = {file = ["README.rst", "CHANGES.rst"]} +# END-MARKER-MANUAL-CONFIG + [tool.towncrier] directory = "news/" filename = "CHANGES.rst" diff --git a/setup.py b/setup.py index ac7400c..d5dbbc6 100644 --- a/setup.py +++ b/setup.py @@ -1,60 +1,4 @@ -from pathlib import Path from setuptools import setup -version = "3.0.1.dev0" - -long_description = ( - f"{Path('README.rst').read_text()}\n" - f"{Path('CHANGES.rst').read_text()}\n" - f"{(Path('docs') / 'usage.rst').read_text()}" -) - -setup( - name="plone.batching", - version=version, - description="Batching facilities used in Plone", - long_description=long_description, - long_description_content_type="text/x-rst", - # Get more strings from - # https://pypi.org/classifiers/ - classifiers=[ - "Development Status :: 5 - Production/Stable", - "Environment :: Web Environment", - "Framework :: Plone", - "Framework :: Plone :: 6.2", - "Framework :: Plone :: Core", - "Framework :: Zope :: 5", - "License :: OSI Approved :: GNU General Public License v2 (GPLv2)", - "Operating System :: OS Independent", - "Programming Language :: Python", - "Programming Language :: Python :: 3.10", - "Programming Language :: Python :: 3.11", - "Programming Language :: Python :: 3.12", - "Programming Language :: Python :: 3.13", - "Programming Language :: Python :: 3.14", - ], - keywords="Plone", - author="Plone Foundation", - author_email="plone-developers@lists.sourceforge.net", - url="https://pypi.org/project/plone.batching", - license="GPL", - include_package_data=True, - zip_safe=False, - python_requires=">=3.10", - install_requires=[ - "AccessControl", - "Zope", - "zope.interface", - "zope.schema", - ], - extras_require={ - "test": [ - "zope.component", - "zope.publisher", - ], - }, - entry_points=""" - [z3c.autoinclude.plugin] - target = plone - """, -) +# See pyproject.toml for package metadata +setup()