bibdeskparser 0.1.0__py3-none-any.whl

bibdeskparser/macros.py

@@ -0,0 +1,109 @@
+r"""Validation and normalization of BibDesk macro (`@string`) names.
+
+BibDesk restricts the names of macros (BibTeX `@string` definitions) to a
+subset of printable ASCII and treats them case-insensitively: its macro
+editor forces names to lowercase as they are typed, and its macro table
+(`BDSKMacroResolver`) looks names up by their lowercased form. This module
+replicates those rules.
+"""
+
+__all__ = []
+
+# All members whose name does not start with an underscore must be listed
+# either in __all__ or in __private__
+__private__ = ["is_valid_macro_name", "normalize_macro_name"]
+
+# Characters BibDesk allows in a field/macro name. Built exactly as
+# `invalidCiteKeyCharSet` in `BDSKTypeManager.m` (which
+# `invalidFieldNameCharacterSet` aliases): start from printable ASCII
+# 32..125, then remove the BibTeX separators/specials. Everything outside
+# this set (control chars, `~`, and all non-ASCII) is invalid.
+_MACRO_NAME_CHARS = frozenset(chr(c) for c in range(32, 126)) - set(
+    " '\"@,\\#}{~%()="
+)
+
+
+def is_valid_macro_name(name, normalized=True):
+    r"""Return whether `name` is a valid BibDesk macro (`@string`) name.
+
+    ```python
+    is_valid_macro_name(name, normalized=True)
+    ```
+
+    Mirrors `-[BDSKMacroTextViewController isPartialStringValid:...]`: a
+    name is valid iff every character is in BibDesk's allowed set (printable
+    ASCII 32..125 minus the BibTeX separators/specials `` '"@,\#}{~%()=``
+    and the space character) and it does not begin with a decimal digit.
+
+    * `name`: the macro name to check.
+    * `normalized`: if `True` (default), `name` must additionally be
+      non-empty and already lowercase, i.e. in the canonical form produced
+      by {any}`normalize_macro_name`. If `False`, the empty string is
+      accepted (BibDesk permits it as an in-progress edit) and uppercase
+      letters are allowed.
+
+    ```python
+    >>> from bibdeskparser.macros import is_valid_macro_name
+    >>> is_valid_macro_name("pra")
+    True
+    >>> is_valid_macro_name("bad name")  # space is not allowed
+    False
+    >>> is_valid_macro_name("2pac")  # must not start with a digit
+    False
+    >>> is_valid_macro_name("PRA")  # not lowercase
+    False
+    >>> is_valid_macro_name("PRA", normalized=False)
+    True
+
+    ```
+    """
+    if any(ch not in _MACRO_NAME_CHARS for ch in name):
+        return False
+    if name and name[0].isascii() and name[0].isdigit():
+        return False
+    if normalized:
+        if not name:
+            return False
+        if name != name.lower():
+            return False
+    return True
+
+
+def normalize_macro_name(name):
+    """Return the BibDesk-canonical form of a macro name.
+
+    ```python
+    normalize_macro_name(name)
+    ```
+
+    BibDesk's macro editor forces names to lowercase as they are typed
+    (`*partialStringPtr = [partialString lowercaseString]`) while rejecting
+    any input that contains a disallowed character or starts with a digit.
+    This returns the lowercased name that BibDesk would store, matching its
+    case-insensitive macro table (`BDSKMacroResolver`), so two names that
+    differ only in case normalize to the same key.
+
+    * `name`: the macro name as written (e.g. from a parsed `@string`
+      block).
+
+    Raises {any}`ValueError` if `name` is empty or is not a valid macro
+    name according to {any}`is_valid_macro_name`.
+
+    ```python
+    >>> from bibdeskparser.macros import normalize_macro_name
+    >>> normalize_macro_name("PRA")
+    'pra'
+    >>> normalize_macro_name("pra")
+    'pra'
+    >>> normalize_macro_name("bad name")
+    Traceback (most recent call last):
+        ...
+    ValueError: invalid BibDesk macro name: 'bad name'
+
+    ```
+    """
+    if not name:
+        raise ValueError("macro name must not be empty")
+    if not is_valid_macro_name(name, normalized=False):
+        raise ValueError(f"invalid BibDesk macro name: {name!r}")
+    return name.lower()

bibdeskparser/middleware.py

