philoch-bib-sdk 0.3.9__cp313-cp313-win_amd64.whl

philoch_bib_sdk/converters/plaintext/author/parser.py

@@ -0,0 +1,83 @@
+import traceback
+from typing import Tuple
+from aletk.ResultMonad import Ok, Err
+from aletk.utils import get_logger, remove_extra_whitespace
+from philoch_bib_sdk.logic.models import Author, BibStringAttr, TBibString
+
+lgr = get_logger(__name__)
+
+
+def _parse_normalize(text: str) -> Tuple[str, str, str]:
+    """
+    Return a tuple of (given_name, family_name, mononym).
+
+    Handles formats:
+    - "Mononym" -> ("", "", "Mononym")
+    - "Family, Given" -> ("Given", "Family", "")
+    - "Family, Suffix, Given" -> ("Given", "Family Suffix", "")
+
+    Suffixes like Jr., Sr., III, etc. are combined with the family name.
+    """
+    parts = tuple(remove_extra_whitespace(part) for part in text.split(","))
+
+    if len(parts) == 0:
+        return ("", "", "")
+
+    elif len(parts) == 1:
+        # Mononym
+        return ("", "", parts[0])
+
+    elif len(parts) == 2:
+        # Full name: "Family, Given"
+        return (parts[1], parts[0], "")
+
+    elif len(parts) == 3:
+        # Full name with suffix: "Family, Suffix, Given"
+        # Combine family name and suffix (e.g., "Belnap Jr.")
+        family_with_suffix = f"{parts[0]} {parts[1]}"
+        return (parts[2], family_with_suffix, "")
+
+    else:
+        raise ValueError(f"Unexpected number of author parts found in '{text}': '{parts}'. Expected 3 or less.")
+
+
+def _parse_single(normalized_name_parts: Tuple[str, str, str], bib_string_type: TBibString) -> Author:
+    """
+    Parse a single author from a string.
+    """
+    _given_name, _family_name, _mononym = normalized_name_parts
+
+    return Author(
+        given_name=BibStringAttr(**{str(bib_string_type): _given_name}),
+        family_name=BibStringAttr(**{str(bib_string_type): _family_name}),
+        mononym=BibStringAttr(**{str(bib_string_type): _mononym}),
+        shorthand=BibStringAttr(),
+        famous_name=BibStringAttr(),
+        publications=(),
+    )
+
+
+def parse_author(text: str, bibstring_type: TBibString) -> Ok[Tuple[Author, ...]] | Err:
+    """
+    Return either a tuple of Author objects or an error.
+    The input string is expected to be an ' and '-separated list of authors, with each author in the format "family_name, given_name" or "mononym".
+    """
+    try:
+        if text == "":
+            lgr.debug("Empty author string, returning empty tuple.")
+            return Ok(())
+
+        parts = tuple(remove_extra_whitespace(part) for part in text.split("and"))
+        parts_normalized = (_parse_normalize(part) for part in parts)
+
+        authors = tuple(_parse_single(part, bibstring_type) for part in parts_normalized)
+
+        return Ok(authors)
+
+    except Exception as e:
+        return Err(
+            message=f"Could not parse 'author' field with value [[ {text} ]]. {e.__class__.__name__}: {e}",
+            code=-1,
+            error_type="ParsingError",
+            error_trace=f"{traceback.format_exc()}",
+        )

philoch_bib_sdk/converters/plaintext/bib_string_formatter.py

@@ -0,0 +1,8 @@
+from philoch_bib_sdk.logic.models import BibStringAttr, MaybeStr, TBibString
+
+
+def format_bib_string_attr(bib_string: MaybeStr[BibStringAttr], bibstring_type: TBibString) -> str:
+    """
+    Format a BibStringAttr into a string representation.
+    """
+    return "" if not bib_string else getattr(bib_string, bibstring_type, "")

philoch_bib_sdk/converters/plaintext/bibitem/bibkey_formatter.py

