philoch-bib-sdk 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

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(),
+        )

philoch_bib_sdk/converters/plaintext/bibitem/parser.py

@@ -0,0 +1,3 @@
+from aletk.utils import get_logger
+
+lgr = get_logger(__name__)

philoch_bib_sdk/converters/plaintext/journal/formatter.py

@@ -0,0 +1,25 @@
+from aletk.utils import get_logger
+from philoch_bib_sdk.logic.models import Journal, Maybe, TBibString
+
+lgr = get_logger(__name__)
+
+
+def format_journal(journal: Maybe[Journal], bibstring_type: TBibString) -> str:
+    """
+    Format a journal object into a string representation.
+    """
+
+    match journal:
+
+        case None:
+            return ""
+
+        case Journal(name, id):
+
+            if not name:
+                return ""
+
+            return f"{getattr(name, bibstring_type)}"
+
+        case _:
+            raise TypeError(f"Invalid type for journal: {type(journal)}. Dump: {journal!r}")

philoch_bib_sdk/converters/plaintext/journal/parser.py

@@ -0,0 +1,36 @@
+import traceback
+from aletk.ResultMonad import Ok, Err
+from aletk.utils import get_logger, remove_extra_whitespace
+from philoch_bib_sdk.logic.models import Journal, BibStringAttr, TBibString
+
+lgr = get_logger(__name__)
+
+
+def parse_journal(text: str, bibstring_type: TBibString) -> Ok[Journal | None] | Err:
+    """
+    Parse a journal string into a Journal object.
+    """
+    try:
+        if text == "":
+            lgr.debug("Empty journal string, returning None.")
+            return Ok(None)
+
+        # Normalize the text by removing extra whitespace
+        normalized_text = remove_extra_whitespace(text)
+
+        journal = Journal(
+            name=BibStringAttr(**{str(bibstring_type): normalized_text}),
+            issn_electronic="",
+            issn_print="",
+        )
+
+        return Ok(journal)
+
+    except Exception as e:
+        error_message = f"Error parsing journal string '{text}': {e}"
+        return Err(
+            message=error_message,
+            code=-1,
+            error_type=f"{e.__class__.__name__}",
+            error_trace=traceback.format_exc(),
+        )

philoch_bib_sdk/converters/plaintext/shared/renderable_formatter.py

@@ -0,0 +1,25 @@
+from philoch_bib_sdk.logic.models import BaseRenderable, BaseNamedRenderable, TBibString
+
+
+def format_renderable(
+    renderable: BaseRenderable | BaseNamedRenderable,
+    bibstring_type: TBibString,
+) -> str:
+    """
+    Format a base renderable object into a string representation.
+    """
+
+    match renderable:
+
+        case BaseRenderable(text, id):
+            if not text:
+                return ""
+            return f"{getattr(text, bibstring_type)}"
+
+        case BaseNamedRenderable(name, id):
+            if not name:
+                return ""
+            return f"{getattr(name, bibstring_type)}"
+
+        case _:
+            raise TypeError("Invalid type for renderable")

philoch_bib_sdk/logic/default_models.py