@@ -0,0 +1,174 @@
+r"""Bibtexparser middlewares replicating BibDesk's read/write conversion.
+
+BibDesk normalizes `.bib` data when reading and writing: on *read*, TeX
+accents in field and `@string` values are decoded to Unicode
+(`detexify`), and `bdsk-file-N` field values are base64-encoded binary
+plists (see {any}`bibdeskparser.bdskfile.BibDeskFile`). On *write*,
+Unicode is re-encoded as TeX (`texify`). The `BibDesk Static Groups`
+`@comment` is not handled here: its body stays a plain string, which
+{any}`bibdeskparser.library.Library` decodes and re-encodes itself
+(see `bibdeskparser.groups`).
+
+This module packages those conversions as `bibtexparser` "block
+middleware" classes (see the
+[bibtexparser documentation](https://bibtexparser.readthedocs.io)).
+Use `parse_stack` to get the standard read stack:
+
+```python
+>>> import bibtexparser
+>>> from bibdeskparser.middleware import parse_stack
+>>> library = bibtexparser.parse_string(
+...     '@article{key1, author = {Gr{\\"u}n, Anna}}',
+...     parse_stack=parse_stack(),
+... )
+>>> library.entries[0]["author"]
+'{Grün, Anna}'
+
+```
+"""
+
+from bibtexparser.middlewares.middleware import BlockMiddleware
+
+from .bdskfile import BibDeskFile
+from .texmap import detexify, skip_texify, texify
+
+__all__ = []
+
+# All members whose name does not start with an underscore must be listed
+# either in __all__ or in __private__
+__private__ = [
+    "DeTeXifyMiddleware",
+    "TeXifyMiddleware",
+    "BibDeskFileMiddleware",
+    "parse_stack",
+]
+
+
+class DeTeXifyMiddleware(BlockMiddleware):
+    r"""Middleware converting TeX markup to Unicode (*read*).
+
+    ```python
+    DeTeXifyMiddleware(allow_inplace_modification=True)
+    ```
+
+    Applies `detexify` to every string field value of every entry
+    (e.g., `Gr{\"u}n` becomes `Grün`), and to the value of every
+    `@string` definition. Field keys for which `skip_texify` is `True`
+    (URL and `bdsk-file` fields) are left untouched, as are non-string
+    values.
+
+    This replicates the `-stringByDeTeXifyingString:` normalization
+    that BibDesk applies to every field value on read.
+
+    * `allow_inplace_modification`: if `True` (default), transform the
+      given library's blocks in place instead of copying them (see the
+      `bibtexparser` `Middleware` base class).
+    """
+
+    def transform_entry(self, entry, library):
+        """Detexify all string field values of `entry`."""
+        for field in entry.fields:
+            if not skip_texify(field.key) and isinstance(field.value, str):
+                field.value = detexify(field.value)
+        return entry
+
+    def transform_string(self, string, library):
+        """Detexify the value of the `@string` definition `string`."""
+        if isinstance(string.value, str):
+            string.value = detexify(string.value)
+        return string
+
+
+class TeXifyMiddleware(BlockMiddleware):
+    r"""Middleware converting Unicode to TeX markup (*write*).
+
+    ```python
+    TeXifyMiddleware(allow_inplace_modification=True)
+    ```
+
+    The mirror image of `DeTeXifyMiddleware`: applies `texify` to every
+    string field value of every entry (e.g., `Grün` becomes
+    `Gr{\"u}n`), and to the value of every `@string` definition. Field
+    keys for which `skip_texify` is `True` (URL and `bdsk-file` fields)
+    are left untouched, as are non-string values (such as
+    {any}`bibdeskparser.bdskfile.BibDeskFile` objects).
+
+    This replicates the `-stringByTeXifyingString:` normalization that
+    BibDesk applies to every field value on write. It is typically used
+    with `allow_inplace_modification=False` so that serializing a
+    library does not modify the caller's Unicode model.
+
+    * `allow_inplace_modification`: if `True` (default), transform the
+      given library's blocks in place instead of copying them (see the
+      `bibtexparser` `Middleware` base class).
+    """
+
+    def transform_entry(self, entry, library):
+        """Texify all string field values of `entry`."""
+        for field in entry.fields:
+            if not skip_texify(field.key) and isinstance(field.value, str):
+                field.value = texify(field.value)
+        return entry
+
+    def transform_string(self, string, library):
+        """Texify the value of the `@string` definition `string`."""
+        if isinstance(string.value, str):
+            string.value = texify(string.value)
+        return string
+
+
+class BibDeskFileMiddleware(BlockMiddleware):
+    """Middleware decoding `bdsk-file-N` field values (*read*).
+
+    ```python
+    BibDeskFileMiddleware(allow_inplace_modification=True)
+    ```
+
+    Replaces the string value of every field whose (lowercased) key
+    starts with `bdsk-file-` with the decoded
+    {any}`bibdeskparser.bdskfile.BibDeskFile` object. The writer
+    serializes such objects back via
+    {any}`bibdeskparser.bdskfile.BibDeskFile.to_field_value`, which is
+    byte-exact for unmodified attachments.
+
+    * `allow_inplace_modification`: if `True` (default), transform the
+      given library's blocks in place instead of copying them (see the
+      `bibtexparser` `Middleware` base class).
+    """
+
+    def transform_entry(self, entry, library):
+        """Decode all `bdsk-file-N` field values of `entry`."""
+        for field in entry.fields:
+            is_file_field = field.key.lower().startswith("bdsk-file-")
+            if is_file_field and isinstance(field.value, str):
+                field.value = BibDeskFile.from_field_value(field.value)
+        return entry
+
+
+def parse_stack():
+    """Return the standard middleware stack for reading BibDesk files.
+
+    ```python
+    parse_stack()
+    ```
+
+    Returns a list of fresh middleware instances,
+
+    ```python
+    [
+        DeTeXifyMiddleware(),
+        BibDeskFileMiddleware(),
+    ]
+    ```
+
+    suitable as the `parse_stack` argument of
+    `bibtexparser.parse_string` or `bibtexparser.parse_file`. Passing
+    an explicit stack (instead of `None`) also disables bibtexparser's
+    default middlewares, so values stay verbatim otherwise: `@string`
+    macros are not interpolated and enclosing braces are kept, exactly
+    like BibDesk's internal model.
+    """
+    return [
+        DeTeXifyMiddleware(),
+        BibDeskFileMiddleware(),
+    ]