@@ -0,0 +1,21 @@
+from philoch_bib_sdk.logic.models import BibKeyAttr, MaybeStr
+
+
+def format_bibkey(bibkey: MaybeStr[BibKeyAttr]) -> str:
+
+    if bibkey == "":
+        return ""
+
+    if bibkey.other_authors:
+        authors_l = [bibkey.first_author, bibkey.other_authors]
+    else:
+        authors_l = [bibkey.first_author]
+
+    authors = "-".join(authors_l)
+
+    if isinstance(bibkey.date, int):
+        year = f"{bibkey.date}{bibkey.date_suffix}"
+    else:
+        year = f"{bibkey.date}-{bibkey.date_suffix}" if bibkey.date_suffix else bibkey.date
+
+    return f"{authors}:{year}"

philoch_bib_sdk/converters/plaintext/bibitem/bibkey_parser.py

@@ -0,0 +1,158 @@
+import traceback
+from typing import Tuple
+from aletk.ResultMonad import Ok, Err
+from aletk.utils import get_logger
+from philoch_bib_sdk.logic.literals import TBasicPubState
+from philoch_bib_sdk.logic.models import BibKeyAttr
+
+lgr = get_logger(__name__)
+
+
+def _parse_bibkey_author(text: str) -> Tuple[str, str]:
+
+    author_parts = text.split("-")
+
+    if len(author_parts) == 1:
+        first_author = author_parts[0]
+        other_authors = ""
+    elif len(author_parts) == 2:
+        first_author = author_parts[0]
+        other_authors = author_parts[1]
+    else:
+        raise ValueError(
+            f"Unexpected bibkey author parts in [[ {text} ]]. Found [[ {author_parts} ]]. Expected 1 author, or 2 authors separated by '-'."
+        )
+
+    return first_author, other_authors
+
+
+def _parse_bibkey_date_int_part(text: str) -> Tuple[int | None, int | None]:
+
+    char_index_type_d = {i: (char, char.isdigit()) for i, char in enumerate(text)}
+
+    year_l: list[str] = []
+    int_breakpoint = None
+    for i, (char, is_digit) in char_index_type_d.items():
+        if is_digit:
+            year_l.append(char)
+            int_breakpoint = i
+        else:
+            break
+
+    if year_l != []:
+        year_int = int(f"{''.join(year_l)}")
+    else:
+        year_int = None
+
+    if year_int and len(f"{year_int}") > 4:
+        raise ValueError(f"Unexpected year value in '{text}': is not a valid year or publication state")
+
+    return year_int, int_breakpoint
+
+
+def _parse_bibkey_date_suffix_part(
+    date_parts: str, year_int: int | None, int_breakpoint: int | None
+) -> Tuple[int | TBasicPubState, str]:
+
+    # Case 1. The first part of the year is a digit
+    if int_breakpoint is not None:
+        if year_int is None:
+            raise ValueError(
+                f"Unexpected case! year_int is None but int_breakpoint is not None. This should not happen."
+            )
+
+        date_suffix_raw = date_parts[int_breakpoint + 1 :]
+        return (
+            year_int,
+            date_suffix_raw,
+        )
+
+    if year_int is not None:
+        raise ValueError(f"Unexpected case! year_int is None but int_breakpoint is not None. This should not happen.")
+
+    # Case 2. first characters are non-digits
+    # has to start with either "unpub" or "forthcoming" then
+    date_suffix_raw = "".join(date_parts)
+
+    if not (date_suffix_raw.startswith("forthcoming") or date_suffix_raw.startswith("unpub")):
+        raise ValueError(f"Unexpected year value in '{date_parts}': it is not a valid publication state.")
+
+    date_suffix_parts = date_suffix_raw.split("-")
+
+    if len(date_suffix_parts) == 2:
+        suffix = date_suffix_parts[1]
+        if not suffix:
+            raise ValueError(
+                f"Unexpected year value in '{date_parts}': it is not a valid publication state. Expected a suffix after '-'."
+            )
+    elif len(date_suffix_parts) == 1:
+        suffix = ""
+    else:
+        raise ValueError(f"Unexpected year value in '{date_parts}': it is not a valid publication state.")
+
+    pubstate: TBasicPubState = ""
+    if date_suffix_parts[0] == "unpub":
+        pubstate = "unpub"
+    elif date_suffix_parts[0] == "forthcoming":
+        pubstate = "forthcoming"
+    else:
+        raise ValueError(f"Unexpected year value in '{date_parts}': it is not a valid publication state.")
+
+    return pubstate, suffix
+
+
+def parse_bibkey(text: str) -> Ok[BibKeyAttr] | Err:
+    """
+    Return either a Bibkey object, or a BibkeyError object to indicate a parsing error.
+    """
+
+    try:
+        bibkey_parts = text.split(":")
+        if len(bibkey_parts) != 2:
+            raise ValueError(
+                f"Unexpected number of bibkey parts in [[ {text} ]]. Expected only two parts separated by ':'."
+            )
+
+        # Parse the author part
+        first_author, other_authors = _parse_bibkey_author(bibkey_parts[0])
+
+        # Parse the date part
+        date_parts = bibkey_parts[1]
+
+        year_int, int_breakpoint = _parse_bibkey_date_int_part(date_parts)
+
+        # Parse the date suffix part
+        date, date_suffix = _parse_bibkey_date_suffix_part(date_parts, year_int, int_breakpoint)
+
+        return Ok(
+            BibKeyAttr(
+                first_author=first_author,
+                other_authors=other_authors,
+                date=date,
+                date_suffix=date_suffix,
+            )
+        )
+
+    except Exception as e:
+        error_message = f"Could not parse bibkey for '{text}'"
+
+        return Err(
+            message=error_message,
+            code=-1,
+            error_type="BibkeyError",
+            error_trace=f"{traceback.format_exc()}",
+        )
+
+
+def hard_parse_bibkey(text: str) -> BibKeyAttr:
+    """
+    Hard parse a bibkey, without any error handling.
+    This is used for testing purposes only.
+    """
+
+    bibkey_parsed = parse_bibkey(text)
+
+    if isinstance(bibkey_parsed, Err):
+        raise ValueError(f"Could not hard parse '{text}' as bibkey: {bibkey_parsed.message}")
+
+    return bibkey_parsed.out