@@ -0,0 +1,315 @@
+from typing import Tuple, TypedDict, Unpack, Literal
+from philoch_bib_sdk.logic.models import BibItem, PageAttr, KeywordsAttr, BibItemDateAttr, BibKeyAttr, Keyword
+
+from philoch_bib_sdk.logic.literals import TBasicPubState, TBibTeXEntryType, TEpoch, TLanguageID, TPubState
+from philoch_bib_sdk.logic.models import (
+    Author,
+    BaseNamedRenderable,
+    BaseRenderable,
+    BibItem,
+    BibStringAttr,
+    Journal,
+    Keyword,
+)
+
+
+class BibStringArgs(TypedDict, total=False):
+    latex: str
+    unicode: str
+    simplified: str
+
+
+def default_bib_string(**kwargs: Unpack[BibStringArgs]) -> BibStringAttr:
+    """
+    Create a default BibString object, given a dictionary with any (or None) of its attributes. Defaults to empty strings if not provided.
+    """
+    return BibStringAttr(
+        latex=kwargs.get("latex", ""),
+        unicode=kwargs.get("unicode", ""),
+        simplified=kwargs.get("simplified", ""),
+    )
+
+
+############
+# Base Renderables
+############
+
+
+class BaseRenderableArgs(TypedDict, total=False):
+    text: BibStringArgs
+    id: int | None
+
+
+def default_base_renderable(**kwargs: Unpack[BaseRenderableArgs]) -> BaseRenderable:
+    """
+    Create a default BaseRenderable object, given a dictionary with any (or None) of its attributes. Defaults to empty strings if not provided.
+    """
+    return BaseRenderable(
+        text=default_bib_string(**kwargs.get("text", {})),
+        id=kwargs.get("id", None),
+    )
+
+
+class BaseNamedRenderableArgs(TypedDict, total=False):
+    name: BibStringArgs
+    id: int | None
+
+
+def default_base_named_renderable(**kwargs: Unpack[BaseNamedRenderableArgs]) -> BaseNamedRenderable:
+    """
+    Create a default BaseNamedRenderable object, given a dictionary with any (or None) of its attributes. Defaults to empty strings if not provided.
+    """
+    return BaseNamedRenderable(
+        name=default_bib_string(**kwargs.get("name", {})),
+        id=kwargs.get("id", None),
+    )
+
+
+############
+# Author
+############
+
+
+class AuthorArgs(TypedDict, total=False):
+    given_name: BibStringArgs
+    family_name: BibStringArgs
+    mononym: BibStringArgs
+    shorthand: BibStringArgs
+    famous_name: BibStringArgs
+    publications: Tuple[BibItem, ...]
+    id: int | None
+
+
+def default_author(**kwargs: Unpack[AuthorArgs]) -> Author:
+    """
+    Create a default Author object, given a dictionary with any (or None) of its attributes. Defaults to empty strings and an empty tuple for publications if not provided.
+    """
+
+    return Author(
+        given_name=default_bib_string(**kwargs.get("given_name", {})),
+        family_name=default_bib_string(**kwargs.get("family_name", {})),
+        mononym=default_bib_string(**kwargs.get("mononym", {})),
+        shorthand=default_bib_string(**kwargs.get("shorthand", {})),
+        famous_name=default_bib_string(**kwargs.get("famous_name", {})),
+        publications=kwargs.get("publications", ()),
+        id=kwargs.get("id", None),
+    )
+
+
+############
+# Journal
+############
+
+
+class JournalArgs(TypedDict, total=False):
+    name: BibStringArgs
+    issn_print: str
+    issn_electronic: str
+    id: int | None
+
+
+def default_journal(**kwargs: Unpack[JournalArgs]) -> Journal | None:
+    """
+    Create a default Journal object, given a dictionary with any (or None) of its attributes. Defaults to empty strings if not provided.
+    """
+    if kwargs == {}:
+        return None
+
+    return Journal(
+        name=default_bib_string(**kwargs.get("name", {})),
+        issn_print=kwargs.get("issn_print", ""),
+        issn_electronic=kwargs.get("issn_electronic", ""),
+        id=kwargs.get("id", None),
+    )
+
+
+############
+# Support Args
+############
+
+
+class PageArgs(TypedDict, total=False):
+    start: str
+    end: str
+
+
+def default_page(**kwargs: Unpack[PageArgs]) -> PageAttr:
+    return PageAttr(
+        start=kwargs.get("start", ""),
+        end=kwargs.get("end", ""),
+    )
+
+
+class KeywordsArgs(TypedDict, total=False):
+    level_1: str
+    level_2: str
+    level_3: str
+
+
+def default_keywords(**kwargs: Unpack[KeywordsArgs]) -> KeywordsAttr:
+    return KeywordsAttr(
+        level_1=Keyword(name=kwargs.get("level_1", "")),
+        level_2=Keyword(name=kwargs.get("level_2", "")),
+        level_3=Keyword(name=kwargs.get("level_3", "")),
+    )
+
+
+class BibItemDateArgs(TypedDict, total=False):
+    year: int
+    year_part_2_hyphen: int | None
+    year_part_2_slash: int | None
+    month: int | None
+    day: int | None
+
+
+def default_bib_item_date(**kwargs: Unpack[BibItemDateArgs]) -> BibItemDateAttr:
+    return BibItemDateAttr(
+        year=kwargs.get("year", 0),
+        year_part_2_hyphen=kwargs.get("year_part_2_hyphen"),
+        year_part_2_slash=kwargs.get("year_part_2_slash"),
+        month=kwargs.get("month"),
+        day=kwargs.get("day"),
+    )
+
+
+def parse_date(date: BibItemDateArgs | Literal["no date"]) -> BibItemDateAttr | Literal["no date"]:
+    if isinstance(date, dict):
+        return default_bib_item_date(**date)
+    else:
+        return "no date"
+
+
+class BibKeyArgs(TypedDict, total=False):
+    first_author: str
+    other_authors: str
+    date: int | TBasicPubState
+    date_suffix: str
+
+
+def default_bib_key(**kwargs: Unpack[BibKeyArgs]) -> BibKeyAttr:
+    # Then pass to BibKeyAttr
+    return BibKeyAttr(
+        first_author=kwargs.get("first_author", ""),
+        other_authors=kwargs.get("other_authors", ""),
+        date=kwargs.get("date", ""),
+        date_suffix=kwargs.get("date_suffix", ""),
+    )
+
+
+############
+# BibItem Args
+############
+
+
+class BibItemArgs(TypedDict, total=False):
+    _to_do_general: str
+    _change_request: str
+    entry_type: TBibTeXEntryType
+    bibkey: BibKeyArgs
+    author: Tuple[AuthorArgs, ...]
+    editor: Tuple[AuthorArgs, ...]
+    options: Tuple[str, ...]
+    date: BibItemDateArgs | Literal["no date"]
+    pubstate: TPubState
+    title: BibStringArgs
+    booktitle: BibStringArgs
+    #    crossref: dict
+    journal: JournalArgs
+    volume: str
+    number: str
+    pages: Tuple[PageArgs, ...]
+    eid: str
+    series: BaseNamedRenderableArgs
+    address: BibStringArgs
+    institution: BibStringArgs
+    school: BibStringArgs
+    publisher: BibStringArgs
+    type: BibStringArgs
+    edition: int
+    note: BibStringArgs
+    issuetitle: BibStringArgs
+    _guesteditor: Tuple[AuthorArgs, ...]
+    _extra_note: BibStringArgs
+    urn: str
+    eprint: str
+    doi: str
+    url: str
+    _kws: KeywordsArgs
+    _epoch: TEpoch
+    _person: AuthorArgs
+    _comm_for_profile_bib: str
+    _langid: TLanguageID
+    _lang_der: str
+    _further_refs: Tuple[BibKeyArgs, ...]
+    _depends_on: Tuple[BibKeyArgs, ...]
+    _dltc_num: int
+    _spec_interest: str
+    _note_perso: str
+    _note_stock: str
+    _note_status: str
+    _num_inwork_coll: int
+    _num_inwork: str
+    _num_coll: int
+    _dltc_copyediting_note: str
+    _note_missing: str
+    _num_sort: int
+    id: int
+    _bib_info_source: str
+
+
+def default_bib_item(**kwargs: Unpack[BibItemArgs]) -> BibItem:
+    return BibItem(
+        to_do_general=kwargs.get("_to_do_general", ""),
+        change_request=kwargs.get("_change_request", ""),
+        entry_type=kwargs.get("entry_type", "UNKNOWN"),
+        bibkey=default_bib_key(**kwargs.get("bibkey", {})) if "bibkey" in kwargs else "",
+        author=tuple(default_author(**a) for a in kwargs.get("author", ())),
+        editor=tuple(default_author(**e) for e in kwargs.get("editor", ())),
+        options=kwargs.get("options", ()),
+        date=parse_date(kwargs.get("date", "no date")),
+        pubstate=kwargs.get("pubstate", ""),
+        title=default_bib_string(**kwargs.get("title", {})) if "title" in kwargs else "",
+        booktitle=default_bib_string(**kwargs.get("booktitle", {})) if "booktitle" in kwargs else "",
+        crossref="",  # Crossref is not defined in the provided context, so we leave it as an empty string
+        journal=default_journal(**kwargs.get("journal", {})) if "journal" in kwargs else None,
+        volume=kwargs.get("volume", ""),
+        number=kwargs.get("number", ""),
+        pages=tuple(default_page(**p) for p in kwargs.get("pages", ())),
+        eid=kwargs.get("eid", ""),
+        series=default_base_named_renderable(**kwargs.get("series", {})) if "series" in kwargs else "",
+        address=default_bib_string(**kwargs.get("address", {})) if "address" in kwargs else "",
+        institution=default_bib_string(**kwargs.get("institution", {})) if "institution" in kwargs else "",
+        school=default_bib_string(**kwargs.get("school", {})) if "school" in kwargs else "",
+        publisher=default_bib_string(**kwargs.get("publisher", {})) if "publisher" in kwargs else "",
+        type=default_bib_string(**kwargs.get("type", {})) if "type" in kwargs else "",
+        edition=kwargs.get("edition"),
+        note=default_bib_string(**kwargs.get("note", {})) if "note" in kwargs else "",
+        issuetitle=default_bib_string(**kwargs.get("issuetitle", {})) if "issuetitle" in kwargs else "",
+        guesteditor=tuple(default_author(**a) for a in kwargs.get("_guesteditor", ())),
+        extra_note=default_bib_string(**kwargs.get("_extra_note", {})) if "_extra_note" in kwargs else "",
+        urn=kwargs.get("urn", ""),
+        eprint=kwargs.get("eprint", ""),
+        doi=kwargs.get("doi", ""),
+        url=kwargs.get("url", ""),
+        kws=default_keywords(**kwargs.get("_kws", {})) if "_kws" in kwargs else "",
+        epoch=kwargs.get("_epoch", ""),
+        person=default_author(**kwargs.get("_person", {})) if "_person" in kwargs else "",
+        comm_for_profile_bib=kwargs.get("_comm_for_profile_bib", ""),
+        langid=kwargs.get("_langid", ""),
+        lang_der=kwargs.get("_lang_der", ""),
+        further_refs=tuple(default_bib_key(**b) for b in kwargs.get("_further_refs", ())),
+        depends_on=tuple(default_bib_key(**b) for b in kwargs.get("_depends_on", ())),
+        dltc_num=kwargs.get("_dltc_num"),
+        spec_interest=kwargs.get("_spec_interest", ""),
+        note_perso=kwargs.get("_note_perso", ""),
+        note_stock=kwargs.get("_note_stock", ""),
+        note_status=kwargs.get("_note_status", ""),
+        num_inwork_coll=kwargs.get("_num_inwork_coll"),
+        num_inwork=kwargs.get("_num_inwork", ""),
+        num_coll=kwargs.get("_num_coll"),
+        dltc_copyediting_note=kwargs.get("_dltc_copyediting_note", ""),
+        note_missing=kwargs.get("_note_missing", ""),
+        num_sort=kwargs.get("_num_sort"),
+        id=kwargs.get("id"),
+        bib_info_source=kwargs.get("_bib_info_source", ""),
+    )

