bibdeskparser 0.1.0__py3-none-any.whl

bibdeskparser/exporting.py

@@ -0,0 +1,331 @@
+r"""Serialization of `Entry` objects to bibtex text ("export" snippets).
+
+Provides {any}`export_entries`, which renders one or more
+{any}`bibdeskparser.entry.Entry` objects to a bibtex snippet in one of
+three formats:
+
+- `"default"`: every stored field except the BibDesk bookkeeping fields
+  (`date-added`/`date-modified`) and the `bdsk-*` fields -- i.e., the
+  `Entry` dict interface plus `keywords` -- Unicode and detexified,
+  plus the entry's `bdsk-file-N`/`bdsk-url-N` fields rendered as plain
+  relative paths/URLs. This is the format used to build the temporary
+  file shown to `$EDITOR` (see the later `editing.py` module): it is
+  re-parseable and its fields can be merged back into an `Entry` (the
+  `bdsk-file`/`bdsk-url` and `keywords` lines are merged via their
+  dedicated properties, not the dict interface, since those fields are
+  not part of it).
+- `"raw"`: the same field set/order as `"default"`, but field values are
+  the literal TeX-encoded text as stored (i.e., exactly what would end
+  up in a `.bib` file on disk), rather than the decoded Unicode dict
+  values.
+- `"minimal"`: a small, LaTeX-bibliography-oriented whitelist of fields
+  per entry type, covering `article`, `inproceedings`, `incollection`,
+  `mastersthesis`, and `phdthesis`, with a best-effort
+  `author, title, year` fallback for every other entry type.
+
+For `"default"` and `"raw"`, an optional `strings` mapping of macro name
+to Unicode value (e.g., `library.strings`) is used to prepend `@string`
+definitions for every macro name that is actually referenced (as a bare
+field value) by the selected entries, so the exported snippet is
+self-contained. `"minimal"` never emits `@string` definitions. The
+`keywords` field is always literal text, never a macro reference: its
+value is always rendered braced, and it never pulls in an `@string`
+definition, even when a keyword happens to match a macro name.
+
+This module intentionally does not import `bibdeskparser.library`
+(which imports this module), to avoid a circular dependency.
+
+```python
+>>> from bibdeskparser.entry import Entry
+>>> from bibdeskparser.exporting import export_entries
+>>> entry = Entry(
+...     "article",
+...     "Key2024",
+...     fields={"author": "Jane Doe", "title": "A Title", "year": "2024"},
+... )
+>>> text = export_entries([entry])
+>>> text == (
+...     "@article{Key2024,\n"
+...     "\tauthor = {Jane Doe},\n"
+...     "\ttitle = {A Title},\n"
+...     "\tyear = {2024}\n"
+...     "}\n"
+... )
+True
+
+```
+"""
+
+import re
+
+from .bdskfile import BibDeskFile
+from .macros import is_valid_macro_name, normalize_macro_name
+from .writer import bibdesk_field_order
+
+__all__ = []
+
+# All members whose name does not start with an underscore must be listed
+# either in __all__ or in __private__
+__private__ = ["export_entries"]
+
+_FORMATS = frozenset(("default", "raw", "minimal"))
+
+#: Non-normal field keys (never part of any exported format's field
+#: list; `bdsk-file-N`/`bdsk-url-N` are handled separately).
+_DATE_KEYS = frozenset(("date-added", "date-modified"))
+
+_BDSK_FILE_RE = re.compile(r"bdsk-file-(\d+)$", re.IGNORECASE)
+_BDSK_URL_RE = re.compile(r"bdsk-url-(\d+)$", re.IGNORECASE)
+
+#: Per-entry-type field whitelist for the `"minimal"` format.
+_MINIMAL_FIELDS = {
+    "article": (
+        "author",
+        "title",
+        "journal",
+        "year",
+        "doi",
+        "pages",
+        "volume",
+        "number",
+    ),
+    "inproceedings": (
+        "author",
+        "title",
+        "booktitle",
+        "year",
+        "doi",
+        "pages",
+        "address",
+        "editor",
+    ),
+    "incollection": (
+        "author",
+        "title",
+        "booktitle",
+        "year",
+        "doi",
+        "pages",
+        "editor",
+        "publisher",
+        "volume",
+    ),
+    "mastersthesis": ("author", "title", "school", "year"),
+    "phdthesis": ("author", "title", "school", "year"),
+}
+
+#: Best-effort fallback whitelist for any entry type not covered by
+#: `_MINIMAL_FIELDS` (e.g. `book`, `misc`, `techreport`,
+#: `unpublished`, ...). Not tuned per type -- just enough for a minimal
+#: citation.
+_MINIMAL_FALLBACK = ("author", "title", "year")
+
+
+def _is_normal_field(key):
+    """Whether `key` is exported as a regular field: not a
+    `date-added`/`date-modified`/`bdsk-*` field. This includes
+    `keywords`, which `Entry`'s dict interface hides."""
+    lkey = key.lower()
+    return lkey not in _DATE_KEYS and not lkey.startswith("bdsk-")
+
+
+def _normal_fields(entry):
+    """The "normal" `Field` objects of `entry`, in BibDesk's field
+    order."""
+    fields = [f for f in entry._entry.fields if _is_normal_field(f.key)]
+    return bibdesk_field_order(fields)
+
+
+def _strip_braces(value):
+    """Strip one matching pair of enclosing `{...}`/`"..."`, if
+    present."""
+    if isinstance(value, str) and len(value) >= 2:
+        if (value[0] == "{" and value[-1] == "}") or (
+            value[0] == '"' and value[-1] == '"'
+        ):
+            return value[1:-1]
+    return value
+
+
+def _render_value(value):
+    """Render a Unicode field value: bare if it's a normalized macro
+    name, else braced."""
+    if is_valid_macro_name(value, normalized=True):
+        return value
+    return "{" + value + "}"
+
+
+def _bdsk_bodies(entry):
+    """`"name = value"` bodies (no trailing comma/newline) for
+    `entry`'s `bdsk-file-N`/`bdsk-url-N` fields, in numeric order:
+    files (as plain relative paths) before URLs (brace-stripped)."""
+    file_fields = []
+    url_fields = []
+    for field in entry._entry.fields:
+        match = _BDSK_FILE_RE.match(field.key)
+        if match:
+            file_fields.append((int(match.group(1)), field))
+            continue
+        match = _BDSK_URL_RE.match(field.key)
+        if match:
+            url_fields.append((int(match.group(1)), field))
+    file_fields.sort(key=lambda item: item[0])
+    url_fields.sort(key=lambda item: item[0])
+    bodies = []
+    for index, field in file_fields:
+        value = field.value
+        if isinstance(value, BibDeskFile):
+            path = value.relative_path
+        else:
+            path = BibDeskFile.from_field_value(value).relative_path
+        bodies.append(f"bdsk-file-{index} = {{{path}}}")
+    for index, field in url_fields:
+        url = _strip_braces(field.value)
+        bodies.append(f"bdsk-url-{index} = {{{url}}}")
+    return bodies
+
+
+def _entry_bodies(entry, fmt):
+    """`"name = value"` bodies (no trailing comma/newline), in order,
+    for `entry` in the `"default"`/`"raw"` formats."""
+    bodies = []
+    for field in _normal_fields(entry):
+        name = field.key.lower()
+        if fmt == "raw":
+            bodies.append(f"{name} = {field.value}")
+        else:
+            # `entry._decode` rather than `entry[field.key]`: the
+            # decoding is identical, but the dict interface hides
+            # `keywords`, which is still exported.
+            value = entry._decode(field.key, field.value)
+            if name == "keywords":
+                # Keywords are always literal text, never a macro
+                # reference: a one-word macro-shaped keyword must not
+                # be rendered bare.
+                bodies.append(f"{name} = {{{value}}}")
+            else:
+                bodies.append(f"{name} = {_render_value(value)}")
+    bodies.extend(_bdsk_bodies(entry))
+    return bodies
+
+
+def _render_entry(entry, fmt):
+    """Render a single `entry` (`"default"`/`"raw"`/`"minimal"`)."""
+    if fmt == "minimal":
+        return _render_minimal_entry(entry)
+    bodies = _entry_bodies(entry, fmt)
+    lines = [f"@{entry.entry_type}{{{entry.key},\n"]
+    last = len(bodies) - 1
+    for i, body in enumerate(bodies):
+        tail = "" if i == last else ","
+        lines.append(f"\t{body}{tail}\n")
+    lines.append("}\n")
+    return "".join(lines)
+
+
+def _render_minimal_entry(entry):
+    """Render a single `entry` in the `"minimal"` format."""
+    whitelist = _MINIMAL_FIELDS.get(entry.entry_type.lower())
+    if whitelist is None:
+        whitelist = _MINIMAL_FALLBACK
+    lines = [f"@{entry.entry_type}{{{entry.key},\n"]
+    for name in whitelist:
+        value = entry.get(name)
+        if not value:
+            continue
+        lines.append(f"    {name.capitalize()} = {_render_value(value)},\n")
+    lines.append("}\n")
+    return "".join(lines)
+
+
+def _is_bare(value):
+    """Whether `value` is a string with no enclosing `{...}`/`"..."`
+    (a bare macro reference, per BibDesk's convention)."""
+    return isinstance(value, str) and bool(value) and value[0] not in '{"'
+
+
+def _referenced_macro_names(entries):
+    """The set of (normalized) macro names referenced as a bare field
+    value by any entry in `entries`.
+
+    The `keywords` field never counts as a macro reference (keywords
+    are always literal text), so it never pulls in an `@string`
+    definition."""
+    names = set()
+    for entry in entries:
+        for field in entry._entry.fields:
+            value = field.value
+            if (
+                _is_bare(value)
+                and field.key.lower() != "keywords"
+                and is_valid_macro_name(value, normalized=False)
+            ):
+                names.add(normalize_macro_name(value))
+    return names
+
+
+def _string_lines(entries, strings):
+    """`@string{name = {value}}` lines for every macro referenced by
+    `entries` that is defined in `strings`, sorted by name."""
+    if not strings:
+        return []
+    names = sorted(
+        name for name in _referenced_macro_names(entries) if name in strings
+    )
+    return [
+        "@string{" + name + " = {" + strings[name] + "}}\n" for name in names
+    ]
+
+
+def export_entries(
+    entries, strings=None, format="default", outfile=None
+):  # pylint: disable=redefined-builtin
+    """Serialize `entries` (an iterable of `Entry`) to bibtex text.
+
+    ```python
+    export_entries(entries, strings=None, format="default", outfile=None)
+    ```
+
+    Returns the text as a `str` if `outfile` is `None`, else writes it
+    (UTF-8) to `outfile` and returns `None`.
+
+    # Arguments
+
+    * `entries`: an iterable of {any}`bibdeskparser.entry.Entry`.
+    * `strings`: an optional `dict` mapping macro name to its Unicode
+      value (e.g. `library.strings`), used to prepend `@string`
+      definitions for every macro actually referenced by `entries`
+      (see the module docstring); ignored for `format="minimal"`. A
+      referenced macro not found in `strings` is silently skipped (not
+      an error -- this is a best-effort self-containment feature, not
+      a validator).
+    * `format`: one of `"default"`, `"raw"`, `"minimal"` (see the
+      module docstring); raises {any}`ValueError` for any other value.
+    * `outfile`: if given, a path (`str`/`pathlib.Path`) or an
+      already-open text file object (anything with a `write` method;
+      if already open, it is written to but not closed).
+
+    Multiple entries are separated by a single blank line; the returned
+    (or written) text always ends with exactly one trailing newline.
+    """
+    if format not in _FORMATS:
+        raise ValueError(
+            f"format must be one of {sorted(_FORMATS)}, not {format!r}"
+        )
+    entries = list(entries)
+    pieces = []
+    if format != "minimal":
+        string_lines = _string_lines(entries, strings)
+        if string_lines:
+            pieces.append("".join(string_lines))
+            pieces.append("\n")
+    pieces.append("\n".join(_render_entry(entry, format) for entry in entries))
+    text = "".join(pieces)
+    if outfile is None:
+        return text
+    if hasattr(outfile, "write"):
+        outfile.write(text)
+        return None
+    with open(outfile, "w", encoding="utf-8") as fh:
+        fh.write(text)
+    return None