bibdeskparser/names.py

@@ -0,0 +1,96 @@
+r"""Read-only structured view of person-name fields (`author`, `editor`).
+
+BibDesk stores the `author`/`editor` field as a flat, de-TeXified Unicode
+string, e.g. `"Goerz, Michael H and Calarco, Tommaso"`, and only *derives*
+a structured representation (first/von/last/Jr name parts) for display in
+its UI; it never re-serializes that structured view back to the field.
+This module mirrors that: `structured_names` builds a read-only
+`list` of `NameParts` on demand, using `bibtexparser`'s own name-splitting
+middlewares (`RemoveEnclosingMiddleware`, `SeparateCoAuthors`,
+`SplitNameParts`), run on a throwaway single-field `Entry` wrapped in a
+throwaway `bibtexparser.Library` so that the caller's real entry is never
+touched.
+
+`bibdeskparser` never uses this pipeline for *writing*: `bibtexparser`
+also provides a `MergeNameParts` middleware that goes the other way
+(`NameParts` -> string), but round-tripping through it is lossy. For
+example, a LaTeX tie in `Koch, C.~P.` would be rewritten as `Koch, C. P.`,
+silently losing the non-breaking space BibDesk's own editor preserves.
+So `author`/`editor` stay plain strings in the dict interface, and
+`structured_names` is only ever used to build the read-only
+`Entry.author`/`Entry.editor` properties.
+"""
+
+import bibtexparser
+from bibtexparser.middlewares import (
+    RemoveEnclosingMiddleware,
+    SeparateCoAuthors,
+    SplitNameParts,
+)
+from bibtexparser.model import Entry, Field
+
+__all__ = []
+
+# All members whose name does not start with an underscore must be listed
+# either in __all__ or in __private__
+__private__ = ["structured_names"]
+
+
+def structured_names(value, allow_inplace_modification=True):
+    r"""Parse a raw `author`/`editor` field value into structured names.
+
+    ```python
+    structured_names(value, allow_inplace_modification=True)
+    ```
+
+    * `value`: the raw field value string, e.g.
+      `"{Goerz, Michael H and Calarco, Tommaso}"` (with or without its
+      enclosing `{...}`/`"..."` delimiters) or `""`/`None` for a missing
+      field.
+    * `allow_inplace_modification`: passed through to the underlying
+      `bibtexparser` middlewares (see the `bibtexparser`
+      `Middleware` base class).
+
+    Returns a `list` of `bibtexparser.middlewares.names.NameParts`, each
+    with `.first`, `.von`, `.last`, `.jr` attributes (each a `list` of
+    strings), in the order the names appear in `value`. Returns `[]` if
+    `value` is empty or `None`.
+
+    This is a **read-only derived view**: BibDesk stores `author` and
+    `editor` as flat Unicode strings and only derives a structured
+    representation for display, so `bibdeskparser` never writes through
+    this pipeline (see the module docstring for why re-serializing via
+    `MergeNameParts` would be lossy).
+
+    ```python
+    >>> from bibdeskparser.names import structured_names
+    >>> names = structured_names(
+    ...     "Goerz, Michael H and Calarco, Tommaso and Koch, Christiane P"
+    ... )
+    >>> [n.last for n in names]
+    [['Goerz'], ['Calarco'], ['Koch']]
+    >>> names[0].first
+    ['Michael', 'H']
+    >>> structured_names("")
+    []
+    >>> structured_names(None)
+    []
+
+    ```
+    """
+    if not value:
+        return []
+    field = Field(key="author", value=value)
+    entry = Entry(entry_type="article", key="probe", fields=[field])
+    library = bibtexparser.Library([entry])
+    for middleware in (
+        RemoveEnclosingMiddleware(
+            allow_inplace_modification=allow_inplace_modification
+        ),
+        SeparateCoAuthors(
+            allow_inplace_modification=allow_inplace_modification
+        ),
+        SplitNameParts(allow_inplace_modification=allow_inplace_modification),
+    ):
+        library = middleware.transform(library)
+    return library.entries[0].fields_dict["author"].value