philoch_bib_sdk/logic/functions/comparator.py

@@ -0,0 +1,134 @@
+from aletk.utils import get_logger, fuzzy_match_score, remove_extra_whitespace
+
+from typing import TypedDict
+from philoch_bib_sdk.converters.plaintext.author.formatter import format_author
+from philoch_bib_sdk.logic.models import BibItem, BibItemDateAttr, TBibString
+
+
+logger = get_logger(__name__)
+
+
+class BibItemScore(TypedDict):
+    score: int
+    score_title: int
+    score_author: int
+    score_year: int
+
+
+class ScoredBibItems(TypedDict):
+    reference: BibItem
+    subject: BibItem
+    score: BibItemScore
+
+
+UNDESIRED_TITLE_KEYWORDS = ["errata", "review"]
+
+
+def _score_title(title_1: str, title_2: str) -> int:
+
+    norm_title_1 = remove_extra_whitespace(title_1).lower()
+    norm_title_2 = remove_extra_whitespace(title_2).lower()
+
+    if not norm_title_1 or not norm_title_2:
+        raise ValueError("Titles cannot be empty for comparison")
+
+    title_score = fuzzy_match_score(
+        norm_title_1,
+        norm_title_2,
+    )
+
+    # Might catch cases in which one doesn't include the subtitle
+    one_included_in_the_other = (norm_title_1 in norm_title_2) or (norm_title_2 in norm_title_1)
+
+    undesired_kws_in_title_1 = {kw for kw in UNDESIRED_TITLE_KEYWORDS if kw in norm_title_1}
+
+    undesired_kws_in_title_2 = {kw for kw in UNDESIRED_TITLE_KEYWORDS if kw in norm_title_2}
+
+    # disjunction
+    undesired_kws = undesired_kws_in_title_1.symmetric_difference(undesired_kws_in_title_2)
+
+    undesired_kws_mismatch = True if len(undesired_kws) > 0 else False
+
+    if ((title_score > 85) or one_included_in_the_other) and not undesired_kws_mismatch:
+        title_score += 100
+
+    for _ in undesired_kws:
+        title_score -= 50
+
+    return title_score
+
+
+def _score_author(author_1_full_name: str, author_2_full_name: str) -> int:
+    stripped_author_1 = remove_extra_whitespace(author_1_full_name)
+    stripped_author_2 = remove_extra_whitespace(author_2_full_name)
+
+    if not stripped_author_1 or not stripped_author_2:
+        raise ValueError("Authors cannot be empty for comparison")
+
+    author_score = fuzzy_match_score(
+        stripped_author_1,
+        stripped_author_2,
+    )
+
+    if author_score > 85:
+        author_score += 100
+
+    return author_score
+
+
+def _score_year(year_1: int, year_2: int, range_offset: int = 1) -> int:
+
+    if not year_1 or not year_2:
+        raise ValueError("Years cannot be empty for comparison")
+
+    if not any(isinstance(year, int) for year in (year_1, year_2)):
+        if year_1 == year_2:
+            return 100
+        else:
+            return 0
+
+    range = [year_1 - range_offset, year_1, year_1 + range_offset]
+
+    if year_2 in range:
+        return 100
+    else:
+        return 0
+
+
+def compare_bibitems(reference: BibItem, subject: BibItem, bibstring_type: TBibString) -> ScoredBibItems:
+    """
+    Calculate the score of two BibItems based on their title, author, and year.
+    The scoring is done using fuzzy matching for title and author, and exact matching for year.
+    The final score is a combination of the individual scores.
+    """
+
+    logger.debug(f"Scoring bibitems: {reference}, {subject}")
+
+    title_1 = getattr(reference.title, bibstring_type)
+    title_2 = getattr(subject.title, bibstring_type)
+    title_score = _score_title(title_1, title_2)
+
+    author_1_full_name = format_author(reference.author, bibstring_type)
+    author_2_full_name = format_author(subject.author, bibstring_type)
+
+    author_score = _score_author(author_1_full_name, author_2_full_name)
+
+    if isinstance(reference.date, BibItemDateAttr) and isinstance(subject.date, BibItemDateAttr):
+        year_1 = reference.date.year
+        year_2 = subject.date.year
+        year_score = _score_year(year_1, year_2)
+    else:
+        year_score = 0
+
+    total_score = title_score + author_score + year_score
+
+    return {
+        "reference": reference,
+        "subject": subject,
+        "score": {
+            "score": total_score,
+            "score_title": title_score,
+            "score_author": author_score,
+            "score_year": year_score,
+        },
+    }