bibdeskparser/groups.py

@@ -0,0 +1,119 @@
+"""BibDesk static groups (the `BibDesk Static Groups` `@comment`).
+
+BibDesk stores manually curated ("static") groups in an `@comment` block
+at the end of the `.bib` file. The body of that comment is the literal
+prefix `BibDesk Static Groups{`, a newline, an Apple XML plist, and a
+closing `}`. The plist is an `<array>` of `<dict>`s with two keys:
+`group name` (the group's display name) and `keys` (the citation keys of
+the group's members, comma-joined). Python's `plistlib` reproduces
+BibDesk's exact XML layout (tab indentation, entity escaping), so a
+parsed block re-serializes byte-for-byte.
+
+This module holds only pure (de)serialization functions. The decoded
+form is a plain `dict` mapping each group name to a `tuple` of citation
+keys, in file order; all group *state* (and every mutation of it) lives
+in {any}`bibdeskparser.library.Library`.
+"""
+
+import plistlib
+
+__all__ = []
+
+# All members whose name does not start with an underscore must be listed
+# either in __all__ or in __private__
+__private__ = [
+    "is_static_groups_comment",
+    "parse_static_groups",
+    "render_static_groups",
+]
+
+_STATIC_GROUPS_HEAD = "BibDesk Static Groups{"
+
+
+def is_static_groups_comment(comment):
+    """Check whether a comment body holds a static-groups block.
+
+    ```python
+    is_static_groups_comment(comment)
+    ```
+
+    Return `True` if `comment` (the string body of an `@comment` block,
+    e.g. the `comment` attribute of a bibtexparser `ExplicitComment`) is
+    a `BibDesk Static Groups` block that can be parsed with
+    `parse_static_groups`. Non-string input yields `False`.
+
+    ```python
+    >>> from bibdeskparser.groups import is_static_groups_comment
+    >>> is_static_groups_comment("BibDesk Static Groups{...}")
+    True
+    >>> is_static_groups_comment("some other comment")
+    False
+    >>> is_static_groups_comment(None)
+    False
+
+    ```
+    """
+    return isinstance(comment, str) and comment.startswith(_STATIC_GROUPS_HEAD)
+
+
+def parse_static_groups(comment):
+    """Parse an `@comment` body of the form `BibDesk Static Groups{...}`.
+
+    ```python
+    parse_static_groups(comment)
+    ```
+
+    The `...` is a newline, an Apple XML plist, and a final newline; the
+    trailing `}` closes the head's opening brace. Return a `dict`
+    mapping each group name to a `tuple` of the group's citation keys,
+    with both the groups and the keys within each group in file order.
+
+    ```python
+    >>> from bibdeskparser.groups import (
+    ...     parse_static_groups,
+    ...     render_static_groups,
+    ... )
+    >>> comment = render_static_groups({"My Papers": ("key1", "key2")})
+    >>> parse_static_groups(comment)
+    {'My Papers': ('key1', 'key2')}
+
+    ```
+    """
+    # After the head comes `\\n<plist xml>\\n}`; drop the head and the
+    # trailing `}`. plistlib requires the `<?xml` declaration at offset
+    # 0, so strip the leading newline (render_static_groups re-adds it).
+    body = comment[len(_STATIC_GROUPS_HEAD) : comment.rindex("}")]
+    array = plistlib.loads(body.lstrip().encode("utf-8"))
+    return {
+        item["group name"]: (
+            tuple(item["keys"].split(",")) if item["keys"] else ()
+        )
+        for item in array
+    }
+
+
+def render_static_groups(groups):
+    """Serialize `groups` to the exact `@comment` body BibDesk writes.
+
+    ```python
+    render_static_groups(groups)
+    ```
+
+    * `groups`: a `dict` mapping each group name to an iterable of the
+      group's citation keys (as returned by `parse_static_groups`).
+
+    The result of parsing a BibDesk-written comment with
+    `parse_static_groups` and serializing it again is byte-identical to
+    the original.
+    """
+    array = [
+        {"group name": name, "keys": ",".join(keys)}
+        for name, keys in groups.items()
+    ]
+    xml = plistlib.dumps(
+        array,
+        fmt=plistlib.FMT_XML,  # pylint: disable=no-member
+    ).decode("utf-8")
+    # plistlib output ends in `</plist>\n`; the head supplies the
+    # leading `\n`.
+    return f"{_STATIC_GROUPS_HEAD}\n{xml}}}"