philoch_bib_sdk/converters/plaintext/bibitem/date_formatter.py

@@ -0,0 +1,37 @@
+from typing import Literal
+from philoch_bib_sdk.logic.models import VALID_DATE_FORMATS, BibItemDateAttr
+
+
+def format_date(date: BibItemDateAttr | Literal["no date"]) -> str:
+
+    if date == "no date":
+        return "no date"
+
+    match date:
+        case BibItemDateAttr(year=year, year_part_2_hyphen=None, year_part_2_slash=None, month=None, day=None):
+            return str(year)
+
+        case BibItemDateAttr(year=year, year_part_2_hyphen=None, year_part_2_slash=None, month=month, day=day) if (
+            month is not None and day is not None
+        ):
+            return f"{year}-{str(month).zfill(2)}-{str(day).zfill(2)}"
+
+        case BibItemDateAttr(year=year, year_part_2_hyphen=None, year_part_2_slash=None, month=month, day=None) if (
+            month is not None
+        ):
+            return f"{year}-{str(month).zfill(2)}"
+
+        case BibItemDateAttr(
+            year=year, year_part_2_hyphen=year_part_2_hyphen, year_part_2_slash=None, month=None, day=None
+        ) if (year_part_2_hyphen is not None):
+            return f"{year}-{year_part_2_hyphen}"
+
+        case BibItemDateAttr(
+            year=year, year_part_2_hyphen=None, year_part_2_slash=year_part_2_slash, month=None, day=None
+        ) if (year_part_2_slash is not None):
+            return f"{year}/{year_part_2_slash}"
+
+        case _:
+            raise ValueError(
+                f"Invalid date format. Expected one of {', '.join(VALID_DATE_FORMATS)}, but found '{date}'."
+            )

philoch_bib_sdk/converters/plaintext/bibitem/date_parser.py

