Convert setup.py to pyproject.toml

.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:

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::
+
+  <div tal:define="batch view/batchresults;">
+
+or you can do it in the template itself if necessary::
+
+  <div tal:define="Batch python:modules['plone.batching'].Batch;
+                   b_size python:30;b_start python:0;b_start request/b_start | b_start;
+                   batch python:Batch(results, b_size, int(b_start), orphan=1);">
+
+For the navigation you add the following snippet to your template::
+
+ <tal:batchnavigation
+     define="batchnavigation nocall:context/@@batchnavigation"
+     replace="structure python:batchnavigation(batch)" />
+
+For backwards compatibility *plone.batching* provides a drop in metal macro *navigation* in the *batch_macros* template.
+Add it to the template like this::
+
+ <div metal:use-macro="context/batch_macros/macros/navigation" />
+
+
+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.
+
+::
+
+   <div tal:replace="structure view/batching" />
+
+Incompatibilities
+-----------------
+
+XXX __len__ method

news/+setup-to-pyproject.internal

@@ -0,0 +1,2 @@
+Move package metadata from ``setup.py`` to ``pyproject.toml``.
+[plone devs]

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"

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()