philoch-bib-sdk 0.1.1rc1__tar.gz

philoch_bib_sdk-0.1.1rc1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Philosophie.ch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

philoch_bib_sdk-0.1.1rc1/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.3
+Name: philoch-bib-sdk
+Version: 0.1.1rc1
+Summary: Standard development kit for the Philosophie Bibliography project
+License: MIT
+Author: Luis Alejandro Bordo García
+Author-email: luis.bordo@philosophie.ch
+Maintainer: Luis Alejandro Bordo García
+Maintainer-email: tech@philosophie.ch
+Requires-Python: >=3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: aletk (>=0.1.6,<0.2.0)
+Requires-Dist: attrs (>=25.3.0,<26.0.0)
+Description-Content-Type: text/markdown
+
+# Philosophie.ch Bibliography SDK
+
+This repository contains the standard development kit for the bibliography project of the [Philosophie.ch](https://philosophie.ch) association.
+

philoch_bib_sdk-0.1.1rc1/README.md

@@ -0,0 +1,3 @@
+# Philosophie.ch Bibliography SDK
+
+This repository contains the standard development kit for the bibliography project of the [Philosophie.ch](https://philosophie.ch) association.

philoch_bib_sdk-0.1.1rc1/philoch_bib_sdk/logic/formatters.py

@@ -0,0 +1,89 @@
+from typing import List
+from aletk.utils import get_logger
+from philoch_bib_sdk.logic.models import Author, BibKey, PagePair
+
+lgr = get_logger(__name__)
+
+
+def _author_full_name_generic(given_name: str | None, family_name: str | None) -> str:
+    if given_name is None:
+        return ""
+
+    if family_name is None:
+        return given_name
+
+    return f"{family_name}, {given_name}"
+
+
+def _author_full_name(author: Author | None) -> str:
+    if author is None:
+        return ""
+    return _author_full_name_generic(author.given_name, author.family_name)
+
+
+def _author_full_name_latex(author: Author | None) -> str:
+    if author is None:
+        return ""
+    return _author_full_name_generic(author.given_name_latex, author.family_name_latex)
+
+
+def author_full_name(authors: List[Author] | None) -> str:
+    if authors is None:
+        return ""
+    return " and ".join([_author_full_name(author) for author in authors])
+
+
+def author_full_name_latex(authors: List[Author] | None) -> str:
+    if authors is None:
+        return ""
+    return " and ".join([_author_full_name_latex(author) for author in authors])
+
+
+def bibkey_str(bibkey: BibKey | None) -> str:
+    if bibkey is None:
+        return ""
+
+    if bibkey.other_authors:
+        authors_l = [bibkey.first_author, bibkey.other_authors]
+    else:
+        authors_l = [bibkey.first_author]
+
+    authors = "-".join(authors_l)
+
+    year = (
+        f"{bibkey.year}{bibkey.year_suffix}"
+        if bibkey.pub_status in ["published", ""]
+        else f"{bibkey.pub_status}{bibkey.year_suffix}"
+    )
+
+    return f"{authors}:{year}"
+
+
+def _pages_single_str(page_pair: PagePair) -> str:
+    return "--".join([page_pair.start, page_pair.end])
+
+
+def pages_str(pages: List[PagePair] | None) -> str:
+    if pages is None:
+        return ""
+    return ", ".join([_pages_single_str(page_pair) for page_pair in pages])
+
+
+def person_str(person: Author | None) -> str:
+    """
+    Note: ignores LaTeX names
+    """
+    if person is None:
+        return ""
+
+    if person.famous_name is not None:
+        return person.famous_name
+
+    if person.given_name is None and person.family_name is None:
+        return ""
+
+    if person.given_name is None:
+        return person.family_name
+
+    # Mononym
+    return person.given_name

philoch_bib_sdk-0.1.1rc1/philoch_bib_sdk/logic/literals.py

@@ -0,0 +1,86 @@
+from typing import Literal
+
+type TBibTeXEntryType = Literal[
+    "",
+    "article",
+    "book",
+    "incollection",
+    "inproceedings",
+    "mastersthesis",
+    "misc",
+    "phdthesis",
+    "proceedings",
+    "techreport",
+    "unpublished",
+]
+
+type TPubState = Literal[
+    "",
+    "unpub",
+    "inwork",
+    "submitted",
+    "published",
+    "forthcoming",
+]
+
+type TLanguageID = Literal[
+    "",
+    "catalan",
+    "czech",
+    "danish",
+    "dutch",
+    "english",
+    "french",
+    "greek",
+    "italian",
+    "latin",
+    "lithuanian",
+    "ngerman",
+    "polish",
+    "portuguese",
+    "romanian",
+    "russian",
+    "slovak",
+    "spanish",
+    "swedish",
+    "unknown",
+]
+
+type TEpoch = Literal[
+    "",
+    "ancient-philosophy",
+    "ancient-scientists",
+    "austrian-philosophy",
+    "british-idealism",
+    "classics",
+    "contemporaries",
+    "contemporary-scientists",
+    "continental-philosophy",
+    "critical-theory",
+    "cynics",
+    "enlightenment",
+    "existentialism",
+    "exotic-philosophy",
+    "german-idealism",
+    "german-rationalism",
+    "gestalt-psychology",
+    "hermeneutics",
+    "islamic-philosophy",
+    "mathematicians",
+    "medieval-philosophy",
+    "modern-philosophy",
+    "modern-scientists",
+    "neokantianism",
+    "neo-kantianism",
+    "neoplatonism",
+    "new-realism",
+    "ordinary-language-philosophy",
+    "phenomenology",
+    "polish-logic",
+    "pragmatism",
+    "presocratics",
+    "renaissance",
+    "stoics",
+    "theologians",
+    "vienna-circle",
+]

philoch_bib_sdk-0.1.1rc1/philoch_bib_sdk/logic/models.py

@@ -0,0 +1,359 @@
+from __future__ import annotations
+from typing import Tuple
+import attrs
+
+from philoch_bib_sdk.logic.literals import TBibTeXEntryType, TEpoch, TLanguageID, TPubState
+
+
+############
+# Base Renderables
+############
+
+
+@attrs.define(frozen=True, slots=True)
+class BaseRenderable:
+    """
+    Base class for renderable objects, that contain LaTeX code, and possibly a unicode representation of it.
+
+    Args:
+        text: str = ""
+        text_latex: str = ""
+        id: int = -1
+    """
+
+    text: str = ""
+    text_latex: str = ""
+    id: int = -1
+
+
+@attrs.define(frozen=True, slots=True)
+class BaseNamedRenderable:
+    """
+    Base class for renderable, named, objects, that contain LaTeX code, and possibly a unicode representation of it.
+
+    Args:
+        name: str
+        name_latex: str | None = None
+        id: int | None = None
+    """
+
+    name: str = ""
+    name_latex: str = ""
+    id: int = -1
+
+
+############
+# Author
+############
+
+
+@attrs.define(frozen=True, slots=True)
+class Author:
+    """
+    An author of a publication.
+
+    Args:
+        given_name: str = ""
+        family_name: str = ""
+        given_name_latex: str  = ""
+        family_name_latex: str = ""
+        publications: List[BibItem] = []
+        id: int = -1
+    """
+
+    given_name: str = ""
+    family_name: str = ""
+    given_name_latex: str = ""
+    family_name_latex: str = ""
+    famous_name: str = ""
+    publications: Tuple[BibItem, ...] = ()
+    id: int = -1
+
+
+############
+# Journal
+############
+
+
+@attrs.define(frozen=True, slots=True)
+class Journal:
+    """
+    A journal that publishes publications.
+
+    Args:
+        name: str = ""
+        name_latex: str = ""
+        issn_print: str = ""
+        issn_electronic: str = ""
+        id: int = -1
+    """
+
+    name: str = ""
+    name_latex: str = ""
+    issn_print: str = ""
+    issn_electronic: str = ""
+    id: int = -1
+
+
+############
+# Note
+############
+
+
+@attrs.define(frozen=True, slots=True)
+class Note(BaseRenderable):
+    """
+    Notes (metadata) about a publication.
+
+    Args:
+        text: str = ""
+        text_latex: str = ""
+        id: int = -1
+    """
+
+    pass
+
+
+############
+# Keywords
+############
+
+
+@attrs.define(frozen=True, slots=True)
+class Keyword:
+    """
+    Keyword of a publication.
+
+    Args:
+        name: str = ""
+        id: int = -1
+    """
+
+    name: str = ""
+    id: int = -1
+
+
+@attrs.define(frozen=True, slots=True)
+class Keywords:
+    level1: Keyword = Keyword()
+    level2: Keyword = Keyword()
+    level3: Keyword = Keyword()
+
+
+############
+# Series, Institution, School, Publisher, Type
+############
+
+
+@attrs.define(frozen=True, slots=True)
+class Series(BaseNamedRenderable):
+    """
+    A series of publications.
+
+    Args:
+        name: str = ""
+        name_latex: str = ""
+        id: int = -1
+    """
+
+    pass
+
+
+@attrs.define(frozen=True, slots=True)
+class Institution(BaseNamedRenderable):
+    """
+    An institution that publishes publications.
+
+    Args:
+        name: str = ""
+        name_latex: str = ""
+        id: int = -1
+    """
+
+    pass
+
+
+@attrs.define(frozen=True, slots=True)
+class School(BaseNamedRenderable):
+    """
+    A school that publishes publications.
+
+    Args:
+        name: str = ""
+        name_latex: str = ""
+        id: int = -1
+    """
+
+    pass
+
+
+@attrs.define(frozen=True, slots=True)
+class Publisher(BaseNamedRenderable):
+    """
+    A publisher of publications.
+
+    Args:
+        name: str = ""
+        name_latex: str = ""
+        id: int = -1
+    """
+
+    pass
+
+
+@attrs.define(frozen=True, slots=True)
+class Type(BaseNamedRenderable):
+    """
+    A type of publication.
+
+    Args:
+        name: str = ""
+        name_latex: str = ""
+        id: int = -1
+    """
+
+    pass
+
+
+############
+# BibItem
+############
+
+
+@attrs.define(frozen=True, slots=True)
+class BibKey:
+    """
+    A unique identifier for a publication.
+
+    Args:
+        first_author: str = ""
+        year: int | None = None
+        pub_status: TPubState = "published"
+        other_authors: str = ""
+        et_al: bool = False
+        year_suffix
+    """
+
+    first_author: str
+    other_authors: str = ""
+    year: int | None = None
+    pub_status: TPubState = ""
+    year_suffix: str = ""
+
+
+@attrs.define(frozen=True, slots=True)
+class BibItemDate:
+    """
+    Year of a publication.
+
+    Example:
+        BibItemDate(year=2021, year_revised=2022) represents `2021/2022`.
+        BibItemDate(year=2021, month=1, day=1) represents `2021-01-01`.
+        BibItemDate(forthcoming=True) represents `forthcoming`.
+
+    Args:
+        year: int | None = None
+        year_revised: int | None = None
+        month: int | None = None
+        day: int | None = None
+        forthcoming: bool | None = None
+    """
+
+    year: int | None = None
+    year_revised: int | None = None
+    month: int | None = None
+    day: int | None = None
+    forthcoming: bool = False
+
+
+@attrs.define(frozen=True, slots=True)
+class PagePair:
+    """
+    Page numbers of a publication. Can be a range, roman numerals, or a single page.
+
+    Args:
+        start: str
+        end: str | None = None
+    """
+
+    start: str
+    end: str = ""
+
+
+@attrs.define(frozen=True, slots=True)
+class IssueTitle(BaseRenderable):
+    """
+    Title of an issue of a publication.
+
+    Args:
+        text: str
+        text_latex: str | None = None
+        id: int | None = None
+    """
+
+    pass
+
+
+@attrs.define(frozen=True, slots=True)
+class BibItem:
+    """
+    Bibliographic item type. All attributes are optional.
+
+    Args:
+
+    """
+
+    _to_do: str = ""
+    _change_request: str = ""
+    entry_type: TBibTeXEntryType = ""
+    bibkey: BibKey | None = None
+    author: Tuple[Author, ...] = ()
+    editor: Tuple[Author, ...] = ()
+    options: Tuple[str, ...] = ()
+    shorthand: str = ""
+    date: BibItemDate | None = None
+    pubstate: TPubState | None = None
+    title: str = ""
+    _title_unicode: str = ""
+    booktitle: str = ""
+    crossref: str = ""
+    journal: Journal | None = None
+    volume: str = ""
+    number: str = ""
+    pages: Tuple[PagePair, ...] = ()
+    eid: str = ""
+    series: Series | None = None
+    address: str = ""
+    institution: str = ""
+    school: str = ""
+    publisher: Publisher | None = None
+    type: Type | None = None
+    edition: str = ""
+    note: Note | None = None
+    issuetitle: IssueTitle | None = None
+    guesteditor: Tuple[Author, ...] = ()
+    further_note: Note | None = None
+    urn: str = ""
+    eprint: str = ""
+    doi: str = ""
+    url: str = ""
+    _kws: Keywords = Keywords()
+    _epoch: TEpoch = ""
+    _person: Author | None = None
+    _comm_for_profile_bib: str = ""
+    langid: TLanguageID = ""
+    _lang_det: str = ""
+    _further_refs: Tuple[BibKey, ...] = ()
+    _depends_on: Tuple[BibKey, ...] = ()
+    dltc_num: int | None = None
+    _spec_interest: str = ""
+    _note_perso: Note | None = None
+    _note_stock: Note | None = None
+    _note_status: Note | None = None
+    _num_in_work: str = ""
+    _num_in_work_coll: int | None = None
+    _num_coll: int | None = None
+    _dltc_copyediting_note: str = ""
+    _note_missing: str = ""
+    _num_sort: int = 0
+    _bib_info_source: str = ""

philoch_bib_sdk-0.1.1rc1/philoch_bib_sdk/logic/parsers.py

@@ -0,0 +1,177 @@
+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, BibKey
+
+lgr = get_logger(__name__)
+
+
+def _author_parse_normalize(text: str) -> Tuple[str, str]:
+    """
+    Return a tuple of two strings, the first of which is the given name, and the second of which is the family name. If only one name is found, the second string will be empty.
+
+    Fails if more than two names are found.
+    """
+    parts = text.split(",")
+
+    if len(parts) > 2:
+        raise ValueError(f"Unexpected number of author parts found in '{text}': '{parts}'. Expected 2 or less.")
+
+    elif len(parts) == 0:
+        return ("", "")
+
+    elif len(parts) == 1:
+        return (parts[0], "")
+
+    else:
+        return (parts[0], parts[1])
+
+
+def author_parse(text: str, latex: bool) -> Ok[Tuple[Author, ...]] | Err:
+    """
+    Return either a string, or a parsing error.
+    """
+    try:
+        if text == "":
+            return Ok(())
+
+        parts = remove_extra_whitespace(text).split(" and ")
+        parts_normalized = [_author_parse_normalize(part) for part in parts]
+
+        authors = tuple(
+            Author(
+                given_name=author[0] if not latex else "",
+                family_name=author[1] if not latex else "",
+                given_name_latex=author[0] if latex else "",
+                family_name_latex=author[1] if latex else "",
+            )
+            for author 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()}",
+        )
+
+
+def person_parse(text: str) -> Ok[Author | None] | Err:
+    """
+    Return either an Author object, or a parsing error.
+    """
+    try:
+        if text == "":
+            return Ok(None)
+
+        cleaned = remove_extra_whitespace(remove_extra_whitespace(text).replace(";", ""))
+
+        return Ok(
+            Author(
+                famous_name=cleaned,
+            )
+        )
+
+    except Exception as e:
+        return Err(
+            message=f"Could not parse '_person' field with value [[ {text} ]]. {e.__class__.__name__}: {e}",
+            code=-1,
+            error_type="ParsingError",
+            error_trace=f"{traceback.format_exc()}",
+        )
+
+
+def bibkey_parse(text: str, text_position_d: dict[str, int] | None = None) -> Ok[BibKey] | Err:
+    """
+    Return either a Bibkey object, or a BibkeyError object to indicate a parsing error.
+    """
+
+    return Err(
+        message="TODO. Clean and adapt the commented out code below.",
+        code=-1,
+        error_type="NotImplementedError",
+    )
+    # try:
+    # parts = text.split(":")
+    # if len(parts) != 2:
+    # raise ValueError(f"Unexpected number of bibkey parts for '{text}': '{parts}'")
+
+    # author_parts = parts[0].split("-")
+    # year_parts = parts[1]
+
+    # if len(author_parts) == 1:
+    # first_author = author_parts[0]
+    # other_authors = None
+    # elif len(author_parts) == 2:
+    # first_author = author_parts[0]
+    # other_authors = author_parts[1]
+    # else:
+    # raise ValueError(f"Unexpected bibkey author parts for '{text}': '{author_parts}'")
+
+    # char_index_type_d = {i: (char, char.isdigit()) for i, char in enumerate(year_parts)}
+
+    # year_l: list[str] = []
+    # int_breakpoint = None
+    # for value in char_index_type_d.items():
+    # i, (char, is_digit) = value
+    # 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 int_breakpoint is not None:
+    # year_suffix = year_parts[int_breakpoint + 1 :]
+
+    # else:
+    ## all characters are non-digits
+    # year_suffix = "".join(year_parts)
+
+    # if year_suffix != "" and year_suffix not in ["unpub", "forthcoming"]:
+    # if len(year_suffix) > 1:
+    # if "unpub" not in year_suffix and "forthcoming" not in year_suffix:
+    # lgr.warning(f"Unexpected year suffix for '{text}': '{year_suffix}'")
+    # elif len(year_suffix) == 1:
+    # if year_suffix.isdigit():
+    # lgr.warning(f"Unexpected year suffix for '{text}': '{year_suffix}'")
+
+    # if year_int is None and year_suffix is None:
+    # raise ValueError(f"Could not parse year for '{text}': '{year_parts}'")
+
+    # if year_int is None:
+    # return Ok(Bibkey(
+    # first_author=first_author,
+    # year = year_int,
+    # ))
+
+    # else:
+    # return Ok(
+    # Bibkey(first_author=first_author, other_authors=other_authors, year=year_int, year_suffix=year_suffix)
+    # )
+
+    # except Exception as e:
+    # error_message = f"Could not parse bibkey for '{text}'"
+
+    # if text_position_d is None:
+    # return Err(
+    # message=f"Could not parse bibkey for '{text}'. {e.__class__.__name__}: {e}",
+    # code=-1,
+    # error_type="BibkeyError",
+    # error_trace=f"{traceback.format_exc()}",
+    # )
+    # else:
+    # return Err(
+    # message=f"Could not parse bibkey for '{text}' at position {text_position_d}. {e.__class__}: {e}",
+    # code=-1,
+    # error_type="BibkeyError",
+    # error_trace=f"{traceback.format_exc()}",
+    # )

philoch_bib_sdk-0.1.1rc1/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "philoch-bib-sdk"
+version = "0.1.1-rc1"
+description = "Standard development kit for the Philosophie Bibliography project"
+authors = [
+    {name = "Luis Alejandro Bordo García", email = "luis.bordo@philosophie.ch"}
+]
+maintainers = [
+    {name = "Luis Alejandro Bordo García", email = "tech@philosophie.ch"}
+]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.13"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.dependencies]
+aletk = "^0.1.6"
+attrs = "^25.3.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.5"
+mypy = "^1.15.0"
+black = {extras = ["jupyter"], version = "^25.1.0"}
+jupyter = "^1.1.1"
+pytest-env = "^1.1.5"
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+explicit_package_bases = true
+mypy_path = "."
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+addopts = "-ras -m 'not external'"
+markers = [
+    "external: mark tests that require external API calls",
+]
+testpaths = ["tests"]
+pythonpath = ["."]
+env = [
+]
+
+[[tool.mypy.overrides]]
+module = [
+]
+
+ignore_missing_imports = true
+[tool.black]
+line-length = 120
+target-version = ['py313']
+include = '\.pyi?$'
+skip-string-normalization = true
+# 'extend-exclude' excludes files or directories in addition to the defaults
+extend-exclude = '''
+# A regex preceded with ^/ will apply only to files and directories
+# in the root of the project.
+(
+  ^/foo.py    # exclude a file named foo.py in the root of the project
+  | .*_pb2.py  # exclude autogenerated Protocol Buffer files anywhere in the project
+)
+'''
+