@@ -0,0 +1,62 @@
+from aletk.utils import remove_extra_whitespace, get_logger
+from aletk.ResultMonad import Ok, Err
+from typing import Literal
+from philoch_bib_sdk.logic.models import VALID_DATE_FORMATS, BibItemDateAttr
+
+
+lgr = get_logger(__name__)
+
+
+def _parse_date(text: str) -> BibItemDateAttr | Literal["no date"]:
+    """
+    Parse a single date attribute from a string.
+    """
+    text = remove_extra_whitespace(text)
+
+    if remove_extra_whitespace(text).lower() == "no date":
+        return "no date"
+
+    # Split by potential delimiters (hyphens or slashes)
+    parts = text.replace("-", "/").split("/")
+
+    # Handle the number of parts (could be year, year-year2, year/year_2, year-month-day)
+    if len(parts) == 1:
+        return BibItemDateAttr(
+            year=int(parts[0]), year_part_2_hyphen=None, year_part_2_slash=None, month=None, day=None
+        )
+
+    elif len(parts) == 2 and "-" in text:
+        return BibItemDateAttr(
+            year=int(parts[0]), year_part_2_hyphen=int(parts[1]), year_part_2_slash=None, month=None, day=None
+        )
+
+    elif len(parts) == 2 and "/" in text:
+        return BibItemDateAttr(
+            year=int(parts[0]), year_part_2_hyphen=None, year_part_2_slash=int(parts[1]), month=None, day=None
+        )
+
+    elif len(parts) == 3 and "-" in text and len(parts[1]) <= 2 and len(parts[2]) <= 2:
+        return BibItemDateAttr(
+            year=int(parts[0]), year_part_2_hyphen=None, year_part_2_slash=None, month=int(parts[1]), day=int(parts[2])
+        )
+
+    else:
+        raise ValueError(f"Invalid date format found in '{text}'. Expected one of {', '.join(VALID_DATE_FORMATS)}.")
+
+
+def parse_date(text: str) -> Ok[BibItemDateAttr | Literal["no date"]] | Err:
+    """
+    Parse a single date string into a BibItemDateAttr object.
+    The input is expected to be a single date, either in the format '<year>' or '<year>-<month>' or '<year>-<month>-<day>' (or slashes instead of hyphens).
+    """
+    try:
+        return Ok(_parse_date(text))
+
+    except Exception as e:
+        error_message = f"Error parsing date from '{text}': {e}"
+        return Err(
+            message=error_message,
+            code=-1,
+            error_type=f"{e.__class__.__name__}",
+            error_trace="",
+        )

philoch_bib_sdk/converters/plaintext/bibitem/formatter.py

