ufo-tdkit-tools 0.2.0__tar.gz

ufo_tdkit_tools-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/

ufo_tdkit_tools-0.2.0/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-09-22
+
+First release published on PyPI.
+
+### Fixed
+
+- **Preserve mode dropped the hints of every production-renamed glyph** ([#1](https://github.com/typedev/ufo-tdkit-tools/issues/1)). The per-glyph charstring merge matches by glyph name, but the two halves of the compile used different name sets: the ufo2ft shell was built with production names (`uni0100`) while the `tx -t1` + `makeotf` donor ignores `public.postscriptNames` and keeps source names (`Amacron`). Every renamed glyph failed the `glyph_name not in hinted_cs` test and was silently skipped — on DIN 2014 that is 488 of 829 glyphs per face, shipping OTFs with 32.5 % of glyphs hinted against 99.3 % for the same sources built with the external autohinter. The shell is now compiled with `useProductionNames=False` so both sides share the UFO's source namespace, and renaming is deferred to after the merge, delegated to ufo2ft's own `PostProcessor` (same code path a plain `compileOTF` runs: lib mapping, `uniXXXX` derivation, collision suffixes, invalid-character stripping) which also performs the `cffsubr` subroutinization. New e2e regression test `test_production_renamed_glyphs_keep_hints`.
+- **Merged charstrings reported a bogus advance width in the CFF.** A Type 2 charstring may open with a width operand encoded as `width - Private.nominalWidthX`, and the merge copies charstrings between two fonts with unrelated Private dicts (here: shell `nominalWidthX=500 / defaultWidthX=600`, donor `0 / 0`). Every transferred glyph therefore decoded to a wrong CFF width — `tx -dump -6` reported `1100 width` for a 600-unit glyph — while `hmtx` stayed correct, so layout engines were unaffected but CFF-level consumers (`tx`, subsetters, CFF→CFF2 conversion) were not. The new `_split_width_prefix` helper strips the donor's width prefix and splices the shell's own onto the donor's body. This defect was previously masked by the name bug (it only affected the third of glyphs that were merged at all). New e2e regression test `test_transferred_charstrings_keep_their_width`.
+- **The autohint gate was per font, not per glyph** ([#1](https://github.com/typedev/ufo-tdkit-tools/issues/1), second defect). `detect_font_source` returns a source as soon as **one** glyph has hints, and the pipeline only called the autohinter when the whole font came up empty. A partially hinted master — the normal shape of a FontLab source, where hints are authored on base forms and not on composites — was therefore treated as fully hinted, and every unhinted glyph went into the OTF unhinted (`source=public_ps glyphs=829 with_hints=408 autohinted=False`). `process_font` gained an `autohint` argument: `"fill"` (new default) autohints exactly the drawable glyphs the chosen source does not cover and keeps the authored hints of the rest; `"all"` discards authored hints and re-hints everything; `"off"` restores the old leave-it-alone behaviour and turns "no hints anywhere" into a failure instead of silently hinting the whole font. The autohinter runs with `glyphList` restricted to the gap glyphs and `explicitGlyphs` set, so its own `maxSegments` heuristic cannot skip complex glyphs.
+- **Silent hint loss now surfaces in the log.** The merge warns when the shell and donor name sets disagree on more than 5 % of glyphs (with a sample of the unmatched names), and when hinted donor glyphs have no shell counterpart. `stats` gained `donor_hinted` and `name_mismatch` alongside `hints_transferred` / `total_glyphs`.
+- **Preserve mode could fail to compile UFOs with features (platform-dependent).** `_compile_makeotf_hinted` passed the UFO's `features.fea` to the donor compile via `-ff`; on some platforms `makeotfexe` aborts with `std::system_error` whenever `-ff` is present — even for an empty file (reproduced deterministically on Fedora 44 / AFDKO 4.0.3, and reported intermittently under parallel load on AFDKO 5.0.0; not reproduced on 5.0.0 here across ~250 serial and oversubscribed-parallel invocations). When the abort fires, `_compile_makeotf_hinted` returns `False`, so `compile_otf_preserve_optimized` returns `False` and `process_font` reports `success=False` / `"OTF compilation failed"` — a hard failure, not a silent unhinted output. (A caller that catches that `False` and falls back to a plain ufo2ft compile is what turns it into silently unhinted output downstream.) The donor font exists only as a source of hinted charstrings and PrivateDict hint parameters — its GSUB/GPOS are discarded by the per-glyph merge — so the donor is now compiled with **no features file at all** (wrapper auto-discovery is moot: the tx-emitted `.ps` sits alone in a temp directory). Output features are unaffected: they come from the ufo2ft shell. Removing `-ff` also skips donor feature compilation that the merge discards anyway (~4% of the makeotf step on a 600-glyph / 42 KB feature file here). New e2e regression test compiles a hinted UFO **with** features and asserts the hints actually reach the output CFF (`test_hints_survive_with_features_present`).
+
+### Added
+
+- **Legacy `kern` table synthesis** (`compilation.legacy_kern`, also re-exported as `ufo_tdkit_tools.add_legacy_kern`). Microsoft Word and other Office rendering paths read kerning from the old-style `kern` table rather than from GPOS, so fonts built by ufo2ft/fontmake lose kerning there. `add_legacy_kern(ttf)` flattens the font's GPOS `kern` feature into a format-0 `kern` table and rewrites the binary so that only `kern` changes (GPOS is flattened on a throwaway lazy `TTFont`; every other table is written back verbatim and `head.modified` is preserved — `head.checkSumAdjustment` is the one unavoidable side effect). Pairs resolve first-wins in feature order, values are clamped to int16, and the table splits across several subtables past the uint16 `nPairs` limit. Contextual lookups inside the `kern` feature (kerning exceptions) have no format-0 equivalent and are skipped with a log line instead of being mistaken for pair positioning — reading them as `PairPos` used to raise `AttributeError: PairSet` and abort the whole flatten. Depends only on fontTools, so it works without the `compilation` extra.
+- **`ProcessResult` build counters.** `autohinted_count` (glyphs the autohinter filled in), plus `otf_glyphs_hinted` / `otf_glyphs_total` taken from the compiler's `stats` — what actually reached the binary, which is what a build-level regression guard should assert on. The CLI prints them per file (`... -> otf 823/829`).
+- **`--autohint {fill,all,off}` CLI flag** on `optimize-otf`, forwarded to `process_font`.
+- **`ps_hints.batch.glyphs_missing_source(font, source)`** — names of drawable glyphs (contours or components) with no hints in a source; `export_all_from_processed` gained an optional `names` filter.
+- **Multi-entry `hintSetList` extraction.** `cff_hints.py` now parses CFF charstrings via `afdko.otfautohint.otfFont.convertT2ToGlyphData` and emits one `autohint.v2` hint set per `hintmask` event in the source, anchored on the canonical UFO point per AFDKO's `addUfoHints` algorithm. Hint substitution is preserved through OTF → UFO → OTF on glyphs whose substitution points lie inside contours.
+- **Counter-mask preservation.** `cntrmask` operators round-trip via `hstem3` / `vstem3` triplets in the `stems` array, mirroring AFDKO's `addUfoMask` triplet encoding.
+- **`StdHW` / `StdVW` round-trip.** UFO has no dedicated field for these scalars, so extraction reorders `postscriptStemSnapH` / `postscriptStemSnapV` to put the CFF `StdHW` / `StdVW` value at index 0; ufo2ft picks `StdHW = StemSnapH[0]` at compile time.
+- **FEA post-processing.** `_unify_feature_blocks` collapses `fontFeatures.unparse` output (one block per `(feature, script, language)` tuple) into one block per tag with internal `script` / `language` scoping. `_inline_aalt_lookups` rewrites `lookup NAME;` references inside `aalt` to inline `sub` statements (the Adobe FEA spec rejects lookup references in `aalt`; `addfeatures` errors out otherwise). `_strip_lookup_noise` and `_strip_empty_gdef` clean up artefacts. On a representative font this reduces feature-block count from 116 to one per tag.
+
+### Changed
+
+- **`process_font` autohints by default** (`autohint="fill"`). Previously the autohinter only ran when the font had no hints at all; now it also fills per-glyph gaps. Callers that want the old behaviour pass `autohint="off"` — with the caveat that "no hints anywhere" then fails instead of falling back to the autohinter.
+- **`_resolve_source` returns `None` for a binary input whose extraction yielded no hints** (it used to return `AUTOHINT_V2` unconditionally); the pipeline treats that as "the autohinter supplies everything", which is what it did before by a separate branch.
+- **Compilation now uses the `makeotf` wrapper** instead of the deprecated `makeotfexe` binary, which is a stub on AFDKO releases scheduling its removal after March 2027 (returns exit 1 with a deprecation message and produces no output). `_compile_makeotf_hinted` resolves and subprocess-runs `makeotf`, sets `PATH` so the wrapper finds its own `tx` / `addfeatures` / `spot`, and asserts the output file exists after a returncode-0 to guard against future stub regressions.
+- **`afdko` is capped at `<6`** in the `extraction` and `compilation` extras. AFDKO 6 drops the bare `tx` / `makeotf` command wrappers in favour of `afdko tx` / `afdko makeotf`, which the compiler does not call yet.
+- **Packaging**: `__version__` is read from the installed package metadata (`pyproject.toml` is the single source), the license is declared as an SPDX expression, and Python 3.13 is listed and tested in CI.
+- **API rename**: `makeotfexe_path` → `makeotf_path` on `compile_otf_preserve`, `compile_otf_preserve_optimized`, `preserve_compile`, `preserve_compile_batch`. Auto-detection now resolves `makeotf` via `shutil.which`.
+
+### Removed
+
+- **`compilation.generate_goadb` and `compilation.prepare_processedglyphs`** (and their private helpers). Neither was called anywhere: the per-glyph merge matches by name, so the donor glyph order no longer needs a GlyphOrderAndAliasDB, and the compiler reads hints from default-layer `autohint.v2` only — a processedglyphs layer built for `tx` would carry decomposed outlines whose hint point references no longer match.
+- The in-house `HintExtractingDecompiler` (subclass of `SimpleT2Decompiler`) is replaced by `convertT2ToGlyphData` from `afdko.otfautohint`, which already parses stems, `startmasks`, per-pathElement masks, and counter masks correctly.
+
+## [0.1.0] - 2026-04-03
+
+### Added
+
+- Initial release: extracted from ufo-widgets-gtk4 and TDKit
+- `constants` module: shared PS hint constants and outline hash computation
+- `extraction` module: binary font (OTF/TTF/WOFF/WOFF2) to UFO conversion with CFF hint extraction and feature cleanup
+- `ps_hints` module: PS hint parsing, optimization, layer conversion, and structural validation
+- `compilation` module: UFO to OTF compilation with PS hint preservation (preserve-optimized mode)
+
+[Unreleased]: https://github.com/typedev/ufo-tdkit-tools/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/typedev/ufo-tdkit-tools/releases/tag/v0.2.0

ufo_tdkit_tools-0.2.0/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Support. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2024 TypeDev
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

ufo_tdkit_tools-0.2.0/Makefile

@@ -0,0 +1,155 @@
+# Release plumbing for ufo-tdkit-tools.
+#
+# `make publish` is the only irreversible target in here, and PyPI is unusually
+# unforgiving about it: a version number can be yanked but never re-uploaded, so a
+# wrong artefact is permanent under that number. Everything before the upload is
+# therefore a gate, and each one exists because it is cheap here and expensive after.
+#
+# Credentials are never stored in this file, and never asked for until the moment they
+# are used: UV_PUBLISH_TOKEN if set, else ~/.pypirc, else a hidden prompt. Better still,
+# publish from CI with Trusted Publishing and keep no token anywhere -- see the bottom.
+
+# bash, not /bin/sh -- and not incidentally: the hidden token prompt below uses
+# `read -rs -p`, and dash (which /bin/sh is on Debian and Ubuntu) supports neither -s
+# nor -p. Under dash the read silently yields an empty string, so the prompt would look
+# like it worked and then abort. Removing this line breaks `make publish` on the systems
+# most likely to run it.
+SHELL := bash
+.SHELLFLAGS := -eu -o pipefail -c
+
+NAME    := ufo-tdkit-tools
+VERSION := $(shell sed -n 's/^version = "\(.*\)"/\1/p' pyproject.toml | head -1)
+TAG     := v$(VERSION)
+
+.DEFAULT_GOAL := help
+.PHONY: help test lint check build verify clean guard-clean guard-tag guard-unpublished publish-test publish release-checklist
+
+help: ## Show this list
+	@grep -hE '^[a-z][a-zA-Z0-9_-]*:.*?## ' $(MAKEFILE_LIST) \
+	  | awk -F':.*?## ' '{printf "  \033[1m%-20s\033[0m %s\n", $$1, $$2}'
+	@echo
+	@echo "  $(NAME) $(VERSION)  (tag $(TAG))"
+
+test: ## Run the full suite
+	uv run pytest -q
+
+lint: ## Ruff
+	uv run ruff check src/ tests/
+
+check: test lint ## Suite + lint
+
+clean: ## Remove built artefacts
+	rm -rf dist build *.egg-info
+
+build: clean ## Build the sdist and the wheel from a clean dist/
+	uv build
+	@ls -1 dist/
+
+# --- gates -------------------------------------------------------------------------
+
+guard-clean: ## Fail unless the working tree is clean and matches origin/main
+	@test -z "$$(git status --porcelain)" \
+	  || { echo "error: working tree is dirty; publishing it would ship something no commit records"; exit 1; }
+	@test "$$(git rev-parse --abbrev-ref HEAD)" = "main" \
+	  || { echo "error: not on main (on $$(git rev-parse --abbrev-ref HEAD))"; exit 1; }
+	@git fetch --quiet origin main
+	@test "$$(git rev-parse HEAD)" = "$$(git rev-parse origin/main)" \
+	  || { echo "error: HEAD and origin/main differ; push or pull first"; exit 1; }
+
+guard-tag: ## Fail unless tag v<version> exists and points at HEAD
+	@git rev-parse -q --verify "refs/tags/$(TAG)" >/dev/null \
+	  || { echo "error: tag $(TAG) does not exist. Cut the release first (make release-checklist), then publish."; exit 1; }
+	@test "$$(git rev-parse "$(TAG)^{commit}")" = "$$(git rev-parse HEAD)" \
+	  || { echo "error: $(TAG) does not point at HEAD -- you would publish code the tag does not describe"; exit 1; }
+
+guard-unpublished: ## Fail if this version is already on PyPI
+	@code=$$(curl -sS -o /dev/null -w '%{http_code}' "https://pypi.org/pypi/$(NAME)/$(VERSION)/json" || echo 000); \
+	if [ "$$code" = "200" ]; then \
+	  echo "error: $(NAME) $(VERSION) is already on PyPI. A version can be yanked but never re-uploaded -- bump the version."; exit 1; \
+	elif [ "$$code" != "404" ]; then \
+	  echo "error: could not reach PyPI to check (HTTP $$code); refusing to guess"; exit 1; \
+	fi
+
+verify: build ## Check the metadata renders, and that the built wheel actually runs
+	uvx twine check --strict dist/*
+	@tmp=$$(mktemp -d); \
+	uv venv --quiet "$$tmp/venv"; \
+	VIRTUAL_ENV="$$tmp/venv" uv pip install --quiet dist/*.whl; \
+	got=$$("$$tmp/venv/bin/ufo-tdkit-tools" --version); \
+	bare=$$("$$tmp/venv/bin/python" -c "import ufo_tdkit_tools.compilation, ufo_tdkit_tools.ps_hints; print('ok')" 2>&1); \
+	rm -rf "$$tmp"; \
+	test "$$got" = "ufo-tdkit-tools $(VERSION)" \
+	  || { echo "error: installed wheel reports '$$got', expected 'ufo-tdkit-tools $(VERSION)'"; exit 1; }; \
+	test "$$bare" = "ok" \
+	  || { echo "error: bare install (no extras) cannot import the package: $$bare"; exit 1; }
+	@echo "ok: wheel installs clean, the entry point runs, and a bare install imports"
+
+# --- publishing --------------------------------------------------------------------
+
+# How the token reaches `uv publish`, in order of preference:
+#   1. UV_PUBLISH_TOKEN already in the environment (CI);
+#   2. ~/.pypirc, which uv reads by itself;
+#   3. a hidden prompt, right before the upload and nowhere else.
+#
+# The prompt is the default for a person at a terminal, because the alternatives leak:
+# `export` puts the token in the shell history and then in the environment of every
+# later command, and `--token` on a command line is visible in `ps` to anyone on the
+# box. Passing it as a per-command environment variable is neither. It is read with
+# `read -rs`, so a paste shows nothing at all .
+define upload
+@if [ -n "$${UV_PUBLISH_TOKEN:-}" ] || [ -f "$$HOME/.pypirc" ]; then \
+  uv publish $(1) dist/*; \
+else \
+  if [ ! -t 0 ]; then \
+    echo "error: no UV_PUBLISH_TOKEN, no ~/.pypirc, and no terminal to ask on."; \
+    echo "       In CI, set UV_PUBLISH_TOKEN -- or better, use Trusted Publishing (see below)."; \
+    exit 1; \
+  fi; \
+  read -rs -p "  API token (input is hidden -- paste and press Enter): " token; echo; \
+  test -n "$$token" || { echo "  aborted: empty token"; exit 1; }; \
+  case "$$token" in pypi-*) ;; *) echo "  note: that does not start with 'pypi-'; tokens do. Continuing anyway." ;; esac; \
+  UV_PUBLISH_TOKEN="$$token" uv publish $(1) dist/*; \
+fi
+endef
+
+publish-test: verify ## Upload to TestPyPI (safe rehearsal; asks for a TestPyPI token)
+	$(call upload,--publish-url https://test.pypi.org/legacy/)
+	@echo
+	@echo "Installed check:"
+	@echo "  uv tool install --index-url https://test.pypi.org/simple/ \\"
+	@echo "    --extra-index-url https://pypi.org/simple/ $(NAME)==$(VERSION)"
+
+publish: guard-clean guard-tag guard-unpublished check verify ## Upload to PyPI (IRREVERSIBLE)
+	@echo
+	@echo "  About to publish $(NAME) $(VERSION) to PyPI from $(TAG)."
+	@echo "  This cannot be undone: the version can be yanked, never replaced."
+	@echo
+	@if [ "$${CONFIRM:-}" != "yes" ]; then \
+	  read -r -p "  Type the version to confirm: " answer; \
+	  test "$$answer" = "$(VERSION)" || { echo "  aborted"; exit 1; }; \
+	fi
+	$(call upload,)
+	@echo
+	@echo "Published. Remaining steps that PyPI does not do for you:"
+	@echo "  - gh release create $(TAG) ... (its publish.yml run will fail on the existing version; expected)"
+	@echo "  - tell TDKit the new version range"
+
+release-checklist: ## Print the order of operations, without doing anything
+	@echo "  1. move [Unreleased] into [X.Y.Z] - <today> in CHANGELOG.md, add the compare link"
+	@echo "  2. bump version in pyproject.toml, then: uv lock"
+	@echo "  3. make check verify"
+	@echo "  4. git commit -am 'chore(release): X.Y.Z' && git tag -a vX.Y.Z -m vX.Y.Z"
+	@echo "  5. git push origin main --follow-tags"
+	@echo "  6. make publish-test   # optional rehearsal on TestPyPI"
+	@echo "  7. gh release create vX.Y.Z --title vX.Y.Z --notes-file <CHANGELOG section> --verify-tag --latest"
+	@echo "     -> publishing the Release runs .github/workflows/publish.yml, which uploads to PyPI"
+	@echo "  8. tell TDKit the new version range"
+	@echo
+	@echo "  'make publish' is the manual fallback for step 7's upload only; if you use it,"
+	@echo "  the later Release will re-run publish.yml, which then fails on the existing version."
+
+# Trusted Publishing (the default path, see .github/workflows/publish.yml)
+# ------------------------------------------------------------------------------------
+# One-time setup: https://pypi.org/manage/account/publishing/ -> add a pending publisher
+# (project ufo-tdkit-tools, owner typedev, repo ufo-tdkit-tools, workflow publish.yml,
+# environment pypi), and create the `pypi` environment in the GitHub repo settings.

ufo_tdkit_tools-0.2.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.5
+Name: ufo-tdkit-tools
+Version: 0.2.0
+Summary: PS hints extraction, optimization, and preserve-mode compilation for UFO fonts
+Project-URL: Homepage, https://github.com/typedev/ufo-tdkit-tools
+Project-URL: Repository, https://github.com/typedev/ufo-tdkit-tools
+Project-URL: Issues, https://github.com/typedev/ufo-tdkit-tools/issues
+Project-URL: Changelog, https://github.com/typedev/ufo-tdkit-tools/blob/main/CHANGELOG.md
+Author-email: Alexander Lubovenko <lubovenko@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: cff,compilation,font,hints,otf,postscript,ttf,typedev,typography,ufo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics :: Editors :: Vector-Based
+Classifier: Topic :: Text Processing :: Fonts
+Requires-Python: >=3.10
+Requires-Dist: fonttools>=4.38.0
+Provides-Extra: all
+Requires-Dist: afdko<6,>=5.0.0; extra == 'all'
+Requires-Dist: cffsubr; extra == 'all'
+Requires-Dist: defcon; extra == 'all'
+Requires-Dist: fontparts>=0.10.0; extra == 'all'
+Requires-Dist: typing-extensions>=4.15.0; extra == 'all'
+Requires-Dist: ufo-extractor>=0.8.1; extra == 'all'
+Requires-Dist: ufo2ft>=3.0.0; extra == 'all'
+Provides-Extra: compilation
+Requires-Dist: afdko<6,>=5.0.0; extra == 'compilation'
+Requires-Dist: cffsubr; extra == 'compilation'
+Requires-Dist: defcon; extra == 'compilation'
+Requires-Dist: fontparts>=0.10.0; extra == 'compilation'
+Requires-Dist: ufo2ft>=3.0.0; extra == 'compilation'
+Provides-Extra: extraction
+Requires-Dist: afdko<6,>=5.0.0; extra == 'extraction'
+Requires-Dist: defcon; extra == 'extraction'
+Requires-Dist: fontparts>=0.10.0; extra == 'extraction'
+Requires-Dist: typing-extensions>=4.15.0; extra == 'extraction'
+Requires-Dist: ufo-extractor>=0.8.1; extra == 'extraction'
+Description-Content-Type: text/markdown
+
+# ufo-tdkit-tools
+
+[![PyPI](https://img.shields.io/pypi/v/ufo-tdkit-tools)](https://pypi.org/project/ufo-tdkit-tools/)
+[![CI](https://github.com/typedev/ufo-tdkit-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/typedev/ufo-tdkit-tools/actions/workflows/ci.yml)
+
+PS hints extraction, optimization, and preserve-mode compilation for UFO fonts.
+
+## Features
+
+- **extraction** -- Convert binary fonts (OTF/TTF/WOFF/WOFF2) to UFO with full PS hint preservation (multi-entry `hintSetList`, counter triplets `hstem3`/`vstem3`, font-level Private dict including `StdHW`/`StdVW`) and FEA post-processing (one feature block per tag, inlined `aalt` for spec compliance).
+- **ps_hints** -- Parse, optimize, analyze, and validate PostScript hints in UFO fonts; move hints between processedglyphs / glyph lib / default layers.
+- **compilation** -- Compile UFO back to OTF preserving PS hints (via AFDKO `makeotf` + per-glyph charstring merge, then production glyph names + `cffsubr` subroutinization). Parallel batch via `ProcessPoolExecutor`.
+
+## Installation
+
+```bash
+pip install ufo-tdkit-tools                    # core (constants, ps_hints parser)
+pip install ufo-tdkit-tools[extraction]        # + binary font conversion
+pip install ufo-tdkit-tools[compilation]       # + OTF compilation with hints
+pip install ufo-tdkit-tools[all]               # everything
+```
+
+The `extraction` and `compilation` extras pull in [AFDKO](https://github.com/adobe-type-tools/afdko) (`>=5,<6`), whose wheels ship the `tx` and `makeotf` executables the compiler runs — nothing needs to be installed separately.
+
+## Quick start
+
+The simplest path is the `process_font` pipeline — any input (binary or
+UFO, hinted or not) becomes a hinted OTF + a clean UFO:
+
+```python
+from ufo_tdkit_tools import process_font
+
+result = process_font(
+    "input.otf",          # OTF / TTF / WOFF / WOFF2 / UFO
+    "out.otf",
+    "out.ufo",
+    hint_source="auto",   # priority: processed > v2 > public_ps
+    autohint="fill",      # "fill" | "all" | "off"
+    optimize=False,       # set True to run the ps_hints optimizer
+)
+assert result.success
+print(result.glyphs_with_hints, "/", result.glyphs_total,
+      "autohinted=", result.autohinted_count,
+      "in otf=", result.otf_glyphs_hinted)
+```
+
+Glyphs the chosen source does not hint are autohinted individually with
+`afdko.otfautohint` — a partially hinted master (base forms hinted,
+composites not) comes out fully hinted, with the authored hints kept.
+`autohint="all"` re-hints everything instead, `autohint="off"` leaves the
+gaps alone.
+
+For the lower-level entry points (`extraction.convert_binary_to_ufo`,
+`compilation.compile_otf_preserve_optimized`, the `ps_hints` parser /
+optimizer / validator / batch wrappers), see [`docs/API.md`](docs/API.md).
+
+### Legacy `kern` table for Word
+
+Modern build tools emit kerning only as GPOS, which Microsoft Word ignores.
+`add_legacy_kern` regenerates the old-style `kern` table from the font's own
+GPOS `kern` feature, rewriting the binary so that nothing but `kern` changes:
+
+```python
+from ufo_tdkit_tools import add_legacy_kern
+
+pairs = add_legacy_kern("Sans-Regular.ttf")   # 0 if the font has no GPOS kerning
+```
+
+It needs only fontTools — no extras required.
+
+## Command line
+
+Installing the package (`uv sync` / `pip install`) provides the
+`ufo-tdkit-tools` console script (also runnable as
+`python -m ufo_tdkit_tools`). It wraps `process_font` for batch builds:
+
+```bash
+# Re-hint/optimize a batch of OTFs in place (temp UFO created & discarded)
+ufo-tdkit-tools optimize-otf --in-place *.otf
+
+# Or write fresh <stem>.otf + <stem>.ufo pairs into a directory
+ufo-tdkit-tools optimize-otf -o build/ Sans-Regular.otf Sans-Bold.otf
+
+# Skip the ps_hints optimizer (autohint + compile only)
+ufo-tdkit-tools optimize-otf --in-place --no-optimize *.otf
+
+# Keep only the authored hints, never call the autohinter
+ufo-tdkit-tools optimize-otf -o build/ --autohint off Src.ufo
+```
+
+Every run prints one machine-parseable summary line and exits non-zero if
+any input failed — convenient inside a build log:
+
+```
+optimized=36 autohinted=0 failed=0
+```
+
+`--in-place` only rewrites `.otf` inputs (atomically, so a mid-pipeline
+failure never corrupts the source). UFO and other binary inputs use `-o DIR`.
+
+## Round-trip fidelity
+
+OTF → UFO → OTF preserves declared `hstem`/`vstem` positions and widths byte-for-byte, hint substitution between drawing operations, counter-mask grouping, and font-level Private dict scalars. The one structural exception is hint substitution that fires *between* subpaths (a `hintmask` immediately before a `moveto`, common on disconnected glyphs like `i`, `j`, dieresis-bearing letters): the `autohint.v2` format has no anchor for these and AFDKO's own autohint produces the same flattening.
+
+Metadata (OS/2, `head`, `name`) also round-trips: `fsType`, weight/width class, vendor ID, Unicode/code-page ranges, PANOSE, typo/win/hhea metrics, sub/superscript and strikeout, `head.macStyle`/`head.flags`, and all name records. The `OS/2.fsSelection` flags `USE_TYPO_METRICS` (bit 7), `WWS` (bit 8) and `OBLIQUE` (bit 9) are restored during extraction — `ufo-extractor` (≤ 0.8.1) drops them, so they are re-read straight from the source `OS/2` table.
+
+## License
+
+Apache-2.0