ibook2epub 2.0.0__tar.gz

ibook2epub-2.0.0/CHANGELOG.md

@@ -0,0 +1,130 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2026-08-26
+
+The exit codes changed incompatibly. Nothing else did, and the rest of this
+release is additions.
+
+### Breaking
+
+- **Every distinct failure now has its own exit code.** Five unrelated
+  conditions used to exit `2`: a mistyped flag, a source directory that is not
+  there, a missing optional extra, a missing external tool, and `--verify`
+  pointed at nothing. A scheduled run could not tell a misconfiguration it
+  should alert on from a transient state it should retry. `2` still means a bad
+  command line, because every tool means that by it; the rest moved to `3`
+  through `7`, with `130` for Ctrl-C. `epubconvert/exits.py` is the single
+  source for the table in the README, so the two cannot drift apart.
+
+### Added
+
+- `--name-by author-title` names books from their own `dc:title` and
+  `dc:creator` instead of the package directory. Apple names a package after
+  the title, so an exported shelf sorted by title and no amount of flags would
+  make it sort by author. The publisher's sort name is preferred, read from
+  either the EPUB2 `opf:file-as` attribute or the EPUB3 `<meta refines="#id"
+  property="file-as">` element — Apple's library is overwhelmingly the latter,
+  and reading only the attribute would have left 301 of 2,793 books filed under
+  their author's first name. Where a publisher gives the author and the
+  illustrator the same `id`, the first sort name wins, which is the author's.
+  `dc:creator` is used verbatim when no sort name exists, never rearranged.
+  Composes with `--portable-names`, which decides how a name is cleaned rather
+  than where it comes from.
+- Up to two contributors are named in full; beyond that the list collapses to
+  `Peralta, Samuel et al.`, which is what other library tools produce.
+  Publishers put a book's entire contributor list in one metadata field joined
+  with ` & `, and a twelve-author name is not a usable filename even when it
+  fits inside the byte limit.
+- Neither half of a name can squeeze the other out. Clamping used to trim the
+  end of the composed `Author - Title`, which is the title: an anthology came
+  out as `... & Wecks, Erik - The Time Travel.epub`, keeping fourteen
+  contributors and losing "Chronicles". A book whose `dc:title` is its whole
+  jacket blurb keeps its author prefix and has the title trimmed instead,
+  because a shelf that stops sorting by author defeats the point of the policy.
+- An author made only of characters that sanitising removes (`..`, `?`) is
+  treated as absent rather than leaving a separator with nothing in front of
+  it.
+- A trimmed title backs off to the last whole word, so a shortened name reads
+  as deliberate rather than damaged: `...watch television` rather than
+  `...watch television a`.
+- Stable collision names. Under `--on-collision suffix`, a book that has to
+  share a name is marked with a digest of its own `dc:identifier` rather than
+  its position in the colliding group. Adding a book that sorts earlier no
+  longer renames every later member. Books whose identifier is missing, a
+  placeholder, or shared with another book keep the positional suffix and the
+  run says so.
+- Orphan reporting. An archive that no book in the library claims is now named
+  by `--list`, carries `"source": null` in the JSON, and is counted in the run
+  summary. Nothing is deleted; the gap was that nothing would say either.
+- Copy-through for books that need no conversion. Already-valid `.epub` files
+  and `.pdf` files are copied verbatim through the same
+  temporary-then-replace path everything else uses, so a library holding both
+  Apple's package folders and books that arrived already zipped exports whole.
+  `--no-copy-through` turns it off.
+- The run reports how many books were named from a package document that
+  declared no creator, and how many kept their folder name because the document
+  declared no title. A shelf that comes out half-named says so, rather than
+  leaving it to be noticed afterwards.
+
+### Fixed
+
+- `dc:identifier` was read as the first such element in document order, where
+  the spec names the canonical one through the `unique-identifier` IDREF on
+  `<package>`. Publishers commonly list a retail ASIN or ISBN first, so the
+  wrong value was returned for 798 of 2,805 books in a real library. Nothing
+  consumed the field yet, so nothing had broken.
+- Structural checks in the source walk ran only where `st_flags` exists, so a
+  package that could not be checked for undownloaded files skipped the rest of
+  its checks on Linux.
+- The two write paths in `_decide` had drifted into being byte-identical and
+  are now one.
+- Roughly forty correctness, security, performance and readability findings
+  from two full review passes, applied by rule at every call site of the rule
+  rather than at the one site that surfaced them.
+
+### Changed
+
+- `assign_names` returns an `Assignment` record rather than a bare triple, so a
+  book that loses a collision can say which file holds the name and what its
+  own identifier is.
+- The PyPI publish workflow was hardened and pinned.
+- Installation instructions cover the published distribution rather than only
+  an editable checkout, and say what the `portable` extra actually buys: it is
+  needed for `--portable-names romanize` and for nothing else.
+- CodeTour walkthroughs were added for the conversion and planning paths.
+
+## [1.2.1] - 2026-08-24
+
+### Fixed
+
+- Issues raised by review of the Tier 3 work.
+- Findings from an automated review pass.
+
+## [1.2.0] - 2026-08-23
+
+### Added
+
+- `-p` / `--portable-names` with `strip` and `romanize` modes, and
+  identity-based deduplication so two spellings of one book export once.
+- Validation, source inspection and `--list`.
+- Reproducible archives, and a clean exit on interrupt.
+
+### Changed
+
+- `click` replaced with `argparse`, removing the last runtime dependency.
+- Python 3.10 is the minimum; development moved to 3.14.
+- Relicensed to MIT.
+
+### Fixed
+
+- Filename-length and output-overlap bugs.
+- Nested content that looked like Apple bookkeeping was being dropped.
+
+[2.0.0]: https://github.com/raeq/ibook2epub/compare/v1.2.1...v2.0.0
+[1.2.1]: https://github.com/raeq/ibook2epub/compare/v1.2.0...v1.2.1
+[1.2.0]: https://github.com/raeq/ibook2epub/releases/tag/v1.2.0

