anchorsfactory 0.2.0__tar.gz

anchorsfactory-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Alexander Lubovenko
+
+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.

anchorsfactory-0.2.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+recursive-include anchorsfactory/rules *.af
+recursive-include docs *.md

anchorsfactory-0.2.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: anchorsfactory
+Version: 0.2.0
+Summary: Rule-driven anchor placement for UFO fonts
+Author-email: Alexander Lubovenko <lubovenko@me.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/typedev/AnchorsFactory
+Project-URL: Repository, https://github.com/typedev/AnchorsFactory
+Project-URL: Issues, https://github.com/typedev/AnchorsFactory/issues
+Keywords: ufo,font,fonts,anchors,diacritics,marks,typography,type-design,fonttools,fontparts,opentype
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+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 :: Text Processing :: Fonts
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fontParts
+Requires-Dist: fontTools
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+# AnchorsFactory
+
+Rule-driven **anchor placement** for [UFO](https://unifiedfontobject.org/)
+fonts. You describe, in a compact text file, where anchors should sit on your
+glyphs; AnchorsFactory computes the coordinates from each glyph's own geometry
+and writes the anchors into the font.
+
+It does the *pre-marking* step of accent handling: place `top`/`bottom`/`_top`/…
+anchors consistently across hundreds of glyphs, so a tool like
+[GlyphConstruction](https://github.com/typemytype/GlyphConstruction) can then
+assemble composite glyphs by snapping mark anchors to base anchors.
+
+## Install
+
+```bash
+pip install anchorsfactory          # once published
+# or, from a checkout:
+pip install -e .
+```
+
+Requires Python 3.10+, `fontParts` and `fontTools`.
+
+## Quick start
+
+```bash
+# place anchors using the bundled default ruleset, save to font_anchored.ufo
+anchorsfactory MyFont.ufo --rules default
+
+# your own rules, overwrite in place, with a backup of existing anchors
+anchorsfactory MyFont.ufo --rules my-rules.af --in-place --backup-dir backups/
+
+# a whole folder of UFOs
+anchorsfactory masters/ --rules default
+```
+
+By default the source UFO is never overwritten — output goes to
+`*_anchored.ufo` unless you pass `--in-place`.
+
+## The rule language
+
+Rules are stacked: define reusable **labels**, then **mark** glyphs with them,
+mixing labels and one-off anchors. An anchor is a name and a parenthesised
+`X Y` placement.
+
+```
+# a label
+@ = top (box.center capHeight), bottom (box.center 0)
+
+# apply it, by name / unicode / range
+A = @, ogonek (outline.right 0)
+U+0410..U+044F = @            # all Russian Cyrillic
+U+0413 += desc (outline.right 0)   # Г also gets a descender anchor
+```
+
+- **X** is `frame.position`: `width.*` (advance), `box.*` (bounding box) or
+  `outline.*` (the contour at height Y, with `.first`/`.last` to pick a stem).
+- **Y** is a number, a font metric (`capHeight`, `xHeight`, `ascender`, …), or a
+  reference glyph (`$H`, `$H.bottom`, `$H*5/6`).
+- Selectors: name, `U+XXXX`, range `U+A..U+B`, glob `*.sc`, category `{Lu}`.
+- `=` replace · `+=` add · `-=` remove; `!extends default` inherits a ruleset.
+
+Full reference: **[docs/anchor-rules.md](docs/anchor-rules.md)**.
+
+### Presets and migration
+
+Bundled rulesets `default` and `default-italics` are usable by name in
+`--rules` or `!extends`. Old `.txt` rule files (see `examples/`) convert to the
+new syntax — verified lossless:
+
+```bash
+anchorsfactory-convert examples/default-anchors-list.txt -o my-rules.af
+```
+
+## Library API
+
+```python
+from anchorsfactory import process_ufo, load_document, apply_document
+
+process_ufo("MyFont.ufo", "default")          # high-level: open, apply, save
+
+from fontParts.world import OpenFont
+font = OpenFont("MyFont.ufo")
+apply_document(font, load_document("my-rules.af"))
+font.save()
+```
+
+## Development
+
+```bash
+make venv      # create .venv, install the package (editable) + dev deps, via uv
+make test      # run the test suite
+make build     # build sdist + wheel into dist/
+```
+
+## License
+
+See [LICENSE](LICENSE).

anchorsfactory-0.2.0/README.md

@@ -0,0 +1,97 @@
+# AnchorsFactory
+
+Rule-driven **anchor placement** for [UFO](https://unifiedfontobject.org/)
+fonts. You describe, in a compact text file, where anchors should sit on your
+glyphs; AnchorsFactory computes the coordinates from each glyph's own geometry
+and writes the anchors into the font.
+
+It does the *pre-marking* step of accent handling: place `top`/`bottom`/`_top`/…
+anchors consistently across hundreds of glyphs, so a tool like
+[GlyphConstruction](https://github.com/typemytype/GlyphConstruction) can then
+assemble composite glyphs by snapping mark anchors to base anchors.
+
+## Install
+
+```bash
+pip install anchorsfactory          # once published
+# or, from a checkout:
+pip install -e .
+```
+
+Requires Python 3.10+, `fontParts` and `fontTools`.
+
+## Quick start
+
+```bash
+# place anchors using the bundled default ruleset, save to font_anchored.ufo
+anchorsfactory MyFont.ufo --rules default
+
+# your own rules, overwrite in place, with a backup of existing anchors
+anchorsfactory MyFont.ufo --rules my-rules.af --in-place --backup-dir backups/
+
+# a whole folder of UFOs
+anchorsfactory masters/ --rules default
+```
+
+By default the source UFO is never overwritten — output goes to
+`*_anchored.ufo` unless you pass `--in-place`.
+
+## The rule language
+
+Rules are stacked: define reusable **labels**, then **mark** glyphs with them,
+mixing labels and one-off anchors. An anchor is a name and a parenthesised
+`X Y` placement.
+
+```
+# a label
+@ = top (box.center capHeight), bottom (box.center 0)
+
+# apply it, by name / unicode / range
+A = @, ogonek (outline.right 0)
+U+0410..U+044F = @            # all Russian Cyrillic
+U+0413 += desc (outline.right 0)   # Г also gets a descender anchor
+```
+
+- **X** is `frame.position`: `width.*` (advance), `box.*` (bounding box) or
+  `outline.*` (the contour at height Y, with `.first`/`.last` to pick a stem).
+- **Y** is a number, a font metric (`capHeight`, `xHeight`, `ascender`, …), or a
+  reference glyph (`$H`, `$H.bottom`, `$H*5/6`).
+- Selectors: name, `U+XXXX`, range `U+A..U+B`, glob `*.sc`, category `{Lu}`.
+- `=` replace · `+=` add · `-=` remove; `!extends default` inherits a ruleset.
+
+Full reference: **[docs/anchor-rules.md](docs/anchor-rules.md)**.
+
+### Presets and migration
+
+Bundled rulesets `default` and `default-italics` are usable by name in
+`--rules` or `!extends`. Old `.txt` rule files (see `examples/`) convert to the
+new syntax — verified lossless:
+
+```bash
+anchorsfactory-convert examples/default-anchors-list.txt -o my-rules.af
+```
+
+## Library API
+
+```python
+from anchorsfactory import process_ufo, load_document, apply_document
+
+process_ufo("MyFont.ufo", "default")          # high-level: open, apply, save
+
+from fontParts.world import OpenFont
+font = OpenFont("MyFont.ufo")
+apply_document(font, load_document("my-rules.af"))
+font.save()
+```
+
+## Development
+
+```bash
+make venv      # create .venv, install the package (editable) + dev deps, via uv
+make test      # run the test suite
+make build     # build sdist + wheel into dist/
+```
+
+## License
+
+See [LICENSE](LICENSE).

anchorsfactory-0.2.0/anchorsfactory/__init__.py

@@ -0,0 +1,36 @@
+"""AnchorsFactory — rule-driven anchor placement for UFO fonts."""
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("anchorsfactory")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0+unknown"
+
+from .apply import apply_document, accumulate, validate_document
+from .parser import parse_document, parse_file, ParseError
+from .dsl import parse_dsl, parse_dsl_file, DSLError
+from .convert import convert_file, render_document, verify_conversion
+from .presets import list_presets, preset_text, is_preset
+from .runner import process_ufo, load_document
+
+__all__ = [
+    "__version__",
+    "apply_document",
+    "accumulate",
+    "validate_document",
+    "parse_document",
+    "parse_file",
+    "ParseError",
+    "parse_dsl",
+    "parse_dsl_file",
+    "DSLError",
+    "convert_file",
+    "render_document",
+    "verify_conversion",
+    "list_presets",
+    "preset_text",
+    "is_preset",
+    "process_ufo",
+    "load_document",
+]

anchorsfactory-0.2.0/anchorsfactory/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

anchorsfactory-0.2.0/anchorsfactory/apply.py

@@ -0,0 +1,137 @@
+"""Apply a parsed :class:`Document` to a font: place the anchors.
+
+Resolution follows the accumulation model: rules are scanned in file order and
+every rule whose selector matches a glyph mutates that glyph's anchor list —
+``=`` replaces it, ``+=`` appends. This single path serves both front-ends
+(the legacy parser emits all-``REPLACE`` rules, so each glyph matched once
+behaves exactly as before).
+
+Coordinate maths is delegated to :mod:`anchorsfactory.geometry`.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import logging
+import unicodedata
+
+from .geometry import resolve
+from .model import (
+    Document, Op, LabelRef,
+    GlyphName, Unicode, UnicodeRange, Glob, Category,
+)
+
+log = logging.getLogger(__name__)
+
+
+def _resolve_items(items, labels, _seen=()):
+    """Expand LabelRefs to concrete AnchorSpecs against *labels* (late binding)."""
+    specs = []
+    for it in items:
+        if isinstance(it, LabelRef):
+            if it.name in _seen:
+                raise ValueError(f"label cycle through {it.name}")
+            if it.name not in labels:
+                raise ValueError(f"undefined label {it.name}")
+            specs.extend(_resolve_items(labels[it.name], labels, _seen + (it.name,)))
+        else:
+            specs.append(it)
+    return specs
+
+
+def _remove_targets(items, labels):
+    """Names to drop for a REMOVE rule: bare names plus the names a label defines."""
+    names = set()
+    for it in items:
+        if isinstance(it, LabelRef):
+            names.update(s.name for s in _resolve_items([it], labels))
+        else:
+            names.add(it)
+    return names
+
+
+def _matches(selector, name: str, unicodes) -> bool:
+    if isinstance(selector, GlyphName):
+        return name == selector.name
+    if isinstance(selector, Unicode):
+        return selector.codepoint in unicodes
+    if isinstance(selector, UnicodeRange):
+        return any(selector.start <= u <= selector.end for u in unicodes)
+    if isinstance(selector, Glob):
+        return fnmatch.fnmatchcase(name, selector.pattern)
+    if isinstance(selector, Category):
+        return any(unicodedata.category(chr(u)).startswith(selector.value) for u in unicodes)
+    raise TypeError(f"unknown selector {selector!r}")
+
+
+def validate_document(doc: Document) -> list[str]:
+    """Pre-flight check (font-independent): every @label reference resolves.
+
+    Returns a list of human-readable problems (empty = ok). Catches typo'd
+    label names up front instead of at apply time, glyph by glyph.
+    """
+    problems = []
+    for lname, items in doc.labels.items():
+        for it in items:
+            if isinstance(it, LabelRef) and it.name not in doc.labels:
+                problems.append(f"label {lname}: undefined label {it.name}")
+    for sel, op, items in doc.rules:
+        for it in items:
+            if isinstance(it, LabelRef) and it.name not in doc.labels:
+                problems.append(f"rule {sel}: undefined label {it.name}")
+    return problems
+
+
+def accumulate(doc: Document, name: str, unicodes) -> list:
+    """Build a glyph's anchor list by applying matching rules in order.
+
+    ``=`` replaces, ``+=`` appends, ``-=`` drops by anchor name. Labels are
+    resolved here, against ``doc.labels``, so overrides take effect late.
+    """
+    acc: list = []
+    for selector, op, items in doc.rules:
+        if not _matches(selector, name, unicodes):
+            continue
+        if op is Op.REMOVE:
+            drop = _remove_targets(items, doc.labels)
+            acc = [s for s in acc if s.name not in drop]
+        else:
+            specs = _resolve_items(items, doc.labels)
+            acc = specs if op is Op.REPLACE else acc + specs
+    return acc
+
+
+def apply_document(font, doc: Document, *, clear=True, replace=True, round_coords=True):
+    """Place all anchors described by *doc* onto *font* (in place).
+
+    ``round_coords`` rounds placed anchors to whole units (the usual choice for
+    a UFO); the golden regression passes ``False`` to compare raw precision.
+    """
+    for glyph in font:
+        specs = accumulate(doc, glyph.name, list(glyph.unicodes))
+        if not specs:
+            continue
+        for sfx in doc.suffixes:
+            gname = glyph.name + sfx
+            if gname in font:
+                _place(font, font[gname], specs, doc.shift_x, clear, replace, round_coords)
+
+
+def _remove_named(glyph, name):
+    for anchor in list(glyph.anchors):
+        if anchor.name == name:
+            glyph.removeAnchor(anchor)
+
+
+def _place(font, glyph, specs, shift_x, clear, replace, round_coords):
+    if clear:
+        for anchor in list(glyph.anchors):
+            glyph.removeAnchor(anchor)
+    for spec in specs:
+        x, y = resolve(font, glyph, spec)
+        if replace:
+            _remove_named(glyph, spec.name)
+        x += shift_x
+        if round_coords:
+            x, y = round(x), round(y)
+        glyph.appendAnchor(spec.name, (x, y))

anchorsfactory-0.2.0/anchorsfactory/cli.py

@@ -0,0 +1,124 @@
+"""Command-line interface for AnchorsFactory.
+
+Replaces the legacy module-level script and batch.py. Accepts one or more
+UFO paths (a directory expands to its ``*.ufo`` files), applies a rule file,
+and saves — safely by default (never overwriting the source unless asked).
+
+Logging is configured here, at the application entry point — never via
+``logging.basicConfig`` inside the library — so batch runs get a clean,
+per-font log file instead of everything landing in the first font's log.
+"""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import logging
+import os
+import sys
+from datetime import datetime
+
+from .apply import validate_document
+from .runner import load_document, process_ufo
+
+log = logging.getLogger("anchorsfactory")
+
+
+def _expand_inputs(paths: list[str]) -> list[str]:
+    ufos: list[str] = []
+    for p in paths:
+        if os.path.isdir(p) and not p.lower().endswith(".ufo"):
+            ufos.extend(sorted(glob.glob(os.path.join(p, "*.ufo"))))
+        else:
+            ufos.append(p)
+    return ufos
+
+
+def _setup_console_logging(verbose: bool) -> None:
+    log.setLevel(logging.DEBUG if verbose else logging.INFO)
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter("%(levelname)s: %(message)s"))
+    log.addHandler(handler)
+
+
+def _font_log_handler(log_dir: str, ufo_path: str) -> logging.Handler:
+    os.makedirs(log_dir, exist_ok=True)
+    stem = os.path.splitext(os.path.basename(ufo_path.rstrip(os.sep)))[0]
+    ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+    handler = logging.FileHandler(os.path.join(log_dir, f"{ts}_{stem}.log"), encoding="utf-8")
+    handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
+    return handler
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="anchorsfactory",
+        description="Place anchors in UFO fonts from a rule file.",
+    )
+    p.add_argument("ufo", nargs="+", help="UFO file(s) or a directory of UFOs")
+    p.add_argument("-r", "--rules", required=True, help="path to the anchor rules file")
+    out = p.add_mutually_exclusive_group()
+    out.add_argument("-o", "--output", help="output UFO path (single input only)")
+    out.add_argument("--in-place", action="store_true", help="overwrite the source UFO")
+    p.add_argument("--backup-dir", help="dump existing anchors here before applying")
+    p.add_argument("--keep-existing", action="store_true",
+                   help="do not clear existing anchors before applying")
+    p.add_argument("--no-round", action="store_true", help="keep fractional anchor coordinates")
+    p.add_argument("--log-dir", help="write a per-font log file into this directory")
+    p.add_argument("-v", "--verbose", action="store_true")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    _setup_console_logging(args.verbose)
+
+    inputs = _expand_inputs(args.ufo)
+    if not inputs:
+        log.error("no UFO inputs found")
+        return 2
+    if args.output and len(inputs) > 1:
+        log.error("--output cannot be used with multiple inputs; use --in-place or default naming")
+        return 2
+
+    # Load + validate the rules once, up front: fail fast on rule errors before
+    # touching any font.
+    try:
+        document = load_document(args.rules)
+    except Exception as e:  # noqa: BLE001 — surface a clean message, not a traceback
+        log.error("cannot load rules %s: %s", args.rules, e)
+        return 2
+    problems = validate_document(document)
+    if problems:
+        for msg in problems:
+            log.error("rules: %s", msg)
+        return 2
+
+    failures = 0
+    for ufo in inputs:
+        fh = _font_log_handler(args.log_dir, ufo) if args.log_dir else None
+        if fh:
+            log.addHandler(fh)
+        try:
+            process_ufo(
+                ufo, args.rules,
+                output=args.output,
+                in_place=args.in_place,
+                backup_dir=args.backup_dir,
+                clear=not args.keep_existing,
+                round_coords=not args.no_round,
+                document=document,
+            )
+        except Exception as e:  # noqa: BLE001 — report per-font, continue the batch
+            log.error("Failed on %s: %s", ufo, e)
+            failures += 1
+        finally:
+            if fh:
+                log.removeHandler(fh)
+                fh.close()
+
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

anchorsfactory-0.2.0/anchorsfactory/convert.py

@@ -0,0 +1,102 @@
+"""Convert a legacy ``.txt`` rule file to the new DSL (docs/anchor-rules.md).
+
+Reuses the IR as the bridge: parse the legacy file to a :class:`Document`
+(via :mod:`anchorsfactory.parser`), then render that Document back out in the
+new surface syntax. Rendering relies on the model's ``__str__``, which already
+emits canonical new-syntax tokens.
+
+Note: rule lines come out with anchors inlined (the legacy parser expands
+label references), so the result is faithful but not re-compressed — you can
+hand-edit it to use labels / ranges afterwards.
+"""
+
+from __future__ import annotations
+
+from .dsl import parse_dsl
+from .parser import parse_file
+
+
+def render_selector(sel) -> str:
+    return str(sel)
+
+
+def render_document(doc) -> str:
+    lines: list[str] = []
+    if doc.shift_x:
+        lines.append(f"!shiftx = {doc.shift_x}")
+    suffixes = [s for s in doc.suffixes if s]
+    if suffixes:
+        lines.append("!suffixes = " + ", ".join(suffixes))
+    if lines:
+        lines.append("")
+
+    if doc.labels:
+        lines.append("# labels")
+        for name, specs in doc.labels.items():
+            lines.append(f"{name} = " + ", ".join(str(s) for s in specs))
+        lines.append("")
+
+    lines.append("# rules")
+    for sel, op, specs in doc.rules:
+        lines.append(f"{render_selector(sel)} {op.value} " + ", ".join(str(s) for s in specs))
+    return "\n".join(lines) + "\n"
+
+
+def convert_file(legacy_path: str) -> str:
+    """Return the new-DSL text for a legacy rule file."""
+    return render_document(parse_file(legacy_path))
+
+
+def verify_conversion(legacy_path: str) -> list[str]:
+    """Round-trip check: legacy -> new text -> IR must equal the legacy IR.
+
+    Returns a list of human-readable mismatches (empty = lossless). Guarantees
+    the conversion preserved every rule, label and directive.
+    """
+    legacy = parse_file(legacy_path)
+    roundtrip = parse_dsl(render_document(legacy).splitlines())
+    problems = []
+    if roundtrip.rules != legacy.rules:
+        problems.append("rules differ after round-trip")
+    if roundtrip.labels != legacy.labels:
+        problems.append("labels differ after round-trip")
+    if roundtrip.shift_x != legacy.shift_x:
+        problems.append("shift_x differs after round-trip")
+    if roundtrip.suffixes != legacy.suffixes:
+        problems.append("suffixes differ after round-trip")
+    return problems
+
+
+def main(argv=None) -> int:
+    import argparse
+    import sys
+
+    p = argparse.ArgumentParser(
+        prog="anchorsfactory-convert",
+        description="Convert a legacy .txt rule file to the new DSL.",
+    )
+    p.add_argument("legacy", help="path to the legacy .txt rule file")
+    p.add_argument("-o", "--output", help="write here instead of stdout")
+    p.add_argument("--no-verify", action="store_true",
+                   help="skip the lossless round-trip check")
+    args = p.parse_args(argv)
+
+    text = convert_file(args.legacy)
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            f.write(text)
+    else:
+        sys.stdout.write(text)
+
+    if not args.no_verify:
+        problems = verify_conversion(args.legacy)
+        if problems:
+            for msg in problems:
+                print(f"verify: {msg}", file=sys.stderr)
+            return 1
+        print("verify: round-trip OK — conversion is lossless", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())