bibdeskparser 0.1.0__py3-none-any.whl

bibdeskparser/texmap.py

@@ -0,0 +1,467 @@
+"""BibDesk's TeX <-> Unicode string conversion.
+
+BibDesk converts between TeX markup and Unicode when reading and writing
+`.bib` files:
+
+- `detexify`: TeX -> Unicode (BibDesk applies this on *read*, for display)
+- `texify`: Unicode -> TeX (BibDesk applies this on *write*, to the `.bib`
+  file)
+
+This module replicates that conversion. The tables are transcribed
+byte-for-byte from BibDesk's `CharacterConversion.plist`, and the
+functions mirror the algorithms in BibDesk's `BDSKConverter.m`, so the
+conversion matches BibDesk exactly: for a `.bib` file written by BibDesk,
+`detexify` (read) followed by `texify` (write) reproduces the original
+file. Characters that BibDesk cannot express in TeX (e.g., `π`, `ℏ`, `₂`)
+pass through untouched in both directions.
+"""
+
+import unicodedata
+
+# All members whose name does not start with an underscore must be listed
+# either in __all__ or in __private__
+__all__ = []
+__private__ = ["detexify", "texify", "skip_texify"]
+
+
+# Roman to TeX + One-Way Conversions from `CharacterConversion.plist`
+# (used by texify; the One-Way entries convert forward only)
+_TEXIFY = {
+    "¡": "{!'}",
+    "§": "{\\S}",
+    "©": "{\\copyright}",
+    "®": "{\\textregistered}",
+    "Á": "{\\'A}",
+    "Â": "{\\^A}",
+    "Ã": "{\\~A}",
+    "Ä": '{\\"A}',
+    "Å": "{\\AA}",
+    "Æ": "{\\AE}",
+    "Ç": "{\\c C}",
+    "É": "{\\'E}",
+    "Ê": "{\\^E}",
+    "Ë": '{\\"E}',
+    "Ì": "{\\`I}",
+    "Í": "{\\'I}",
+    "Î": "{\\^I}",
+    "Ï": '{\\"I}',
+    "Ó": "{\\'O}",
+    "Ô": "{\\^O}",
+    "Ö": '{\\"O}',
+    "Ø": "{\\O}",
+    "Ú": "{\\'U}",
+    "Û": "{\\^U}",
+    "Ü": '{\\"U}',
+    "ß": "{\\ss}",
+    "à": "{\\`a}",
+    "á": "{\\'a}",
+    "â": "{\\^a}",
+    "ã": "{\\~a}",
+    "ä": '{\\"a}',
+    "å": "{\\aa}",
+    "æ": "{\\ae}",
+    "ç": "{\\c c}",
+    "è": "{\\`e}",
+    "é": "{\\'e}",
+    "ê": "{\\^e}",
+    "ë": '{\\"e}',
+    "ì": "{\\`\\i}",
+    "í": "{\\'\\i}",
+    "î": "{\\^\\i}",
+    "ï": '{\\"\\i}',
+    "ñ": "{\\~n}",
+    "ò": "{\\`o}",
+    "ó": "{\\'o}",
+    "ô": "{\\^o}",
+    "õ": "{\\~o}",
+    "ö": '{\\"o}',
+    "ø": "{\\o}",
+    "ù": "{\\`u}",
+    "ú": "{\\'u}",
+    "û": "{\\^u}",
+    "ü": '{\\"u}',
+    "ÿ": '{\\"y}',
+    "Ā": "{\\=A}",
+    "ā": "{\\=a}",
+    "ć": "{\\'c}",
+    "Č": "{\\v C}",
+    "č": "{\\v c}",
+    "ě": "{\\v e}",
+    "Ī": "{\\=I}",
+    "ī": "{\\=\\i}",
+    "Ł": "{\\L}",
+    "ł": "{\\l}",
+    "ő": "{\\H o}",
+    "Œ": "{\\OE}",
+    "œ": "{\\oe}",
+    "ş": "{\\c s}",
+    "š": "{\\v s}",
+    "Ū": "{\\=U}",
+    "ū": "{\\=u}",
+    "Ÿ": '{\\"Y}',
+    "Ž": "{\\v Z}",
+    "ž": "{\\v z}",
+    "Ḍ": "{\\d D}",
+    "ḍ": "{\\d d}",
+    "Ḥ": "{\\d H}",
+    "ḥ": "{\\d h}",
+    "Ṣ": "{\\d S}",
+    "ṣ": "{\\d s}",
+    "Ṭ": "{\\d T}",
+    "ṭ": "{\\d t}",
+    "Ẓ": "{\\d Z}",
+    "ẓ": "{\\d z}",
+    "…": "{\\ldots}",
+    "™": "{\\texttrademark}",
+    "\u00a0": " ",
+    "\u00ad": "-",
+    "°": "$\\,^{\\circ}$",
+    "±": "$\\pm$",
+    "–": "--",
+    "—": "---",
+    "‘": "`",
+    "’": "'",
+    "‛": "`",
+    "“": "``",
+    "”": "''",
+    "‟": "``",
+    "•": "*",
+    "ff": "ff",
+    "fi": "fi",
+    "fl": "fl",
+    "ffi": "ffi",
+    "ffl": "ffl",
+}
+
+# TeX to Roman from `CharacterConversion.plist` (used by detexify)
+_DETEXIFY = {
+    "{!'}": "¡",
+    '{\\"A}': "Ä",
+    '{\\"E}': "Ë",
+    '{\\"I}': "Ï",
+    '{\\"O}': "Ö",
+    '{\\"U}': "Ü",
+    '{\\"Y}': "Ÿ",
+    '{\\"\\i}': "ï",
+    '{\\"a}': "ä",
+    '{\\"e}': "ë",
+    '{\\"o}': "ö",
+    '{\\"u}': "ü",
+    '{\\"y}': "ÿ",
+    "{\\'A}": "Á",
+    "{\\'E}": "É",
+    "{\\'I}": "Í",
+    "{\\'O}": "Ó",
+    "{\\'U}": "Ú",
+    "{\\'\\i}": "í",
+    "{\\'a}": "á",
+    "{\\'c}": "ć",
+    "{\\'e}": "é",
+    "{\\'o}": "ó",
+    "{\\'u}": "ú",
+    "{\\=A}": "Ā",
+    "{\\=I}": "Ī",
+    "{\\=U}": "Ū",
+    "{\\=\\i}": "ī",
+    "{\\=a}": "ā",
+    "{\\=u}": "ū",
+    "{\\AA}": "Å",
+    "{\\AE}": "Æ",
+    "{\\H o}": "ő",
+    "{\\OE}": "Œ",
+    "{\\O}": "Ø",
+    "{\\S}": "§",
+    "{\\^A}": "Â",
+    "{\\^E}": "Ê",
+    "{\\^I}": "Î",
+    "{\\^O}": "Ô",
+    "{\\^U}": "Û",
+    "{\\^\\i}": "î",
+    "{\\^a}": "â",
+    "{\\^e}": "ê",
+    "{\\^o}": "ô",
+    "{\\^u}": "û",
+    "{\\`I}": "Ì",
+    "{\\`\\i}": "ì",
+    "{\\`a}": "à",
+    "{\\`e}": "è",
+    "{\\`o}": "ò",
+    "{\\`u}": "ù",
+    "{\\aa}": "å",
+    "{\\ae}": "æ",
+    "{\\c C}": "Ç",
+    "{\\c c}": "ç",
+    "{\\c s}": "ş",
+    "{\\cc}": "ç",
+    "{\\copyright}": "©",
+    "{\\d D}": "Ḍ",
+    "{\\d H}": "Ḥ",
+    "{\\d S}": "Ṣ",
+    "{\\d T}": "Ṭ",
+    "{\\d Z}": "Ẓ",
+    "{\\d d}": "ḍ",
+    "{\\d h}": "ḥ",
+    "{\\d s}": "ṣ",
+    "{\\d t}": "ṭ",
+    "{\\d z}": "ẓ",
+    "{\\ldots}": "…",
+    "{\\L}": "Ł",
+    "{\\l}": "ł",
+    "{\\oe}": "œ",
+    "{\\o}": "ø",
+    "{\\ss}": "ß",
+    "{\\textregistered}": "®",
+    "{\\texttrademark}": "™",
+    "{\\v C}": "Č",
+    "{\\v Z}": "Ž",
+    "{\\v c}": "č",
+    "{\\v e}": "ě",
+    "{\\v s}": "š",
+    "{\\v z}": "ž",
+    "{\\~A}": "Ã",
+    "{\\~a}": "ã",
+    "{\\~n}": "ñ",
+    "{\\~o}": "õ",
+}
+
+# accent letter/symbol -> combining mark (detexify accent algorithm)
+_DETEX_ACCENTS = {
+    '"': "\u0308",  # combining diaeresis
+    "'": "\u0301",  # combining acute accent
+    ".": "\u0307",  # combining dot above
+    "=": "\u0304",  # combining macron
+    "H": "\u030b",  # combining double acute accent
+    "^": "\u0302",  # combining circumflex accent
+    "`": "\u0300",  # combining grave accent
+    "b": "\u0331",  # combining macron below
+    "c": "\u0327",  # combining cedilla
+    "d": "\u0323",  # combining dot below
+    "k": "\u0328",  # combining ogonek
+    "r": "\u030a",  # combining ring above
+    "u": "\u0306",  # combining breve
+    "v": "\u030c",  # combining caron
+    "~": "\u0303",  # combining tilde
+}
+
+# combining mark -> accent letter/symbol, with a trailing space
+# for letter accents (texify accent algorithm)
+_TEX_ACCENTS = {
+    "\u0300": "`",  # combining grave accent
+    "\u0301": "'",  # combining acute accent
+    "\u0302": "^",  # combining circumflex accent
+    "\u0303": "~",  # combining tilde
+    "\u0304": "=",  # combining macron
+    "\u0306": "u ",  # combining breve
+    "\u0307": ".",  # combining dot above
+    "\u0308": '"',  # combining diaeresis
+    "\u030a": "r ",  # combining ring above
+    "\u030b": "H ",  # combining double acute accent
+    "\u030c": "v ",  # combining caron
+    "\u0331": "b ",  # combining macron below
+    "\u0323": "d ",  # combining dot below
+    "\u0327": "c ",  # combining cedilla
+    "\u0328": "k ",  # combining ogonek
+}
+
+# BibDesk's finalCharacterSet: the codepoints that texify will
+# attempt to convert
+# fmt: off
+_FINAL = frozenset([
+    160, 161, 167, 169, 173, 174, 176, 177, 192, 193, 194, 195, 196, 197,
+    198, 199, 200, 201, 202, 203, 204, 205, 206, 207, 209, 210, 211, 212,
+    213, 214, 216, 217, 218, 219, 220, 221, 223, 224, 225, 226, 227, 228,
+    229, 230, 231, 232, 233, 234, 235, 236, 237, 238, 239, 241, 242, 243,
+    244, 245, 246, 248, 249, 250, 251, 252, 253, 255, 256, 257, 258, 259,
+    260, 261, 262, 263, 264, 265, 266, 267, 268, 269, 270, 271, 274, 275,
+    276, 277, 278, 279, 280, 281, 282, 283, 284, 285, 286, 287, 288, 289,
+    290, 291, 292, 293, 296, 297, 298, 299, 300, 301, 302, 303, 304, 308,
+    309, 310, 311, 313, 314, 315, 316, 317, 318, 321, 322, 323, 324, 325,
+    326, 327, 328, 332, 333, 334, 335, 336, 337, 338, 339, 340, 341, 342,
+    343, 344, 345, 346, 347, 348, 349, 350, 351, 352, 353, 354, 355, 356,
+    357, 360, 361, 362, 363, 364, 365, 366, 367, 368, 369, 370, 371, 372,
+    373, 374, 375, 376, 377, 378, 379, 380, 381, 382, 416, 417, 431, 432,
+    461, 462, 463, 464, 465, 466, 467, 468, 469, 470, 471, 472, 473, 474,
+    475, 476, 478, 479, 480, 481, 482, 483, 486, 487, 488, 489, 490, 491,
+    492, 493, 494, 495, 496, 500, 501, 504, 505, 506, 507, 508, 509, 510,
+    511, 512, 513, 514, 515, 516, 517, 518, 519, 520, 521, 522, 523, 524,
+    525, 526, 527, 528, 529, 530, 531, 532, 533, 534, 535, 536, 537, 538,
+    539, 542, 543, 550, 551, 552, 553, 554, 555, 556, 557, 558, 559, 560,
+    561, 562, 563, 7680, 7681, 7682, 7683, 7684, 7685, 7686, 7687, 7688,
+    7689, 7690, 7691, 7692, 7693, 7694, 7695, 7696, 7697, 7698, 7699,
+    7700, 7701, 7702, 7703, 7704, 7705, 7706, 7707, 7708, 7709, 7710,
+    7711, 7712, 7713, 7714, 7715, 7716, 7717, 7718, 7719, 7720, 7721,
+    7722, 7723, 7724, 7725, 7726, 7727, 7728, 7729, 7730, 7731, 7732,
+    7733, 7734, 7735, 7736, 7737, 7738, 7739, 7740, 7741, 7742, 7743,
+    7744, 7745, 7746, 7747, 7748, 7749, 7750, 7751, 7752, 7753, 7754,
+    7755, 7756, 7757, 7758, 7759, 7760, 7761, 7762, 7763, 7764, 7765,
+    7766, 7767, 7768, 7769, 7770, 7771, 7772, 7773, 7774, 7775, 7776,
+    7777, 7778, 7779, 7780, 7781, 7782, 7783, 7784, 7785, 7786, 7787,
+    7788, 7789, 7790, 7791, 7792, 7793, 7794, 7795, 7796, 7797, 7798,
+    7799, 7800, 7801, 7802, 7803, 7804, 7805, 7806, 7807, 7808, 7809,
+    7810, 7811, 7812, 7813, 7814, 7815, 7816, 7817, 7818, 7819, 7820,
+    7821, 7822, 7823, 7824, 7825, 7826, 7827, 7828, 7829, 7830, 7831,
+    7832, 7833, 7835, 7840, 7841, 7842, 7843, 7844, 7845, 7846, 7847,
+    7848, 7849, 7850, 7851, 7852, 7853, 7854, 7855, 7856, 7857, 7858,
+    7859, 7860, 7861, 7862, 7863, 7864, 7865, 7866, 7867, 7868, 7869,
+    7870, 7871, 7872, 7873, 7874, 7875, 7876, 7877, 7878, 7879, 7880,
+    7881, 7882, 7883, 7884, 7885, 7886, 7887, 7888, 7889, 7890, 7891,
+    7892, 7893, 7894, 7895, 7896, 7897, 7898, 7899, 7900, 7901, 7902,
+    7903, 7904, 7905, 7906, 7907, 7908, 7909, 7910, 7911, 7912, 7913,
+    7914, 7915, 7916, 7917, 7918, 7919, 7920, 7921, 7922, 7923, 7924,
+    7925, 7926, 7927, 7928, 7929, 8211, 8212, 8216, 8217, 8219, 8220,
+    8221, 8223, 8226, 8230, 8482, 64256, 64257, 64258, 64259, 64260
+])
+# fmt: on
+
+# base letters that may carry a TeX accent
+_BASE = set("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz")
+
+
+def _tex_accent_to_char(tmp):
+    r"""Convert a `{\<accent><letter>}` token to a composed character.
+
+    Mirrors `convertTeXStringToComposedCharacter()` in BibDesk's
+    `BDSKConverter.m`. Returns the single composed Unicode character for
+    `tmp`, or `None` if `tmp` is not a valid accent token.
+    """
+    if len(tmp) < 4 or tmp[0] != "{" or tmp[1] != "\\":
+        return None
+    accent_ch = tmp[2]
+    accent = _DETEX_ACCENTS.get(accent_ch)
+    if accent is None:
+        return None
+    ch = tmp[3]
+    if accent_ch.isalpha() and ch not in (" ", "\\"):
+        # letter accents (e.g. {\v S}) must be followed by space/backslash
+        return None
+    letter_start = 4 if ch == " " else 3
+    end = tmp.find("}", letter_start)
+    if end == -1:
+        return None
+    character = tmp[letter_start:end]
+    if character in ("\\i", "\\j"):
+        character = character[1:]  # dotless i/j -> plain i/j
+    if len(character) != 1:
+        return None
+    composed = unicodedata.normalize("NFC", character + accent)
+    return composed if len(composed) == 1 else None
+
+
+def detexify(s):
+    r"""Convert TeX markup in `s` to Unicode.
+
+    ```python
+    >>> from bibdeskparser.texmap import detexify
+    >>> detexify('Universit{\\"a}t T{\\"u}bingen')
+    'Universität Tübingen'
+
+    ```
+
+    Mirrors `copyStringByDeTeXifyingString:` in BibDesk's
+    `BDSKConverter.m`; BibDesk applies this conversion to every field
+    value when reading a `.bib` file.
+
+    # Arguments
+
+    * `s`: The string to convert.
+
+    Only `{\...}` sequences are converted; the function is a no-op
+    unless `s` contains `{\`.
+    """
+    if not s or "{\\" not in s:
+        return s
+    out = s
+    i = out.find("{\\")
+    converted = False
+    while i != -1:
+        close = out.find("}", i + 2)
+        if close == -1:
+            break
+        tmp = out[i : close + 1]
+        repl = _DETEXIFY.get(tmp) or _tex_accent_to_char(tmp)
+        if repl is not None:
+            out = out[:i] + repl + out[close + 1 :]
+            converted = True
+        # advance one char past the current '{' (matches BibDesk's
+        # search reset)
+        i = out.find("{\\", i + 1)
+    return out if converted else s
+
+
+def _char_to_tex_accent(ch):
+    r"""Convert a composed character to a `{\<accent><letter>}` token.
+
+    Mirrors `convertComposedCharacterToTeX()` in BibDesk's
+    `BDSKConverter.m`. Returns the TeX form of the single character `ch`
+    (or `ch` itself for a plain base letter), or `None` if `ch` cannot be
+    expressed as a TeX accent.
+    """
+    d = unicodedata.normalize("NFD", ch)
+    if len(d) == 0 or d[0] not in _BASE:
+        return None
+    if len(d) == 1:
+        return ch  # base letter, nothing to do
+    if len(d) > 2 or d[1] not in _TEX_ACCENTS:
+        return None
+    accent = _TEX_ACCENTS[d[1]]
+    character = d[0]
+    if character in ("i", "j") and accent not in ("c ", "d ", "b ", "k "):
+        character = "\\" + character  # dotless \i / \j
+    return "{\\" + accent + character + "}"
+
+
+def texify(s):
+    r"""Convert Unicode characters in `s` to TeX markup.
+
+    ```python
+    >>> from bibdeskparser.texmap import texify
+    >>> texify("Universität Tübingen")
+    'Universit{\\"a}t T{\\"u}bingen'
+
+    ```
+
+    Mirrors `copyStringByTeXifyingString:` in BibDesk's
+    `BDSKConverter.m`; BibDesk applies this conversion to every field
+    value when writing a `.bib` file.
+
+    # Arguments
+
+    * `s`: The string to convert.
+
+    The string is first NFC-normalized; only characters whose codepoint
+    is in BibDesk's "final character set" are converted, and any other
+    character (e.g., `π`, `ℏ`, `₂`) passes through untouched.
+    """
+    if not s:
+        return s
+    s = unicodedata.normalize("NFC", s)
+    out = []
+    changed = False
+    for ch in s:
+        if ord(ch) in _FINAL:
+            repl = _TEXIFY.get(ch)
+            if repl is None:
+                repl = _char_to_tex_accent(ch)
+            if repl is not None and repl != ch:
+                out.append(repl)
+                changed = True
+                continue
+        out.append(ch)
+    return "".join(out) if changed else s
+
+
+def skip_texify(key):
+    r"""Whether the field `key` is excluded from TeX conversion.
+
+    # Arguments
+
+    * `key`: The field key, e.g. `"url"` or `"bdsk-file-1"`. Matching is
+      case-insensitive.
+
+    Returns `True` if the (lowercased) `key` contains `"url"` or starts
+    with `"bdsk-file"`. BibDesk does not TeXify URL fields, and
+    `bdsk-file` fields hold base64 data. Both are pure ASCII without
+    `{\` sequences, so this only matters as a safety guard.
+    """
+    k = key.lower()
+    return "url" in k or k.startswith("bdsk-file")