ibook2epub-2.0.0/CONTRIBUTING.md

@@ -0,0 +1,98 @@
+# Contributing
+
+## Running the checks
+
+CI runs five steps. Run all five before pushing; the first four are fast.
+
+```bash
+ruff check epubconvert tests
+ruff format --check epubconvert tests
+mypy
+pylint epubconvert tests
+pytest
+```
+
+`pylint` has no score threshold. It exits non-zero on any message, which is
+deliberate: it used to run with `--fail-under=8.0` against a tree scoring
+10.00, so a regression to 8.1 merged green.
+
+## Two invariants worth knowing before you change anything
+
+### The output directory is the only record of completed work
+
+There is no state file. Whether a book has been converted is decided by
+globbing `*.epub` in the output directory and recomputing each name's identity.
+Everything follows from that:
+
+- A name the glob cannot match means the book is re-converted on every run,
+  for ever. A title of `?` once produced a file called `epub`.
+- Anything that lands in the output directory is recorded as finished and no
+  rerun retries it. A truncated archive is permanent.
+
+`archive.assert_is_a_book` is the choke point. It runs before every
+`partial.replace()` and refuses an archive that lacks `META-INF/container.xml`
+or holds no members. Every silent-success defect this project has had ended
+there: an unreadable subdirectory that contributed nothing, a package deleted
+between planning and writing, a symlinked directory holding somebody else's
+files. In each case the run wrote a valid zip, reported an export, and recorded
+a book that was wrong or missing. `--validate` is the thorough check and it is
+off by default, so the cheap unconditional assertion is what actually holds the
+line.
+
+If you add a path that writes into the output directory, it goes through that
+function.
+
+### A name from a book is input, not fact
+
+`container.xml` names the package document. The package document names every
+manifest item. The package directory names its own entries. All of those are
+chosen by whoever produced or sideloaded the book, and all of them get joined
+onto a real directory.
+
+`epubconvert/contained.py` holds the rule, and a test asserts nothing
+reimplements it. This is not a style preference. The rule was written three
+times: a traversal through a manifest href was fixed at the one call site that
+had it, the archive writer later grew a weaker version of its own, and the
+readers of `container.xml`, the package document and `encryption.xml` grew
+none — so a book could still point its own package document at any file the
+user could read, months after the "same" bug was closed.
+
+Names shown to a user go through `epubconvert/display.py`, which escapes
+control characters. A package name carrying `ESC[2K` can otherwise erase the
+line reporting it.
+
+### Exit codes are a contract
+
+`epubconvert/exits.py` holds every code with its meaning, and the README table
+is generated from `MEANINGS`, so the two cannot drift. A new failure mode gets
+a new code rather than reusing a near-enough one: five conditions once shared
+`2`, and a scheduled run could not tell a typo from a missing dependency.
+
+Environment checks — does this directory exist, is that tool installed — go in
+`run.main`, not in `parse_args`. `parser.error` always exits 2, so validating
+the environment there is what collapsed them in the first place.
+
+## Measure before tuning
+
+Two of this project's performance assumptions were wrong, and both had been
+sitting in the code unquestioned:
+
+- `COMPRESS_LEVEL = 9` had never been applied. `ZipFile(compresslevel=)` is
+  consulted only when `open()` builds its own `ZipInfo`, and this code hands it
+  a prebuilt one, so every member had always deflated at zlib's default.
+  Applying the constant would have cost 3.2× the CPU for 0.6% less size.
+- `--validate` was assumed to double the read work, because it re-inflates
+  every member. It costs about 7%: the archive is still in the page cache, and
+  inflating is far cheaper than deflating.
+
+Neither was discoverable by reading. If you change a tuning constant, a worker
+count, or a compression choice, record the measurement in a comment next to it
+and say what you measured on. The constants in `archive.py` and
+`convert.default_workers` carry theirs.
+
+## Style
+
+Docstrings explain *why*, and often cite the defect that motivated a decision.
+That is intentional and worth keeping. When you move code, re-read the
+docstrings that moved with it — four of them were left pointing at functions
+that had relocated.

ibook2epub-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-2026 Richard Quinn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ibook2epub-2.0.0/MANIFEST.in

@@ -0,0 +1,16 @@
+# setuptools auto-includes test*.py by a legacy rule, which picks up
+# tests/test_*.py and silently leaves out conftest.py and __init__.py. Every
+# fixture lives in conftest, so a packager running the suite from the sdist
+# got collection errors rather than tests.
+recursive-include tests *.py
+
+include CONTRIBUTING.md
+include CHANGELOG.md
+
+# Review artefacts and editor tooling are working files, not part of the
+# distribution. Named explicitly so a new one does not start shipping.
+exclude hai-sdlc-review-*.md
+exclude uv.lock
+prune .tours
+prune .claude
+prune .github