@@ -0,0 +1,182 @@
+from typing import TypedDict
+from aletk.utils import get_logger
+
+from philoch_bib_sdk.converters.plaintext.author.formatter import format_author
+from philoch_bib_sdk.converters.plaintext.bib_string_formatter import format_bib_string_attr
+from philoch_bib_sdk.converters.plaintext.bibitem.bibkey_formatter import format_bibkey
+from philoch_bib_sdk.converters.plaintext.bibitem.date_formatter import format_date
+from philoch_bib_sdk.converters.plaintext.bibitem.pages_formatter import format_pages
+from philoch_bib_sdk.converters.plaintext.journal.formatter import format_journal
+from philoch_bib_sdk.logic.literals import TBibTeXEntryType
+from philoch_bib_sdk.logic.models import BibItem
+
+
+lgr = get_logger(__name__)
+
+
+def format_entry_type(entry_type: TBibTeXEntryType) -> str:
+    """
+    Format the entry type for the BibItem.
+    """
+    match entry_type:
+        case "UNKNOWN":
+            return "UNKNOWN"
+        case _ if entry_type:
+            return f"@{entry_type}"
+        case _:
+            return ""
+
+
+class FormattedBibItem(TypedDict, total=True):
+    _to_do_general: str
+    _change_request: str
+    entry_type: str
+    bibkey: str
+    author: str
+    _author_ids: str
+    editor: str
+    _editor_ids: str
+    author_ids: str
+    options: str
+    shorthand: str
+    date: str
+    pubstate: str
+    title: str
+    _title_unicode: str
+    booktitle: str
+    crossref: str
+    journal: str
+    journal_id: str
+    volume: str
+    number: str
+    pages: str
+    eid: str
+    series: str
+    address: str
+    institution: str
+    school: str
+    publisher: str
+    publisher_id: str
+    type: str
+    edition: str
+    note: str
+    _issuetitle: str
+    _guesteditor: str
+    _extra_note: str
+    urn: str
+    eprint: str
+    doi: str
+    url: str
+    _kw_level1: str
+    _kw_level2: str
+    _kw_level3: str
+    _epoch: str
+    _person: str
+    _comm_for_profile_bib: str
+    _langid: str
+    _lang_der: str
+    _further_refs: str
+    _depends_on: str
+    _dltc_num: str
+    _spec_interest: str
+    _note_perso: str
+    _note_stock: str
+    _note_status: str
+    _num_inwork_coll: str
+    _num_inwork: str
+    _num_coll: str
+    _dltc_copyediting_note: str
+    _note_missing: str
+    _num_sort: str
+
+
+def format_bibitem(bibitem: BibItem) -> FormattedBibItem:
+
+    bibkey = format_bibkey(bibitem.bibkey)
+
+    author = format_author(bibitem.author, "latex")
+    editor = format_author(bibitem.editor, "latex")
+    person = format_author((bibitem._person,), "latex") if bibitem._person else ""
+
+    shorthand = ", ".join([author.mononym.latex for author in bibitem.author if author.mononym.latex])
+    date = format_date(bibitem.date)
+
+    pages = format_pages(bibitem.pages)
+
+    journal = format_journal(bibitem.journal, "latex")
+
+    crossref = format_bibkey(bibitem.crossref.bibkey) if bibitem.crossref else ""
+
+    _kw_level1, kw_level2, kw_level3 = (
+        bibitem._kws.level_1.name if bibitem._kws else "",
+        bibitem._kws.level_2.name if bibitem._kws else "",
+        bibitem._kws.level_3.name if bibitem._kws else "",
+    )
+
+    further_refs = ", ".join([format_bibkey(ref) for ref in bibitem._further_refs])
+    depends_on = ", ".join([format_bibkey(dep) for dep in bibitem._depends_on])
+
+    formatted: FormattedBibItem = {
+        "_to_do_general": bibitem._to_do_general,
+        "_change_request": bibitem._change_request,
+        "entry_type": format_entry_type(bibitem.entry_type),
+        "bibkey": bibkey,
+        "author": author,
+        "_author_ids": "",
+        "editor": editor,
+        "_editor_ids": "",
+        "author_ids": "",
+        "options": ", ".join(bibitem.options),
+        "shorthand": shorthand,
+        "date": date,
+        "pubstate": bibitem.pubstate,
+        "title": format_bib_string_attr(bibitem.title, "latex"),
+        "_title_unicode": format_bib_string_attr(bibitem.title, "unicode"),
+        "booktitle": format_bib_string_attr(bibitem.booktitle, "latex"),
+        "crossref": crossref,
+        "journal": journal,
+        "journal_id": "",
+        "volume": bibitem.volume,
+        "number": bibitem.number,
+        "pages": pages,
+        "eid": bibitem.eid,
+        "series": format_bib_string_attr(bibitem.series.name, "latex") if bibitem.series else "",
+        "address": format_bib_string_attr(bibitem.address, "latex"),
+        "institution": format_bib_string_attr(bibitem.institution, "latex"),
+        "school": format_bib_string_attr(bibitem.school, "latex"),
+        "publisher": format_bib_string_attr(bibitem.publisher, "latex"),
+        "publisher_id": "",
+        "type": format_bib_string_attr(bibitem.type, "latex"),
+        "edition": str(bibitem.edition) if bibitem.edition is not None else "",
+        "note": format_bib_string_attr(bibitem.note, "latex"),
+        "_issuetitle": format_bib_string_attr(bibitem.issuetitle, "latex") if bibitem.issuetitle else "",
+        "_guesteditor": ", ".join(format_author(tuple(author for author in bibitem._guesteditor), "latex")),
+        "_extra_note": format_bib_string_attr(bibitem._extra_note, "latex") if bibitem._extra_note else "",
+        "urn": bibitem.urn,
+        "eprint": bibitem.eprint,
+        "doi": bibitem.doi,
+        "url": bibitem.url,
+        "_kw_level1": _kw_level1,
+        "_kw_level2": kw_level2,
+        "_kw_level3": kw_level3,
+        "_epoch": bibitem._epoch,
+        "_person": person,
+        "_comm_for_profile_bib": bibitem._comm_for_profile_bib,
+        "_langid": bibitem._langid,
+        "_lang_der": bibitem._lang_der,
+        "_further_refs": further_refs,
+        "_depends_on": depends_on,
+        "_dltc_num": str(bibitem._dltc_num) if bibitem._dltc_num is not None else "",
+        "_spec_interest": bibitem._spec_interest,
+        "_note_perso": bibitem._note_perso,
+        "_note_stock": bibitem._note_stock,
+        "_note_status": bibitem._note_status,
+        "_num_inwork_coll": str(bibitem._num_inwork_coll) if bibitem._num_inwork_coll is not None else "",
+        "_num_inwork": bibitem._num_inwork,
+        "_num_coll": str(bibitem._num_coll) if bibitem._num_coll is not None else "",
+        "_dltc_copyediting_note": bibitem._dltc_copyediting_note,
+        "_note_missing": bibitem._note_missing,
+        "_num_sort": str(bibitem._num_sort) if bibitem._num_sort is not None else "",
+    }
+
+    return formatted