bibdeskparser/writer.py

@@ -0,0 +1,234 @@
+r"""Serialization of a `bibtexparser` library in BibDesk's file format.
+
+BibDesk lays out a `.bib` file as the header comment, the `@string`
+definitions, the entries, and finally the group `@comment` blocks.
+Blocks are separated by one blank line, except for two blank lines
+before the `@string` section and before the first entry. Entry fields
+are written one per line, indented with a tab, with the closing brace
+fused onto the last field line.
+
+`render_library` serializes a parsed library back to that exact
+format: for an unmodified library, the output is byte-identical to the
+original file.
+
+```python
+>>> import bibtexparser
+>>> from bibdeskparser.middleware import parse_stack
+>>> from bibdeskparser.writer import render_library
+>>> source = (
+...     '@article{key1,\n'
+...     '\tauthor = {Gr{\\"u}n, Anna},\n'
+...     '\tyear = {2026}}\n'
+... )
+>>> library = bibtexparser.parse_string(source, parse_stack=parse_stack())
+>>> library.entries[0]["author"]  # Unicode model ...
+'{Grün, Anna}'
+>>> render_library(library) == source  # ... but byte-exact output
+True
+
+```
+"""
+
+from bibtexparser.model import (
+    Entry,
+    ExplicitComment,
+    ImplicitComment,
+    ParsingFailedBlock,
+    String,
+)
+
+from .bdskfile import BibDeskFile
+from .header import restore_trailing_space
+from .middleware import TeXifyMiddleware
+
+__all__ = []
+
+# All members whose name does not start with an underscore must be listed
+# either in __all__ or in __private__
+__private__ = [
+    "render_library",
+    "serialize_block",
+    "bibdesk_field_order",
+    "separator",
+]
+
+
+#: First line of the header comment in files written by BibDesk.
+_BIBDESK_HEADER_PREFIX = (
+    "%% This BibTeX bibliography file was created using BibDesk"
+)
+
+
+def serialize_block(block):
+    r"""Serialize a single block in BibDesk's exact format.
+
+    ```python
+    serialize_block(block)
+    ```
+
+    Returns the string representation (without trailing newline) of a
+    `bibtexparser` block:
+
+    * `ImplicitComment`: the comment text, verbatim. If the comment is
+      a BibDesk header, the trailing space that the parser rstripped
+      from the last line is restored.
+    * `String`: `@string{key = value}`.
+    * `ExplicitComment`: `@comment{...}`, with the comment body
+      written verbatim.
+    * `Entry`: the entry type and key, then one tab-indented line per
+      field, with the closing brace directly after the last field
+      value. {any}`bibdeskparser.bdskfile.BibDeskFile` values are
+      serialized via their
+      {any}`~bibdeskparser.bdskfile.BibDeskFile.to_field_value` method.
+    * `ParsingFailedBlock` (e.g., a `DuplicateBlockKeyBlock` for an
+      entry with a duplicate key): the block's `raw` source slice,
+      verbatim, so that files with duplicate keys still round-trip.
+
+    Raises {any}`TypeError` for any other block type.
+
+    ```python
+    >>> from bibtexparser.model import Entry, Field, String
+    >>> from bibdeskparser.writer import serialize_block
+    >>> print(serialize_block(String(key="jpb", value="{J. Phys. B}")))
+    @string{jpb = {J. Phys. B}}
+    >>> entry = Entry(
+    ...     entry_type="article",
+    ...     key="key1",
+    ...     fields=[
+    ...         Field(key="author", value="{Goerz}"),
+    ...         Field(key="year", value="{2026}"),
+    ...     ],
+    ... )
+    >>> serialize_block(entry)
+    '@article{key1,\n\tauthor = {Goerz},\n\tyear = {2026}}'
+
+    ```
+    """
+    if isinstance(block, ImplicitComment):
+        text = block.comment
+        if text.startswith(_BIBDESK_HEADER_PREFIX):
+            text = restore_trailing_space(text)
+        return text
+    if isinstance(block, String):
+        return f"@string{{{block.key} = {block.value}}}"
+    if isinstance(block, ExplicitComment):
+        return f"@comment{{{block.comment}}}"
+    if isinstance(block, Entry):
+        if not block.fields:
+            return f"@{block.entry_type}{{{block.key}}}"
+        lines = [f"@{block.entry_type}{{{block.key},"]
+        last = len(block.fields) - 1
+        for i, field in enumerate(block.fields):
+            value = field.value
+            if isinstance(value, BibDeskFile):
+                value = value.to_field_value()
+            tail = "}" if i == last else ","
+            lines.append(f"\t{field.key} = {value}{tail}")
+        return "\n".join(lines)
+    if isinstance(block, ParsingFailedBlock):
+        return block.raw
+    raise TypeError(f"Unhandled block type: {type(block).__name__}")
+
+
+def _effective_type(block):
+    """The block type to use for separator purposes.
+
+    A `ParsingFailedBlock` counts as the block it wraps
+    (`ignore_error_block`), or as an `Entry` if it wraps nothing, since
+    failed blocks are almost always broken entries (e.g., duplicate
+    keys)."""
+    if isinstance(block, ParsingFailedBlock):
+        inner = block.ignore_error_block
+        return type(inner) if inner is not None else Entry
+    return type(block)
+
+
+def separator(prev_block, cur_block):
+    """The blank-line separator BibDesk puts between two blocks.
+
+    ```python
+    separator(prev_block, cur_block)
+    ```
+
+    Returns `"\\n\\n\\n"` (two blank lines) between the header comment
+    and the first `@string`, and between the last `@string` and the
+    first entry, i.e., when `prev_block` is an `ImplicitComment` and
+    `cur_block` is a `String`, or when `prev_block` is a `String` and
+    `cur_block` is an `Entry`. Returns `"\\n\\n"` (one blank line) for
+    every other transition. A `ParsingFailedBlock` counts as the block
+    it wraps (usually an `Entry` with a duplicate key).
+    """
+    prev_type = _effective_type(prev_block)
+    cur_type = _effective_type(cur_block)
+    double = (
+        issubclass(prev_type, ImplicitComment) and issubclass(cur_type, String)
+    ) or (issubclass(prev_type, String) and issubclass(cur_type, Entry))
+    return "\n\n\n" if double else "\n\n"
+
+
+def render_library(library):
+    """Serialize a library to the exact text BibDesk would write.
+
+    ```python
+    render_library(library)
+    ```
+
+    Returns the full text of the `.bib` file for `library`: all blocks
+    serialized with `serialize_block`, joined with `separator`, with a
+    final newline. Before serializing, the library is passed through
+    `TeXifyMiddleware` on a copy (`allow_inplace_modification=False`),
+    so Unicode field values are written as TeX and the caller's
+    library is left untouched.
+    """
+    library = TeXifyMiddleware(allow_inplace_modification=False).transform(
+        library
+    )
+    pieces = []
+    prev = None
+    for block in library.blocks:
+        if prev is not None:
+            pieces.append(separator(prev, block))
+        pieces.append(serialize_block(block))
+        prev = block
+    pieces.append("\n")
+    return "".join(pieces)
+
+
+def bibdesk_field_order(fields):
+    """Sort entry fields the way BibDesk does.
+
+    ```python
+    bibdesk_field_order(fields)
+    ```
+
+    Returns the list of `bibtexparser` `Field` objects in `fields`
+    sorted case-insensitively alphabetically by key, except that all
+    `bdsk-*` fields (file attachments, URLs) come after all other
+    fields (each group sorted alphabetically). The sort is stable and
+    purely lexical, so, e.g., `bdsk-file-10` sorts *before*
+    `bdsk-file-2` (`"1" < "2"`), matching the field order in files
+    written by BibDesk.
+
+    This helper is not used by `render_library` (which writes fields
+    in their existing order); it is intended for normalizing the field
+    order of newly created or modified entries.
+
+    ```python
+    >>> from bibtexparser.model import Field
+    >>> from bibdeskparser.writer import bibdesk_field_order
+    >>> fields = [
+    ...     Field(key="bdsk-url-1", value="{http://example.org}"),
+    ...     Field(key="year", value="{2026}"),
+    ...     Field(key="author", value="{Goerz, Michael}"),
+    ... ]
+    >>> [field.key for field in bibdesk_field_order(fields)]
+    ['author', 'year', 'bdsk-url-1']
+
+    ```
+    """
+
+    def sort_key(field):
+        key = field.key.lower()
+        return (key.startswith("bdsk-"), key)
+
+    return sorted(fields, key=sort_key)