philoch_bib_sdk/logic/functions/journal_article_matcher.py

@@ -0,0 +1,40 @@
+from typing import Callable, Dict, Tuple
+from philoch_bib_sdk.converters.plaintext.journal.formatter import format_journal
+from philoch_bib_sdk.logic.models import BibItem
+
+
+type TJournalName = str
+
+type TVolume = str
+
+type TNumber = str
+
+type TBibkey = str
+
+
+type TJournalBibkeyIndex = Dict[Tuple[TJournalName, TVolume, TNumber], TBibkey]  # (journal, volume, number)  # bibkey
+
+
+def get_bibkey_by_journal_volume_number(index: TJournalBibkeyIndex, subject: BibItem) -> TBibkey:
+    """
+    Simple lookup of a Bibitem on an index for its bibkey, via the combination (journal_name, volume, number). Fails if any of the three fields are missing.
+    """
+
+    journal = format_journal(subject.journal, bibstring_type="latex")
+    volume = subject.volume
+    number = subject.number
+
+    if any((journal == "", volume == "", number == "")):
+        raise ValueError(
+            f"Expected subject bibitem journal with non-empty journal, volume, and number. Found [[ journal: {journal}; volume: {volume}; number: {number} ]] instead."
+        )
+
+    return index[(journal, volume, number)]
+
+
+type TReadIndex = Callable[
+    [
+        str,  # path to the index file
+    ],
+    TJournalBibkeyIndex,
+]

philoch_bib_sdk/logic/literals.py

@@ -1,7 +1,6 @@
 from typing import Literal
 
 type TBibTeXEntryType = Literal[
-    "",
     "article",
     "book",
     "incollection",
@@ -12,15 +11,20 @@ type TBibTeXEntryType = Literal[
     "proceedings",
     "techreport",
     "unpublished",
+    "UNKNOWN",
 ]
 
-type TPubState = Literal[
+type TBasicPubState = Literal[
     "",
     "unpub",
+    "forthcoming",
+]
+
+type TPubState = Literal[
+    TBasicPubState,
     "inwork",
     "submitted",
     "published",
-    "forthcoming",
 ]
 
 type TLanguageID = Literal[