update: LTS bits (closes #30)

.cspell.json

@@ -4,18 +4,25 @@
   "words": [
     "arjndr",
     "attrbox",
+    "Autobuild",
     "begert",
+    "codeql",
     "docopt",
     "isinstance",
     "isrange",
     "lukasbindreiter",
     "Metaist",
+    "mypy",
     "pdfmerge",
     "pdfs",
     "pdoc",
+    "pypa",
     "pypdf",
+    "pypi",
     "pyproject",
+    "pyright",
     "rangify",
+    "setuptools",
     "unrotated",
     "venv"
   ]

.gitignore

@@ -17,7 +17,7 @@ _seed.py
 __pycache__
 
 # test
-.coverage*
+.coverage
 .mypy_cache
 .pytest_cache
 .ruff_cache

CONTRIBUTING.md

@@ -1,30 +1,89 @@
-## Setting up a dev environment
+# Contributing
+
+## Local Development
 
 ```bash
-git clone <url>
+# get the code
+git clone git@github.com:metaist/pdfmerge.git
 cd pdfmerge
-python -m .venv --prompt pdfmerge
-source .venv/bin/activate
-pip install -e ".[dev]"
 
+# create a virtual environment
+python -m venv .venv --prompt pdfmerge
+. .venv/bin/activate
+pip install --upgrade pip
+
+# install dependencies and dev tools
+pip install -e ".[dev]"
 pnpm install -g cspell
 ```
 
-## Making a release
+As you work on the code, you should periodically run:
+
+```bash
+pdm lint  # for type checks
+pdm test  # for unit tests
+```
+
+This repo generally tries to maintain type-correctness (via `mypy` and `pyright`) and complete unit test coverage.
+
+## Making a Release
+
+Checkout `prod`:
 
 ```bash
 git checkout prod
 git merge --no-ff --no-edit main
-# update __init__.py version
-# update changelog.md
-pdm all
+```
+
+Update top-most `__init__.py`:
+
+```python
+__version__ = "X.0.1"
+```
+
+Update `CHANGELOG.md`:
+
+Sections order is: `Fixed`, `Changed`, `Added`, `Deprecated`, `Removed`, `Security`.
+
+```markdown
+---
 
-git commit -m "release: $VER"
-git tag "$VER"
+[X.0.1]: https://github.com/metaist/pdfmerge/compare/X.0.0...X.0.1
+
+## [X.0.1] - XXXX-XX-XXT00:00:00Z
+
+**Fixed**
+
+**Changed**
+
+**Added**
+
+**Deprecated**
+
+**Removed**
+
+**Security**
+```
+
+###
+
+```bash
+export VER="X.0.1"
+
+# update docs
+pdm docs
+
+# check build
+pip install -e .
+
+# commit and push tags
+git commit -am "release: $VER"
+git tag $VER
 git push
 git push --tags
-
 git checkout main
 git merge --no-ff --no-edit prod
 git push
 ```
+
+[Create the release on GitHub](https://github.com/metaist/pdfmerge/releases/new). The `pypi.yaml` workflow will attempt to publish it to PyPI.

README.md

@@ -1,16 +1,14 @@
-# pdfmerge
-
-_Command-line utility for merging, splicing, and rotating PDF documents._
-
-[![Build Status](https://img.shields.io/github/actions/workflow/status/metaist/pdfmerge/.github/workflows/ci.yaml?branch=main&style=for-the-badge)](https://github.com/metaist/pdfmerge/actions)
-[![pdfmerge on PyPI](https://img.shields.io/pypi/v/pdfmerge.svg?color=blue&style=for-the-badge)](https://pypi.org/project/pdfmerge)
-[![Supported Python versions](https://img.shields.io/pypi/pyversions/pdfmerge?style=for-the-badge)](https://pypi.org/project/pdfmerge)
-
-[Changelog] - [Issues] - [Documentation]
-
-[changelog]: https://github.com/metaist/pdfmerge/blob/main/CHANGELOG.md
-[issues]: https://github.com/metaist/pdfmerge/issues
-[documentation]: https://metaist.github.io/pdfmerge/
+# pdfmerge: CLI for merging, splicing, and rotating PDFs
+
+<p align="center">
+  <a href="https://metaist.github.io/pdfmerge/"><img alt="pdfmerge" width="200" src="https://raw.githubusercontent.com/metaist/pdfmerge/main/staple-the-squirrel.png" /></a><br />
+  <em>Staple the Squirrel</em>
+</p>
+<p align="center">
+  <a href="https://github.com/metaist/pdfmerge/actions/workflows/ci.yaml"><img alt="Build" src="https://img.shields.io/github/actions/workflow/status/metaist/pdfmerge/.github/workflows/ci.yaml?branch=main&logo=github"/></a>
+  <a href="https://pypi.org/project/pdfmerge"><img alt="PyPI" src="https://img.shields.io/pypi/v/pdfmerge.svg?color=blue" /></a>
+  <a href="https://pypi.org/project/pdfmerge"><img alt="Supported Python Versions" src="https://img.shields.io/pypi/pyversions/pdfmerge" /></a>
+</p>
 
 ## Why?
 
@@ -24,7 +22,10 @@ python -m pip install pdfmerge
 
 ## Usage
 
-    $ pdfmerge [-h] [--version] [-o FILE|--output FILE] [-p PASSWORD|--password PASSWORD] PATH[RULE[, RULE ...]] [PATH[RULE, ...]] ...]
+    $ pdfmerge [-h] [--version]
+      [-o FILE|--output FILE]
+      [-p PASSWORD|--password PASSWORD]
+      PATH[RULE[, RULE ...]] [[PATH[RULE, ...]] ...]
 
 - `-o`, `--output` output file (default: `output.pdf`).
 - `-p`, '--password` password for encrypted files (default: empty string).
@@ -45,7 +46,7 @@ python -m pip install pdfmerge
 
 This example illustrates several features:
 
-- specifying an output file (must not be any of the input files)
+- specifying an output file
 - merging multiple files, some more than once
 - splicing parts of file using indices (1-based; negatives allowed)
 - including the same page multiple times
@@ -65,14 +66,4 @@ pdfmerge(["pdf-1.pdf", "pdf-2.pdf[2>]"], "output.pdf")
 
 ## License
 
-[MIT License](https://github.com/metaist/pypdf/blob/main/LICENSE.md)
-
-[ci-image]: https://travis-ci.org/metaist/pdfmerge.png?branch=master
-[ci-status]: http://travis-ci.org/metaist/pdfmerge
-[gh-code]: https://github.com/metaist/pdfmerge/zipball/master
-[gh-issues]: https://github.com/metaist/pdfmerge/issues
-[gh-issues-all]: https://github.com/metaist/pdfmerge/issues/search?q=
-[gh-pdfmerge]: https://github.com/metaist/pdfmerge/blob/master/pdfmerge.py
-[gh-setup]: https://github.com/metaist/pdfmerge/blob/master/releases/pdfmerge-latest-setup.exe
-[osi-mit]: http://opensource.org/licenses/MIT
-[pypdf]: https://pypi.python.org/pypi/pyPdf
+[MIT License](https://github.com/metaist/pdfmerge/blob/main/LICENSE.md)

docs/index.html

@@ -23,17 +23,25 @@ <h1 class="title">Package <code>pdfmerge</code></h1>
 </header>
 <section id="section-intro">
 <p>Command-line utility for merging, splicing, and rotating PDF documents.</p>
-<p><a href="https://github.com/metaist/pdfmerge/actions"><img alt="Build Status" src="https://img.shields.io/github/actions/workflow/status/metaist/pdfmerge/.github/workflows/ci.yaml?branch=main&amp;style=for-the-badge"></a>
-<a href="https://pypi.org/project/pdfmerge"><img alt="pdfmerge on PyPI" src="https://img.shields.io/pypi/v/pdfmerge.svg?color=blue&amp;style=for-the-badge"></a>
-<a href="https://pypi.org/project/pdfmerge"><img alt="Supported Python versions" src="https://img.shields.io/pypi/pyversions/pdfmerge?style=for-the-badge"></a></p>
-<p><a href="https://github.com/metaist/pdfmerge/blob/main/CHANGELOG.md">Changelog</a> - <a href="https://github.com/metaist/pdfmerge/issues">Issues</a> - <a href="https://metaist.github.io/pdfmerge/">Documentation</a></p>
+<p align="center">
+<a href="https://metaist.github.io/pdfmerge/"><img alt="pdfmerge" width="200" src="https://raw.githubusercontent.com/metaist/pdfmerge/main/staple-the-squirrel.png" /></a><br />
+<em>Staple the Squirrel</em>
+</p>
+<p align="center">
+<a href="https://github.com/metaist/pdfmerge/actions/workflows/ci.yaml"><img alt="Build" src="https://img.shields.io/github/actions/workflow/status/metaist/pdfmerge/.github/workflows/ci.yaml?branch=main&logo=github"/></a>
+<a href="https://pypi.org/project/pdfmerge"><img alt="PyPI" src="https://img.shields.io/pypi/v/pdfmerge.svg?color=blue" /></a>
+<a href="https://pypi.org/project/pdfmerge"><img alt="Supported Python Versions" src="https://img.shields.io/pypi/pyversions/pdfmerge" /></a>
+</p>
 <h2 id="why">Why?</h2>
 <p>I find myself merging bits of different PDFs fairly regularly and really wanted a simple CLI way to do it.</p>
 <h2 id="install">Install</h2>
 <pre><code class="language-bash">python -m pip install pdfmerge
 </code></pre>
 <h2 id="usage">Usage</h2>
-<pre><code>$ pdfmerge [-h] [--version] [-o FILE|--output FILE] [-p PASSWORD|--password PASSWORD] PATH[RULE[, RULE ...]] [PATH[RULE, ...]] ...]
+<pre><code>$ pdfmerge [-h] [--version]
+  [-o FILE|--output FILE]
+  [-p PASSWORD|--password PASSWORD]
+  PATH[RULE[, RULE ...]] [[PATH[RULE, ...]] ...]
 </code></pre>
 <ul>
 <li><code>-o</code>, <code>--output</code> output file (default: <code>output.pdf</code>).</li>
@@ -54,7 +62,7 @@ <h2 id="command-line-example">Command-line Example</h2>
 </code></pre>
 <p>This example illustrates several features:</p>
 <ul>
-<li>specifying an output file (must not be any of the input files)</li>
+<li>specifying an output file</li>
 <li>merging multiple files, some more than once</li>
 <li>splicing parts of file using indices (1-based; negatives allowed)</li>
 <li>including the same page multiple times</li>
@@ -68,15 +76,15 @@ <h1 id="python-module-usage">Python Module Usage</h1>
 pdfmerge([&quot;pdf-1.pdf&quot;, &quot;pdf-2.pdf[2&gt;]&quot;], &quot;output.pdf&quot;)
 </code></pre>
 <h2 id="license">License</h2>
-<p><a href="https://github.com/metaist/pypdf/blob/main/LICENSE.md">MIT License</a></p>
+<p><a href="https://github.com/metaist/pdfmerge/blob/main/LICENSE.md">MIT License</a></p>
 <details class="source">
 <summary>
 <span>Expand source code</span>
 </summary>
 <pre><code class="python">&#34;&#34;&#34;Command-line utility for merging, splicing, and rotating PDF documents.
 
 .. include:: ../../README.md
-   :start-line: 4
+   :start-line: 2
 &#34;&#34;&#34;
 
 # native
@@ -261,7 +269,7 @@ <h2 id="license">License</h2>
     Returns:
         PdfFileWriter: the writer object
     &#34;&#34;&#34;
-    reader = PdfReader(item.path.open(&#34;rb&#34;), strict=True)
+    reader = PdfReader(item.path.open(&#34;rb&#34;))
     if reader.is_encrypted:
         if password is None:
             print(f&#34;Reading encrypted PDF &lt;{item.path}&gt;&#34;)

pyproject.toml

@@ -22,7 +22,7 @@ Changelog = "https://github.com/metaist/pdfmerge/blob/main/CHANGELOG.md"
 
 [project]
 name = "pdfmerge"
-description = "Command-line utility for merging, splicing, and rotating PDF documents."
+description = "CLI for merging, splicing, and rotating PDFs."
 keywords = ["pdf", "merge", "split", "cli"]
 
 dynamic = ["version"]
@@ -39,6 +39,7 @@ optional-dependencies = { dev = [
   "mypy",
   "pdm",
   "pdoc3",
+  "pyright",
   "pytest-cov",
   "pytest",
   "ruff",
@@ -69,6 +70,7 @@ classifiers = [
 black = { shell = "black ." }
 ruff = { shell = "ruff ." }
 cspell = { shell = "cspell --gitignore '**/*.{py,txt,md,markdown}'" }
+pyright = { shell = "pyright src test" }
 
 mypy = { shell = """\
   mypy \
@@ -100,6 +102,6 @@ docs = { shell = """\
   touch docs/.nojekyll
 """ }
 
-lint = { composite = ["black", "ruff", "cspell", "mypy"] }
+lint = { composite = ["black", "ruff", "cspell", "pyright", "mypy"] }
 dev = { composite = ["lint", "test"] }
 all = { composite = ["lint", "test", "docs"] }

src/pdfmerge/__init__.py

@@ -1,7 +1,7 @@
 """Command-line utility for merging, splicing, and rotating PDF documents.
 
 .. include:: ../../README.md
-   :start-line: 4
+   :start-line: 2
 """
 
 # native