philoch_bib_sdk/converters/plaintext/bibitem/pages_formatter.py

@@ -0,0 +1,13 @@
+from typing import Tuple
+from philoch_bib_sdk.logic.models import PageAttr
+
+
+def _pages_single_str(page_pair: PageAttr) -> str:
+    return "--".join((page_pair.start, page_pair.end)) if page_pair.end else page_pair.start
+
+
+def format_pages(pages: Tuple[PageAttr, ...]) -> str:
+    if pages is tuple():
+        return ""
+
+    return ", ".join((_pages_single_str(page_pair) for page_pair in pages))

philoch_bib_sdk/converters/plaintext/bibitem/pages_parser.py

@@ -0,0 +1,63 @@
+import re
+import traceback
+from typing import Tuple
+from aletk.utils import remove_extra_whitespace
+from aletk.ResultMonad import Ok, Err
+
+from philoch_bib_sdk.logic.models import PageAttr
+
+
+def is_valid_roman(raw_str: str) -> bool:
+    """
+    TODO: TBD, decide if we want to control if the pages are in roman numbers.
+    """
+    raw_str = raw_str.upper()
+    pattern = r"^M{0,3}(CM|CD|D?C{0,3})(XC|XL|L?X{0,3})(IX|IV|V?I{0,3})$"
+    return bool(re.match(pattern, raw_str))
+
+
+def _parse_single_page_attr(
+    text: str,
+) -> PageAttr:
+    """
+    Parse a single page attribute from a string.
+    """
+    if "--" not in text and "-" in text:
+        raise ValueError(f"Unexpected page format found in '{text}'. Expected either '<start>--<end>' or '<page>'.")
+    elif "--" in text:
+        parts = remove_extra_whitespace(text).split("--")
+
+        if len(parts) != 2:
+            raise ValueError(f"Unexpected number of page parts found in '{text}': '{parts}'. Expected exactly 2.")
+
+        start_page, end_page = (remove_extra_whitespace(part) for part in parts)
+
+    else:
+        start_page = remove_extra_whitespace(text)
+        end_page = ""
+
+    return PageAttr(start=start_page, end=end_page)
+
+
+def parse_pages(text: str) -> Ok[Tuple[PageAttr, ...]] | Err:
+    """
+    Parse a string of pages into a tuple of PageAttr objects.
+    The input string is expected to be a comma-separated list of page attributes, with each attribute in the format "<start>--<end>" or "<page>".
+    """
+    try:
+        if text == "":
+            return Ok(())
+
+        parts = (remove_extra_whitespace(part) for part in text.split(","))
+        parts_normalized = (_parse_single_page_attr(part) for part in parts)
+
+        return Ok(tuple(parts_normalized))
+
+    except Exception as e:
+        error_message = f"Error parsing pages from '{text}': {e}"
+        return Err(
+            error_message,
+            code=-1,
+            error_type=f"{e.__class__.__name__}",
+            error_trace=traceback.format_exc(),
+        )