podpack-pdf 0.2.2__tar.gz

podpack_pdf-0.2.2/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.3
+Name: podpack-pdf
+Version: 0.2.2
+Summary: PDF booklet-imposition and page-splitting tools as an installable Flask app
+Author: Steve Holden
+Author-email: Steve Holden <steve@holdenweb.com>
+Requires-Dist: flask>=2.3.3
+Requires-Dist: flask-wtf>=1.2.1
+Requires-Dist: wtforms>=3.0
+Requires-Dist: pdfrw>=0.4
+Requires-Dist: reportlab>=3.6.12
+Requires-Python: >=3.12, <4.0
+Description-Content-Type: text/markdown
+
+# podpack-pdf
+
+Two PDF utilities packaged as an installable Flask app:
+
+- **PDF Booklet Maker** — imposes an A4 document four-up onto A4 sheets so that
+  each group of eight pages forms a signature, returned as a zip of the odd and
+  even sides for duplex printing.
+- **PDF Page Splitter** — explodes a PDF into one file per page, returned as a
+  zip.
+
+Extracted from [holdenweb.com](https://holdenweb.com) with its history intact. It
+answers to two contracts and requires neither: a plain Flask blueprint, and a
+[podpack](https://github.com/holdenweb/podpack) app.
+
+## Install
+
+```bash
+uv add podpack-pdf
+```
+
+The distribution is `podpack-pdf`; the module, and the app's name everywhere podpack
+needs one, is `podpack_pdf`.
+
+---
+
+## As a plain Flask blueprint
+
+```python
+from flask import Flask
+from podpack_pdf import pdf_blueprint
+
+app = Flask(__name__)
+app.config["SECRET_KEY"] = "..."          # required: the forms are CSRF-protected
+app.register_blueprint(pdf_blueprint, url_prefix="/pdf/")
+```
+
+That yields three endpoints under the prefix you chose:
+
+| Route | Purpose |
+| --- | --- |
+| `/` | Index listing both tools |
+| `/booklet` | Upload a PDF, receive a zip of imposed odd/even sides |
+| `/pagezip` | Upload a PDF, receive a zip of one file per page |
+
+Here the mount point is yours: the blueprint is relocatable, so mount it at
+`/tools/pdf` or anywhere else and its internal links follow, because they are
+generated with `url_for`.
+
+### Discovery
+
+```toml
+[project.entry-points."holdenweb.apps"]
+pdf = "podpack_pdf:pdf_blueprint"
+```
+
+A host site can enumerate its installed apps rather than hard-coding imports:
+
+```python
+from importlib.metadata import entry_points
+
+for entry_point in entry_points(group="holdenweb.apps"):
+    app.register_blueprint(entry_point.load(), url_prefix=f"/{entry_point.name}/")
+```
+
+The entry point resolves to the **blueprint itself**, not to a bespoke
+`register()` callable, so the contract is expressed in Flask's own vocabulary.
+The entry-point *name* is only a mount hint for that loop; it is not the app's
+name.
+
+### Setup hooks
+
+Anything needed at registration time goes through Flask's own deferred-
+registration hook, which is the equivalent of Django's `AppConfig.ready`. This
+package uses it on itself, to settle its two config keys:
+
+```python
+@pdf_blueprint.record_once
+def _defaults(state):
+    state.app.config.setdefault("PODPACK_PDF_BASE_TEMPLATE", STANDALONE_LAYOUT)
+    state.app.config.setdefault("PODPACK_PDF_MAX_PAGES", DEFAULT_MAX_PAGES)
+```
+
+---
+
+## As a podpack app
+
+Add the package's **import name** to the site's config file and restart:
+
+```toml
+[site]
+apps = ["podpack_pdf"]
+
+[apps.pdf]
+max_pages = 200
+```
+
+There is no second step. podpack imports the package, reads its module-level
+`site_app`, and takes the mount point, the nav entry and the config namespace
+from it:
+
+```python
+site_app = SiteApp(
+    blueprint=pdf_blueprint,
+    url_prefix="/pdf",
+    nav=(Section("PDF tools", "pdf.root_page"),),
+    init=_init,
+)
+```
+
+The app's name is not declared: podpack derives it from the blueprint's own
+name, so `pdf` — the template namespace, the config section, the data
+directory — follows from `Blueprint("pdf", ...)` in views.py.
+
+`url_prefix` is what this app asks for, not what it is entitled to. A site that
+wants these pages somewhere else in its address space says so, and the nav entry
+follows without either side restating it — a `Section` names an endpoint, so
+podpack resolves it with `url_for` as the chrome renders:
+
+```toml
+[site.mounts]
+pdf = "/tools/pdf"
+```
+
+That lives under `[site]`, not in `[apps.pdf]`, because it is the site's
+policy rather than this package's configuration — `app_config()` returns only
+what this app is meant to read, and where it was mounted is not among it.
+
+So the mount point is the host's under either contract; only the way of saying
+so differs — an argument to `register_blueprint` there, a line of config here.
+
+This app's **name is its blueprint's name**: podpack derives it, so
+`Blueprint("pdf", …)` in `views.py` is what decides the template namespace,
+the data directory and the `[apps.pdf]` config section. There is nothing to
+keep in step by hand.
+
+podpack is an **optional** import here — it is on no package index, and this
+package's first contract is to need no framework at all. Where it is absent,
+`podpack_pdf.site_app` is `None` and everything else works unchanged.
+
+---
+
+## How one package serves both
+
+|  | Plain Flask | podpack |
+| --- | --- | --- |
+| Discovery | `holdenweb.apps` entry point, or a direct import | import name in the site's `apps` list |
+| What is discovered | the `Blueprint` | `site_app: SiteApp` |
+| Mount point | the host's argument to `register_blueprint` | `[site.mounts] pdf`, defaulting to the app's own |
+| Setup hook | `pdf_blueprint.record_once` | `SiteApp.init` |
+| Page layout | `pdf/standalone.html`, shipped here | the site's `base.html` |
+| Configuration | `app.config["PODPACK_PDF_…"]` | `[apps.pdf]` in the site's TOML |
+| Navigation | the host's business | `nav=(Section(…),)` |
+
+The two coexist because the podpack half is a **config translator, not a second
+code path**. Both hosts settle the same two keys before the first request, and
+the views, forms and templates read only those.
+
+### Templates, and the layout ladder
+
+All templates ship namespaced under `templates/pdf/`, so nothing can collide
+with a host site's own template names. Every page extends `pdf/base.html`,
+which is one line: it extends whatever the host has said should wrap it.
+
+```
+a site's own templates/pdf/base.html   shadows this package's entirely
+podpack                                   "base.html" -- the site's chrome
+plain Flask                               pdf/standalone.html, shipped here
+```
+
+A host of either kind overrides any template here — including the whole page
+layout — by placing a file at the same path in its own template folder. Flask
+searches the application's templates before any blueprint's, so no configuration
+is involved. To wrap these pages in a plain-Flask site's furniture, that is a
+one-line file:
+
+```jinja
+{# templates/pdf/base.html in the host site #}
+{% extends "site-base.html" %}
+```
+
+or a single config key, set before the blueprint is registered:
+
+```python
+app.config["PODPACK_PDF_BASE_TEMPLATE"] = "site-base.html"
+```
+
+Standalone mode does **not** go looking for a `base.html` of its own accord. A
+host opts in, by one of those two routes. Adopting an unrelated layout
+automatically would reparent these pages onto blocks that may not match and
+context this package cannot supply — and a Jinja block that no ancestor renders
+is dropped in silence, so the failure would have no error message.
+
+For the same reason this package ships no template called `base.html`: Flask
+searches *every* blueprint's templates for a name the application does not
+supply, so one here would become the site-wide base for a podpack site and
+reparent every other installed app. A test pins that.
+
+**Which blocks a child may fill:** `content` and `title`. Both known layouts
+define them. `scripts` exists only in `standalone.html` and vanishes without
+warning under podpack.
+
+### A note on upload size
+
+A podpack site's `[limits] max_upload_bytes` becomes Flask's
+`MAX_CONTENT_LENGTH`. podpack's lab config sets it to 1 MiB, which will reject
+most real PDFs with a 413 before this app ever sees them. Raise it there.
+
+Separately, `max_pages` bounds the splitter: it builds its zip entirely in
+memory, one member per page, so an unbounded document is a way to exhaust the
+process rather than a document that cannot be read. Over the limit it declines
+with a message instead of trying.
+
+---
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+That runs the standalone suite: it registers the blueprint on a **bare** `Flask`
+app with no framework of any kind, pushes real reportlab-generated PDFs through
+both tools, and asserts that mounting at a non-default prefix, overriding the
+layout, and refusing an oversized document all work. If it passes, the package
+is genuinely self-contained.
+
+The podpack conformance suite installs the app into a real podpack site and
+checks the other contract. It needs no setting up:
+
+```bash
+uv sync
+uv run pytest
+```
+
+podpack is a **dev** dependency, sourced from its repository — never a real
+one, because an app must not pin the framework version of the site installing
+it. It used to be absent from the lock altogether, opted into by hand with
+`uv pip install -e ../podpack`, because podpack was a sibling working tree and
+any declaration would have made `uv lock` fail on a machine that had not
+checked it out. A git source needs a network rather than a neighbour, so that
+restriction is gone.
+
+To look at the pages without a host site of any kind:
+
+```bash
+uv run python devserver.py     # http://127.0.0.1:8459/pdf/
+```

podpack_pdf-0.2.2/README.md

@@ -0,0 +1,248 @@
+# podpack-pdf
+
+Two PDF utilities packaged as an installable Flask app:
+
+- **PDF Booklet Maker** — imposes an A4 document four-up onto A4 sheets so that
+  each group of eight pages forms a signature, returned as a zip of the odd and
+  even sides for duplex printing.
+- **PDF Page Splitter** — explodes a PDF into one file per page, returned as a
+  zip.
+
+Extracted from [holdenweb.com](https://holdenweb.com) with its history intact. It
+answers to two contracts and requires neither: a plain Flask blueprint, and a
+[podpack](https://github.com/holdenweb/podpack) app.
+
+## Install
+
+```bash
+uv add podpack-pdf
+```
+
+The distribution is `podpack-pdf`; the module, and the app's name everywhere podpack
+needs one, is `podpack_pdf`.
+
+---
+
+## As a plain Flask blueprint
+
+```python
+from flask import Flask
+from podpack_pdf import pdf_blueprint
+
+app = Flask(__name__)
+app.config["SECRET_KEY"] = "..."          # required: the forms are CSRF-protected
+app.register_blueprint(pdf_blueprint, url_prefix="/pdf/")
+```
+
+That yields three endpoints under the prefix you chose:
+
+| Route | Purpose |
+| --- | --- |
+| `/` | Index listing both tools |
+| `/booklet` | Upload a PDF, receive a zip of imposed odd/even sides |
+| `/pagezip` | Upload a PDF, receive a zip of one file per page |
+
+Here the mount point is yours: the blueprint is relocatable, so mount it at
+`/tools/pdf` or anywhere else and its internal links follow, because they are
+generated with `url_for`.
+
+### Discovery
+
+```toml
+[project.entry-points."holdenweb.apps"]
+pdf = "podpack_pdf:pdf_blueprint"
+```
+
+A host site can enumerate its installed apps rather than hard-coding imports:
+
+```python
+from importlib.metadata import entry_points
+
+for entry_point in entry_points(group="holdenweb.apps"):
+    app.register_blueprint(entry_point.load(), url_prefix=f"/{entry_point.name}/")
+```
+
+The entry point resolves to the **blueprint itself**, not to a bespoke
+`register()` callable, so the contract is expressed in Flask's own vocabulary.
+The entry-point *name* is only a mount hint for that loop; it is not the app's
+name.
+
+### Setup hooks
+
+Anything needed at registration time goes through Flask's own deferred-
+registration hook, which is the equivalent of Django's `AppConfig.ready`. This
+package uses it on itself, to settle its two config keys:
+
+```python
+@pdf_blueprint.record_once
+def _defaults(state):
+    state.app.config.setdefault("PODPACK_PDF_BASE_TEMPLATE", STANDALONE_LAYOUT)
+    state.app.config.setdefault("PODPACK_PDF_MAX_PAGES", DEFAULT_MAX_PAGES)
+```
+
+---
+
+## As a podpack app
+
+Add the package's **import name** to the site's config file and restart:
+
+```toml
+[site]
+apps = ["podpack_pdf"]
+
+[apps.pdf]
+max_pages = 200
+```
+
+There is no second step. podpack imports the package, reads its module-level
+`site_app`, and takes the mount point, the nav entry and the config namespace
+from it:
+
+```python
+site_app = SiteApp(
+    blueprint=pdf_blueprint,
+    url_prefix="/pdf",
+    nav=(Section("PDF tools", "pdf.root_page"),),
+    init=_init,
+)
+```
+
+The app's name is not declared: podpack derives it from the blueprint's own
+name, so `pdf` — the template namespace, the config section, the data
+directory — follows from `Blueprint("pdf", ...)` in views.py.
+
+`url_prefix` is what this app asks for, not what it is entitled to. A site that
+wants these pages somewhere else in its address space says so, and the nav entry
+follows without either side restating it — a `Section` names an endpoint, so
+podpack resolves it with `url_for` as the chrome renders:
+
+```toml
+[site.mounts]
+pdf = "/tools/pdf"
+```
+
+That lives under `[site]`, not in `[apps.pdf]`, because it is the site's
+policy rather than this package's configuration — `app_config()` returns only
+what this app is meant to read, and where it was mounted is not among it.
+
+So the mount point is the host's under either contract; only the way of saying
+so differs — an argument to `register_blueprint` there, a line of config here.
+
+This app's **name is its blueprint's name**: podpack derives it, so
+`Blueprint("pdf", …)` in `views.py` is what decides the template namespace,
+the data directory and the `[apps.pdf]` config section. There is nothing to
+keep in step by hand.
+
+podpack is an **optional** import here — it is on no package index, and this
+package's first contract is to need no framework at all. Where it is absent,
+`podpack_pdf.site_app` is `None` and everything else works unchanged.
+
+---
+
+## How one package serves both
+
+|  | Plain Flask | podpack |
+| --- | --- | --- |
+| Discovery | `holdenweb.apps` entry point, or a direct import | import name in the site's `apps` list |
+| What is discovered | the `Blueprint` | `site_app: SiteApp` |
+| Mount point | the host's argument to `register_blueprint` | `[site.mounts] pdf`, defaulting to the app's own |
+| Setup hook | `pdf_blueprint.record_once` | `SiteApp.init` |
+| Page layout | `pdf/standalone.html`, shipped here | the site's `base.html` |
+| Configuration | `app.config["PODPACK_PDF_…"]` | `[apps.pdf]` in the site's TOML |
+| Navigation | the host's business | `nav=(Section(…),)` |
+
+The two coexist because the podpack half is a **config translator, not a second
+code path**. Both hosts settle the same two keys before the first request, and
+the views, forms and templates read only those.
+
+### Templates, and the layout ladder
+
+All templates ship namespaced under `templates/pdf/`, so nothing can collide
+with a host site's own template names. Every page extends `pdf/base.html`,
+which is one line: it extends whatever the host has said should wrap it.
+
+```
+a site's own templates/pdf/base.html   shadows this package's entirely
+podpack                                   "base.html" -- the site's chrome
+plain Flask                               pdf/standalone.html, shipped here
+```
+
+A host of either kind overrides any template here — including the whole page
+layout — by placing a file at the same path in its own template folder. Flask
+searches the application's templates before any blueprint's, so no configuration
+is involved. To wrap these pages in a plain-Flask site's furniture, that is a
+one-line file:
+
+```jinja
+{# templates/pdf/base.html in the host site #}
+{% extends "site-base.html" %}
+```
+
+or a single config key, set before the blueprint is registered:
+
+```python
+app.config["PODPACK_PDF_BASE_TEMPLATE"] = "site-base.html"
+```
+
+Standalone mode does **not** go looking for a `base.html` of its own accord. A
+host opts in, by one of those two routes. Adopting an unrelated layout
+automatically would reparent these pages onto blocks that may not match and
+context this package cannot supply — and a Jinja block that no ancestor renders
+is dropped in silence, so the failure would have no error message.
+
+For the same reason this package ships no template called `base.html`: Flask
+searches *every* blueprint's templates for a name the application does not
+supply, so one here would become the site-wide base for a podpack site and
+reparent every other installed app. A test pins that.
+
+**Which blocks a child may fill:** `content` and `title`. Both known layouts
+define them. `scripts` exists only in `standalone.html` and vanishes without
+warning under podpack.
+
+### A note on upload size
+
+A podpack site's `[limits] max_upload_bytes` becomes Flask's
+`MAX_CONTENT_LENGTH`. podpack's lab config sets it to 1 MiB, which will reject
+most real PDFs with a 413 before this app ever sees them. Raise it there.
+
+Separately, `max_pages` bounds the splitter: it builds its zip entirely in
+memory, one member per page, so an unbounded document is a way to exhaust the
+process rather than a document that cannot be read. Over the limit it declines
+with a message instead of trying.
+
+---
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```
+
+That runs the standalone suite: it registers the blueprint on a **bare** `Flask`
+app with no framework of any kind, pushes real reportlab-generated PDFs through
+both tools, and asserts that mounting at a non-default prefix, overriding the
+layout, and refusing an oversized document all work. If it passes, the package
+is genuinely self-contained.
+
+The podpack conformance suite installs the app into a real podpack site and
+checks the other contract. It needs no setting up:
+
+```bash
+uv sync
+uv run pytest
+```
+
+podpack is a **dev** dependency, sourced from its repository — never a real
+one, because an app must not pin the framework version of the site installing
+it. It used to be absent from the lock altogether, opted into by hand with
+`uv pip install -e ../podpack`, because podpack was a sibling working tree and
+any declaration would have made `uv lock` fail on a machine that had not
+checked it out. A git source needs a network rather than a neighbour, so that
+restriction is gone.
+
+To look at the pages without a host site of any kind:
+
+```bash
+uv run python devserver.py     # http://127.0.0.1:8459/pdf/
+```

podpack_pdf-0.2.2/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "podpack-pdf"
+version = "0.2.2"
+description = "PDF booklet-imposition and page-splitting tools as an installable Flask app"
+readme = "README.md"
+requires-python = ">=3.12, <4.0"
+dependencies = [
+    "flask (>=2.3.3)",
+    "flask-wtf (>=1.2.1)",
+    "wtforms (>=3.0)",
+    "pdfrw (>=0.4)",
+    "reportlab (>=3.6.12)",
+]
+
+[[project.authors]]
+name = "Steve Holden"
+email = "steve@holdenweb.com"
+
+# Discovery hook for a site with no framework: it enumerates its installed apps
+# by iterating this group instead of hard-coding imports, and the value resolves
+# to the blueprint itself. The entry-point *name* is a mount hint -- the
+# documented consumer does url_prefix=f"/{entry_point.name}/" -- and is
+# deliberately not the app's name. podpack does not use entry points at all; it
+# imports `podpack_pdf` by name from the site's app list and reads `site_app`.
+[project.entry-points."holdenweb.apps"]
+pdf = "podpack_pdf:pdf_blueprint"
+
+[build-system]
+requires = [ "uv_build>=0.8.4,<0.9.0",]
+build-backend = "uv_build"
+
+[dependency-groups]
+# podpack is here rather than in `dependencies`, which is the important half:
+# an app must not pin the framework version of the site installing it. A
+# dependency group is dev-only metadata and constrains nobody downstream.
+#
+# It used to be absent from this file altogether, opted into by hand with
+# `uv pip install -e ../podpack`, because podpack was a sibling working tree
+# rather than a published package -- so any declaration would have bound at
+# *lock* time and made `uv lock` fail outright on a machine without that
+# checkout. A git source has no such requirement: it needs a network, not a
+# neighbour. `uv sync && uv run pytest` now works anywhere.
+dev = [ "pytest>=9.1.1", "mypy>=1.11", "types-WTForms", "types-reportlab", "podpack",]
+
+[tool.uv.sources]
+podpack = { git = "https://github.com/holdenweb/podpack.git" }
+
+# Type-checked like its sibling apps, and gated by ci.yml rather than left to
+# be run by hand -- a check nothing runs is a check that is already stale.
+[tool.mypy]
+files = ["src", "tests"]
+
+# Stubs exist for WTForms and reportlab and are installed above, so those are
+# checked for real. These two ship neither stubs nor a py.typed marker and have
+# no types-* package, so they are suppressed per module rather than globally --
+# a blanket ignore_missing_imports would also hide a genuinely missing import.
+[[tool.mypy.overrides]]
+module = ["flask_wtf.*", "pdfrw.*"]
+ignore_missing_imports = true

podpack_pdf-0.2.2/src/podpack_pdf/__init__.py

@@ -0,0 +1,89 @@
+"""PDF booklet-imposition and page-splitting tools as an installable Flask app.
+
+The package answers to two contracts and requires neither.
+
+**As a plain Flask blueprint**, for a site with no framework at all::
+
+    from podpack_pdf import pdf_blueprint
+
+    app.register_blueprint(pdf_blueprint, url_prefix="/pdf/")
+
+or let the site discover it through the ``holdenweb.apps`` entry-point group,
+whose value resolves to the blueprint itself. Where it is mounted is the site's
+decision, as it is in Django. Anything needed at registration time goes through
+``pdf_blueprint.record_once``, Flask's equivalent of Django's
+``AppConfig.ready`` -- no bespoke install hook is required.
+
+**As a podpack app**, by adding this package's import name to ``apps`` in the
+site's config file::
+
+    [site]
+    apps = ["podpack_pdf"]
+
+    [apps.pdf]
+    max_pages = 200
+
+podpack reads ``site_app`` below and takes the mount point, the nav entry and the
+config namespace from it.
+
+The two coexist because the podpack half is a config translator, not a second
+code path: both hosts settle ``PODPACK_PDF_BASE_TEMPLATE`` and ``PODPACK_PDF_MAX_PAGES``
+before the first request, and the views read only those. So the pages wear the
+site's own chrome under podpack, and a complete layout of their own without it.
+A host of either kind can also override any template in this package by shipping
+a file at the same path -- Flask searches the application's template folder
+before any blueprint's, so ``templates/pdf/base.html`` simply wins.
+"""
+
+from importlib.util import find_spec
+
+from .views import pdf_blueprint
+
+__all__ = ["pdf_blueprint", "site_app"]
+
+
+def _init(app):
+    """podpack's registration hook: adapt this app to the site installing it.
+
+    Runs before the blueprint is registered, so these defaults land ahead of the
+    blueprint's own and win. Under podpack ``base.html`` always resolves -- to
+    the site's chrome if it ships any, and to podpack's default if it does not.
+    """
+    from podpack import app_config
+
+    # `app_config` resolves the app from `request.blueprint` when called without
+    # a name; there is no request here, so name it. It needs an app context
+    # either way, and the registry pushes none.
+    with app.app_context():
+        settings = app_config("pdf")
+
+    app.config.setdefault("PODPACK_PDF_BASE_TEMPLATE", "base.html")
+    if "max_pages" in settings:
+        app.config["PODPACK_PDF_MAX_PAGES"] = settings["max_pages"]
+
+
+# podpack is optional and deliberately so: it is on no index, and this package's
+# first contract is to need no framework at all. `find_spec` rather than
+# `except ImportError` for the reason podpack's own registry gives for the same
+# choice -- a genuine failure *inside* podpack, a typo or a missing dependency,
+# must not be mistaken for its absence. Swallowing one would leave `site_app` as
+# None and produce a baffling "exposes no module-level site_app" from the
+# registry in place of the real traceback.
+if find_spec("podpack") is None:
+    site_app = None
+else:
+    from podpack import Section, SiteApp
+
+    site_app = SiteApp(
+        # This app's name is the blueprint's own -- podpack derives it, so the
+        # template namespace, the data directory and the `[apps.pdf]` config
+        # section all follow from `Blueprint("pdf", ...)` in views.py.
+        blueprint=pdf_blueprint,
+        # Where this app asks to be mounted. A site that wants it elsewhere
+        # says so in `[site.mounts]`, where its own policy lives -- this app
+        # never learns the answer. The nav entry below follows without either
+        # side restating it, because it names an endpoint rather than a path.
+        url_prefix="/pdf",
+        nav=(Section("PDF tools", "pdf.root_page"),),
+        init=_init,
+    )

podpack_pdf-0.2.2/src/podpack_pdf/booklet.py

@@ -0,0 +1,72 @@
+"""
+booklet.py: Produce an 8-page booklet from a single sheet of
+paper printed duplex.
+"""
+import io
+import sys
+from itertools import cycle
+from reportlab.pdfgen.canvas import Canvas
+from reportlab.lib.pagesizes import A4
+from pdfrw import PdfReader
+from pdfrw.buildxobj import pagexobj
+from pdfrw.toreportlab import makerl
+
+
+width, height = A4
+
+transforms = [
+	(0, 0.5, 0),
+	(0.5, 0.5, 0),
+	(1, 0.5, 180),
+	(0.5, 0.5, 180)
+]
+
+page_layouts = (8, 1, 4, 5), (2, 7, 6, 3)
+
+def make_booklet(in_doc, out_docs=None):
+    doc_pages = PdfReader(in_doc).pages
+    if out_docs is None:
+        out_docs = (io.BytesIO(), io.BytesIO())
+    elif len(out_docs) != 2:
+        raise ValueError("An out_docs argument to make_booklet did not have two elements")
+    # Create an odd an and even side imposed page stream, to which PDF
+    # content will be written.
+    imp_sides = []
+    for out_doc in out_docs:
+        imp_sides.append(imp_side := Canvas(out_doc))
+        imp_side.setPageSize(A4)
+    # Iterate over the pages in groups of eight, each group
+    # of original pages being the two sides of a signature.
+    for i in range(0, len(doc_pages), 8):
+        pages = doc_pages[i:i+8]
+        # Odd pages get sides 8, 1, 4 and 5
+        # Even pages get sides 2, 7, 6 and 3
+        for imp_side, page_numbers in zip(imp_sides, page_layouts):
+            page_data = [(k, t) for (k, t) in zip(page_numbers, transforms)]
+            # Each of the four pages in the imposed layout has its own
+            # transform: x-offset, y-offset and rotation angle. Offsets are
+            # multiples of the unit width and length, respectively, and the
+            # rotation angle is in degrees.
+            for page_number, (x, y, angle) in page_data:
+                # The final imposed page may not contain an exact multiple of
+                # four original pages, so we simply ignore requests for
+                # non-existent original pages, leaving them blank.
+                if page_number <= len(pages):
+                    orig_page = pages[page_number-1]
+                    orig_page = makerl(imp_side, pagexobj(orig_page))
+                    imp_side.saveState()
+                    imp_side.translate(x*width, y*height)
+                    imp_side.rotate(angle)
+                    imp_side.scale(0.5, 0.5)
+                    imp_side.doForm(orig_page)
+                    imp_side.restoreState()
+            imp_side.showPage()
+    # Save the generated PDFs
+    for imp_side in imp_sides:
+        imp_side.save()
+    # And return them to the caller
+    return out_docs
+
+if __name__ == '__main__':
+    with open("out_odd.pdf", "wb") as out_f1, open("out_even.pdf", "wb") as out_f2:
+        make_booklet(sys.argv[1], (out_f1, out_f2))

podpack_pdf-0.2.2/src/podpack_pdf/forms.py

@@ -0,0 +1,16 @@
+from flask_wtf import FlaskForm
+from wtforms import FileField, SubmitField, StringField
+from wtforms.validators import DataRequired
+
+
+class PDFBookletForm(FlaskForm):
+    file_details = FileField('file_details', validators=[DataRequired()])
+    submit = SubmitField("Generate Booklet")
+
+
+class PDFSplitterForm(FlaskForm):
+    file_details = FileField('file_details', validators=[DataRequired()])
+    file_prefix = StringField('file_prefix')
+    submit = SubmitField('Get Pages')
+
+

podpack_pdf-0.2.2/src/podpack_pdf/templates/pdf/base.html

@@ -0,0 +1,18 @@
+{# Every page in this app extends this file, and this file extends whatever the
+   host has said should wrap it:
+
+     a site's own templates/pdf/base.html   shadows this file entirely
+     podpack                                   "base.html" -- the site's chrome
+     plain Flask                               pdf/standalone.html, shipped here
+
+   The name arrives as `pdf_layout` from a context processor on the blueprint.
+   Jinja resolves `{% extends %}` against a variable perfectly well, but cannot
+   be handed a list of candidates to try -- `extends` compiles to
+   `environment.get_template`, not `get_or_select_template` -- so the choice is
+   made in Python, where it is also inspectable as the config key
+   PODPACK_PDF_BASE_TEMPLATE rather than being buried in a template.
+
+   Child templates may fill `content` and `title`, which both known layouts
+   define. A block no ancestor renders is dropped silently, so anything else is
+   layout-specific and will vanish without warning on the other one. #}
+{% extends pdf_layout %}

podpack_pdf-0.2.2/src/podpack_pdf/templates/pdf/booklet_form.html

@@ -0,0 +1,25 @@
+{% extends "pdf/base.html" %}
+
+{% block content %}
+<form method="post" enctype="multipart/form-data">
+  <fieldset>
+    {{ form.hidden_tag() }}
+    <legend>Make your own tiny booklets</legend>
+
+    <p>Use the Choose button to select a PDF file. Hit Submit and you will
+    receive a zip file containing two PDF files, one of odd sides and one of
+    even sides. Print the even sides, then run the same paper through to print
+    the odd sides.</p>
+    <p>The returned file is called "pages.zip", and holds "odd.pdf" and
+    "even.pdf" in a directory named "pdf".</p>
+
+    <div class="field">
+      {{ form.file_details(size=32) }}
+    </div>
+    <hr>
+    <div class="field">
+      {{ form.submit() }}
+    </div>
+  </fieldset>
+</form>
+{% endblock %}

podpack_pdf-0.2.2/src/podpack_pdf/templates/pdf/index.html

@@ -0,0 +1,12 @@
+{% extends "pdf/base.html" %}
+{% block content %}
+<h2>PDF Helper Utilities</h2>
+<ul>
+  {# Relative endpoints, so these links survive the blueprint being renamed as
+     well as being mounted somewhere other than /pdf/. #}
+  <li><a href="{{ url_for('.get_or_post_pagezip') }}"><strong>PDF Splitter</strong></a>
+      &mdash; split a PDF file into its individual pages</li>
+  <li><a href="{{ url_for('.get_or_post_booklet') }}"><strong>PDF Booklet Maker</strong></a>
+      &mdash; turn any PDF document into an A6 booklet</li>
+</ul>
+{% endblock %}

podpack_pdf-0.2.2/src/podpack_pdf/templates/pdf/pagesplit_form.html

@@ -0,0 +1,28 @@
+{% extends "pdf/base.html" %}
+
+{% block content %}
+<form method="post" enctype="multipart/form-data">
+  <fieldset>
+    {{ form.hidden_tag() }}
+    <legend>Split PDF documents into individual pages</legend>
+
+    <p>Use the Choose button to select the PDF file you want to split. Hit
+    Submit and you will receive a zip file containing a directory named after
+    your document that holds the individual pages, one per file.</p>
+    <p>By default the files will be called "page_001.pdf", "page_002.pdf" and so
+    on, but you can enter a prefix below to be used instead of "page".</p>
+
+    <div class="field">
+      {{ form.file_details(size=32) }}
+    </div>
+    <hr>
+    <div class="field">
+      <label for="file_prefix">Alternate prefix ...</label>
+      {{ form.file_prefix(size=32) }}
+    </div>
+    <div class="field">
+      {{ form.submit() }}
+    </div>
+  </fieldset>
+</form>
+{% endblock %}

podpack_pdf-0.2.2/src/podpack_pdf/templates/pdf/standalone.html

@@ -0,0 +1,41 @@
+{# The layout for a host that supplies none: a complete document, because with
+   no site to inherit from there is nothing else to be.
+
+   Under podpack this file is never reached -- the site's own base.html is. It
+   carries its own small stylesheet rather than loading a CSS framework, so that
+   the pages have no opinion to impose when they are rendered inside someone
+   else's chrome. The marker in the comment below is how the tests tell which of
+   the two layouts actually rendered. #}
+<!DOCTYPE html>
+<!-- podpack-pdf standalone layout -->
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>{% block title %}{{ title or "PDF tools" }}{% endblock %}</title>
+    {% block styles %}
+    <style>
+      body { max-width: 46rem; margin: 2rem auto; padding: 0 1rem;
+             font-family: system-ui, sans-serif; line-height: 1.5; }
+      fieldset { border: 1px solid #ccc; padding: 1rem 1.25rem; }
+      legend { font-weight: 600; padding: 0 .5rem; }
+      label { display: block; margin-bottom: .25rem; }
+      .field { margin: 1rem 0; }
+      input[type=submit] { padding: .4rem 1rem; }
+      .flashes { color: darkred; }
+    </style>
+    {% endblock %}
+  </head>
+  <body>
+    <h1>{{ title }}</h1>
+    {% with messages = get_flashed_messages() %}
+      {% if messages %}
+        <ul class="flashes">
+          {% for message in messages %}<li>{{ message }}</li>{% endfor %}
+        </ul>
+      {% endif %}
+    {% endwith %}
+    {% block content %}{% endblock %}
+    {% block scripts %}{% endblock %}
+  </body>
+</html>

podpack_pdf-0.2.2/src/podpack_pdf/views.py

@@ -0,0 +1,147 @@
+"""Views for the PDF helper utilities: booklet imposition and page splitting.
+
+Nothing here knows which contract installed it. Both hosts settle the same two
+config keys before the first request -- podpack through `SiteApp.init`, a plain
+Flask app through `record_once` below -- so the view code is written once.
+"""
+import os
+from io import BytesIO
+from logging import getLogger
+from zipfile import ZipFile
+
+from flask import (Blueprint, current_app, flash, render_template, request,
+                   send_file)
+import pdfrw
+from werkzeug.utils import secure_filename
+
+from .booklet import make_booklet
+from .forms import PDFBookletForm, PDFSplitterForm
+
+logger = getLogger(__name__)
+
+# The blueprint's name is also the app's name under podpack, which resolves an
+# app's data directory and config namespace from `request.blueprint`. Keep the
+# two in step; see the SiteApp in __init__.py.
+pdf_blueprint = Blueprint("pdf", __name__, template_folder="templates")
+
+# What these pages extend when no host has said otherwise. Namespaced, like every
+# other template here: Flask searches *every* blueprint's templates for a name
+# the application itself does not supply, so a `base.html` in this package would
+# silently become the site-wide base for a podpack site and reparent every other
+# installed app.
+STANDALONE_LAYOUT = "pdf/standalone.html"
+
+# The splitter builds its zip entirely in memory, one member per page, so an
+# unbounded document is a way to exhaust the process rather than a document we
+# cannot read. A site raises or lowers this with `[apps.pdf] max_pages`.
+DEFAULT_MAX_PAGES = 200
+
+
+@pdf_blueprint.record_once
+def _defaults(state):
+    """Settle this app's configuration at registration time.
+
+    Flask's own deferred-registration hook, which is this package's equivalent of
+    Django's ``AppConfig.ready``. ``setdefault`` rather than assignment because a
+    host may have decided already: podpack's ``SiteApp.init`` runs before this
+    one and points the layout at the site's own chrome.
+    """
+    state.app.config.setdefault("PODPACK_PDF_BASE_TEMPLATE", STANDALONE_LAYOUT)
+    state.app.config.setdefault("PODPACK_PDF_MAX_PAGES", DEFAULT_MAX_PAGES)
+
+
+@pdf_blueprint.context_processor
+def _layout():
+    """Tell ``pdf/base.html`` what to extend.
+
+    Registered on the blueprint, so the name is in scope for this app's templates
+    and for nothing else in the application.
+    """
+    return {"pdf_layout": current_app.config["PODPACK_PDF_BASE_TEMPLATE"]}
+
+
+@pdf_blueprint.route("/", methods=['GET'])
+def root_page():
+    return render_template("pdf/index.html", title="PDF Helpers")
+
+
+@pdf_blueprint.route("/booklet", methods=['GET', 'POST'])
+def get_or_post_booklet():
+    """
+    Post-design imposition of A6 booklets from A4 paper.
+
+    This page requests a file from the user, and returns a zipfile containing
+    its pages, each shrunk to 50% and imposed four-up on A4. This allows
+    creation of a signature from each eight original pages, four-up on an
+    even and an odd side.
+
+    The even and odd sides are then written into separate PDF files and
+    packed in a zipfile, which is delivered to the user as a downloaded.
+    """
+    form = PDFBookletForm()
+    logger.info("Booklet requested")
+    if form.validate_on_submit():
+        my_file = request.files['file_details']
+        try:
+            output_pdfs = make_booklet(my_file.stream)
+            outzip = BytesIO()
+            container = ZipFile(outzip, 'w')
+            for p_typ, pdf in zip(('odd', 'even'), output_pdfs):
+                container.writestr(f"pdf/{p_typ}.pdf",
+                                   pdf.getvalue())
+            container.close()
+            outzip.seek(0)
+            return send_file(outzip,
+                             mimetype="application/zip",
+                             as_attachment=True,
+                             download_name="pages.zip")
+        except Exception as e:
+            # Plain text, no markup: a host's layout may escape flashed messages
+            # -- podpack's does -- and the message interpolates an exception that
+            # can contain the client's own filename.
+            logger.exception("booklet imposition failed")
+            flash("I'm sorry, it seems I couldn't do that. Please report the "
+                  f"following message if it makes no sense to you: {e}")
+    return render_template('pdf/booklet_form.html', form=form, title="PDF Booklet Maker")
+
+
+@pdf_blueprint.route("/pagezip", methods=['GET', 'POST'])
+def get_or_post_pagezip():
+    form = PDFSplitterForm()
+    if form.validate_on_submit():
+        in_storage = request.files['file_details']
+        # The uploaded name becomes a directory inside the zip and the name of
+        # the download, so it is the client's string until sanitised.
+        infile_name = os.path.splitext(
+            secure_filename(in_storage.filename))[0] or "document"
+        file_prefix = request.form['file_prefix'] or 'page'
+        try:
+            inputpdf = pdfrw.PdfReader(fname=in_storage.stream)
+            max_pages = current_app.config["PODPACK_PDF_MAX_PAGES"]
+            if len(inputpdf.pages) > max_pages:
+                # A refusal rather than an error, and outside the loop, so the
+                # bare except below cannot turn it into "not a PDF".
+                flash(f"That document has {len(inputpdf.pages)} pages and this "
+                      f"tool splits at most {max_pages}.")
+                return render_template('pdf/pagesplit_form.html', form=form,
+                                       title="PDF Page Splitter")
+            outzip = BytesIO()
+            container = ZipFile(outzip, 'w')
+            for i, page in enumerate(inputpdf.pages):
+                output = pdfrw.PdfWriter()
+                file_name = f"{file_prefix}_{i+1:03}.pdf"
+                output.addpage(page)
+                outfile = BytesIO()
+                output.write(outfile)
+                container.writestr(f"{infile_name}/{file_name}",
+                                   outfile.getvalue())
+            container.close()
+            outzip.seek(0)
+            return send_file(outzip,
+                             mimetype="application/octet-stream",
+                             as_attachment=True,
+                             download_name=f"{infile_name}.pages.zip")
+        except Exception:
+            logger.exception("could not read the upload as a PDF")
+            flash("Could not open file as a PDF - please try again")
+    return render_template('pdf/pagesplit_form.html', form=form, title="PDF Page Splitter")