bibdeskparser/header.py

@@ -0,0 +1,236 @@
+"""Handling of the header comment in BibDesk `.bib` files.
+
+Every `.bib` file saved by BibDesk starts with this header (`NAME` is
+the macOS user's full name, and there is a single trailing space after
+the date and after `(UTF-8)`):
+
+```
+%% This BibTeX bibliography file was created using BibDesk.
+%% http://bibdesk.sourceforge.net/
+
+
+%% Created for NAME at YYYY-MM-DD HH:MM:SS ±ZZZZ
+
+
+%% Saved with string encoding Unicode (UTF-8)
+```
+
+The date on the `Created for` line is the time of the last save;
+BibDesk updates it in place on every save. `bibtexparser` parses the
+whole header as a single `ImplicitComment` block (internal blank lines
+and trailing spaces are preserved verbatim, but the trailing space of
+the *last* line is rstripped away; see `restore_trailing_space`).
+
+This module extracts data from that header (`parse_header`,
+`peek_timestamp`), updates it in place (`update_header`), and
+synthesizes it for new files (`make_header`).
+"""
+
+import datetime
+import re
+
+__all__ = []
+
+# All members whose name does not start with an underscore must be listed
+# either in __all__ or in __private__
+__private__ = [
+    "parse_header",
+    "make_header",
+    "peek_timestamp",
+    "update_header",
+    "restore_trailing_space",
+]
+
+
+#: `strptime`/`strftime` format of the date in the `Created for` line.
+_TIMESTAMP_FMT = "%Y-%m-%d %H:%M:%S %z"
+
+#: Regex matching the `Created for` line of a BibDesk header.
+_CREATED_RE = re.compile(
+    r"^%% Created for (?P<creator>.+?) at "
+    r"(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} [+-]\d{4})",
+    flags=re.MULTILINE,
+)
+
+#: First line of the last section of a BibDesk header.
+_SAVED_WITH_PREFIX = "%% Saved with string encoding "
+
+#: Template for `make_header` (mind the trailing spaces).
+_HEADER_TEMPLATE = (
+    "%% This BibTeX bibliography file was created using BibDesk.\n"
+    "%% http://bibdesk.sourceforge.net/\n"
+    "\n"
+    "\n"
+    "%% Created for {creator} at {timestamp} \n"
+    "\n"
+    "\n"
+    "%% Saved with string encoding Unicode (UTF-8) "
+)
+
+
+def parse_header(comment_text):
+    """Extract the creator and save time from a BibDesk header.
+
+    ```python
+    parse_header(comment_text)
+    ```
+
+    Returns a tuple `(creator, timestamp)` with the creator name (str)
+    and the last-save time (a timezone-aware
+    {any}`datetime.datetime`), extracted from the
+    `%% Created for NAME at YYYY-MM-DD HH:MM:SS ±ZZZZ` line of
+    `comment_text` (the body of the comment block at the top of the
+    `.bib` file). Returns `(None, None)` if no such line is found,
+    indicating that the file was not written by BibDesk.
+
+    ```python
+    >>> from bibdeskparser.header import parse_header
+    >>> header = (
+    ...     "%% This BibTeX bibliography file was created using "
+    ...     "BibDesk.\\n"
+    ...     "%% http://bibdesk.sourceforge.net/\\n\\n\\n"
+    ...     "%% Created for Michael Goerz at 2026-07-04 13:45:42 -0400 "
+    ... )
+    >>> creator, timestamp = parse_header(header)
+    >>> creator
+    'Michael Goerz'
+    >>> print(timestamp)
+    2026-07-04 13:45:42-04:00
+    >>> parse_header("% not a BibDesk header")
+    (None, None)
+
+    ```
+    """
+    match = _CREATED_RE.search(comment_text)
+    if match is None:
+        return (None, None)
+    timestamp = datetime.datetime.strptime(
+        match.group("timestamp"), _TIMESTAMP_FMT
+    )
+    return (match.group("creator"), timestamp)
+
+
+def update_header(comment_text, timestamp):
+    """Replace the save time in a BibDesk header.
+
+    ```python
+    update_header(comment_text, timestamp)
+    ```
+
+    Returns a copy of `comment_text` in which only the
+    `YYYY-MM-DD HH:MM:SS ±ZZZZ` substring of the `Created for` line is
+    replaced with `timestamp` (a timezone-aware
+    {any}`datetime.datetime`). Everything else, including trailing
+    spaces, is preserved byte-for-byte, mirroring how BibDesk updates
+    the date in place on every save.
+
+    Raises {any}`ValueError` if `comment_text` contains no
+    `Created for` line (see `parse_header`).
+    """
+    match = _CREATED_RE.search(comment_text)
+    if match is None:
+        raise ValueError(
+            "Cannot update header: no BibDesk 'Created for' line in "
+            f"{comment_text!r}"
+        )
+    start, end = match.span("timestamp")
+    return (
+        comment_text[:start]
+        + timestamp.strftime(_TIMESTAMP_FMT)
+        + comment_text[end:]
+    )
+
+
+def make_header(creator, timestamp):
+    """Synthesize the header comment for a new BibDesk `.bib` file.
+
+    ```python
+    make_header(creator, timestamp)
+    ```
+
+    Returns the canonical BibDesk header exactly as BibDesk writes it
+    (including the single trailing space after the date and after
+    `(UTF-8)`, and the two blank lines between sections), without a
+    trailing newline.
+
+    * `creator`: the name to put on the `Created for` line.
+    * `timestamp`: the save time, as a timezone-aware
+      {any}`datetime.datetime`.
+
+    ```python
+    >>> import datetime
+    >>> from bibdeskparser.header import make_header, parse_header
+    >>> timestamp = datetime.datetime(
+    ...     2026, 7, 4, 13, 45, 42,
+    ...     tzinfo=datetime.timezone(datetime.timedelta(hours=-4)),
+    ... )
+    >>> header = make_header("Michael Goerz", timestamp)
+    >>> for line in header.split("\\n"):
+    ...     print(repr(line))
+    '%% This BibTeX bibliography file was created using BibDesk.'
+    '%% http://bibdesk.sourceforge.net/'
+    ''
+    ''
+    '%% Created for Michael Goerz at 2026-07-04 13:45:42 -0400 '
+    ''
+    ''
+    '%% Saved with string encoding Unicode (UTF-8) '
+    >>> parse_header(header) == ("Michael Goerz", timestamp)
+    True
+
+    ```
+    """
+    return _HEADER_TEMPLATE.format(
+        creator=creator, timestamp=timestamp.strftime(_TIMESTAMP_FMT)
+    )
+
+
+def peek_timestamp(path):
+    """Cheaply extract the save time from a `.bib` file on disk.
+
+    ```python
+    peek_timestamp(path)
+    ```
+
+    Reads only the first 20 lines of the file at `path` (without
+    parsing it as BibTeX) and returns the timezone-aware
+    {any}`datetime.datetime` from the header's `Created for` line, or
+    `None` if the file has no BibDesk header. This is intended for
+    detecting whether a file changed on disk (e.g., was re-saved by
+    BibDesk) since it was read.
+    """
+    lines = []
+    with open(path, encoding="utf-8", errors="replace") as bibfile:
+        for line in bibfile:
+            lines.append(line)
+            if len(lines) >= 20:
+                break
+    _, timestamp = parse_header("".join(lines))
+    return timestamp
+
+
+def restore_trailing_space(comment_text):
+    """Re-append the trailing space to a parsed BibDesk header.
+
+    ```python
+    restore_trailing_space(comment_text)
+    ```
+
+    BibDesk writes the last header line as
+    `%% Saved with string encoding Unicode (UTF-8) `, with a single
+    trailing space. When `bibtexparser` parses the header into an
+    `ImplicitComment`, it preserves *internal* trailing spaces (such as
+    the one after the date) but rstrips the whitespace at the very end
+    of the comment, so that one space is lost. This function re-appends
+    it, so that writing the parsed header back to disk is byte-exact.
+
+    The space is appended only if the last line of `comment_text`
+    starts with `%% Saved with string encoding` and does not already
+    end in whitespace; any other text is returned unchanged.
+    """
+    last_line = comment_text.rsplit("\n", 1)[-1]
+    if last_line.startswith(_SAVED_WITH_PREFIX.rstrip()) and (
+        last_line == last_line.rstrip()
+    ):
+        return comment_text + " "
+    return comment_text