psimodpy 0.1.0__py3-none-any.whl

psimodpy/__init__.py

@@ -0,0 +1,33 @@
+"""psimodpy — Python library for the PSI-MOD protein modification ontology."""
+
+from psimodpy._download import download_obo
+from psimodpy.database import PsiModDatabase, load, load_from
+from psimodpy.models import (
+    AminoAcid,
+    Crosslink,
+    PsiModEntry,
+    Relationship,
+    RelationshipType,
+    Source,
+    Synonym,
+    SynonymType,
+    TermSpec,
+)
+from psimodpy.parser import parse_obo
+
+__all__ = [
+    "AminoAcid",
+    "Crosslink",
+    "PsiModEntry",
+    "Synonym",
+    "SynonymType",
+    "Relationship",
+    "RelationshipType",
+    "TermSpec",
+    "Source",
+    "PsiModDatabase",
+    "load",
+    "load_from",
+    "parse_obo",
+    "download_obo",
+]

psimodpy/_download.py

@@ -0,0 +1,30 @@
+"""Utility for downloading the PSI-MOD OBO file from the HUPO-PSI GitHub repository."""
+
+from __future__ import annotations
+
+import urllib.request
+from pathlib import Path
+
+_PSIMOD_URL = "https://raw.githubusercontent.com/HUPO-PSI/psi-mod-CV/master/PSI-MOD.obo"
+_CACHE_DIR = Path.home() / ".cache" / "psimodpy"
+_CACHE_FILE = _CACHE_DIR / "PSI-MOD.obo"
+
+
+def download_obo(dest: Path | str | None = None, *, force: bool = False) -> Path:
+    """Fetch the PSI-MOD OBO file and cache it locally.
+
+    Args:
+        dest: Destination path. Defaults to ~/.cache/psimodpy/PSI-MOD.obo.
+        force: If True, re-download even if the file already exists.
+
+    Returns:
+        Path to the downloaded file.
+    """
+    target = Path(dest) if dest is not None else _CACHE_FILE
+    if target.exists() and not force:
+        return target
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with urllib.request.urlopen(_PSIMOD_URL) as response:  # noqa: S310
+        data = response.read()
+    target.write_bytes(data)
+    return target

psimodpy/_formula.py

@@ -0,0 +1,92 @@
+"""PSI-MOD formula string parsing and Hill-notation conversion.
+
+PSI-MOD formula format: element-count pairs separated by spaces, with isotopes
+in parentheses before the element symbol. Elements are in strict alphabetical
+order (not CAS/Hill order). Counts can be zero or negative in difference formulas.
+
+Examples:
+    "C 3 H 5 N 1 O 1"
+    "C 0 H 0 N 0 O 3 P 1"
+    "(12)C 8 (13)C 4 H 20 (14)N 1 (15)N 1 O 2"
+    "C 0 H -2 N 0 O -1"
+"""
+
+from __future__ import annotations
+
+import re
+
+# Matches either "(12)C" or "C" followed by whitespace and an integer count (may be negative).
+_TOKEN_RE = re.compile(r"(\(\d+\)[A-Za-z]+|[A-Za-z]+)\s+(-?\d+)")
+
+
+def parse_formula(formula: str) -> dict[str, int]:
+    """Parse a PSI-MOD formula string into {element_token: count}.
+
+    Zero counts are included. Negative counts are preserved.
+
+    Examples:
+        >>> parse_formula("C 3 H 5 N 1 O 1")
+        {'C': 3, 'H': 5, 'N': 1, 'O': 1}
+        >>> parse_formula("(12)C 8 (13)C 4 H 20")
+        {'(12)C': 8, '(13)C': 4, 'H': 20}
+    """
+    result: dict[str, int] = {}
+    for element, count in _TOKEN_RE.findall(formula):
+        result[element] = int(count)
+    return result
+
+
+def formula_to_hill(composition: dict[str, int]) -> str:
+    """Convert an element-count dict to Hill-notation string.
+
+    Ordering: C (and isotopic carbons) first, H (and isotopic hydrogens) second,
+    then all remaining elements alphabetically. Zero counts are skipped.
+    A count of 1 is omitted. Negative counts are written as e.g. "O-1".
+
+    Examples:
+        >>> formula_to_hill({"C": 3, "H": 5, "N": 1, "O": 1})
+        'C3H5NO'
+        >>> formula_to_hill({"C": 0, "H": -2, "O": -1})
+        'H-2O-1'
+        >>> formula_to_hill({"(12)C": 8, "(13)C": 4, "H": 20})
+        '(12)C8(13)C4H20'
+    """
+    # Separate into carbon group, hydrogen group, and other
+    carbon_group: list[tuple[str, int]] = []
+    hydrogen_group: list[tuple[str, int]] = []
+    other: list[tuple[str, int]] = []
+
+    for element, count in composition.items():
+        if count == 0:
+            continue
+        # Isotopic carbons: "(12)C", "(13)C", "(14)C" — contain "C" after closing paren
+        # Non-isotopic carbon: "C"
+        base = re.sub(r"^\(\d+\)", "", element)  # strip isotope prefix
+        if base == "C":
+            carbon_group.append((element, count))
+        elif base == "H":
+            hydrogen_group.append((element, count))
+        else:
+            other.append((element, count))
+
+    # Sort each group: isotopic variants before non-isotopic, then by isotope number
+    def _sort_key(ec: tuple[str, int]) -> tuple[int, str]:
+        element = ec[0]
+        m = re.match(r"^\((\d+)\)", element)
+        isotope_num = int(m.group(1)) if m else 0
+        return (isotope_num, element)
+
+    carbon_group.sort(key=_sort_key)
+    hydrogen_group.sort(key=_sort_key)
+    other.sort(key=lambda ec: ec[0])
+
+    ordered = carbon_group + hydrogen_group + other
+
+    parts: list[str] = []
+    for element, count in ordered:
+        if count == 1:
+            parts.append(element)
+        else:
+            parts.append(f"{element}{count}")
+
+    return "".join(parts)

psimodpy/database.py

@@ -0,0 +1,171 @@
+"""PSI-MOD database: indexing, lookup, and graph traversal."""
+
+from __future__ import annotations
+
+import importlib.resources
+from collections.abc import Iterator
+from pathlib import Path
+
+from psimodpy.models import AminoAcid, Crosslink, PsiModEntry, RelationshipType
+
+
+class PsiModDatabase:
+    """In-memory database of PSI-MOD entries with multiple lookup strategies."""
+
+    def __init__(self, entries: list[PsiModEntry] | Iterator[PsiModEntry]) -> None:
+        self._by_id: dict[int, PsiModEntry] = {}
+        self._by_name_lower: dict[str, PsiModEntry] = {}
+        self._by_origin: dict[str, list[PsiModEntry]] = {}
+        self._children: dict[int, list[int]] = {}
+
+        for entry in entries:
+            self._by_id[entry.id] = entry
+            self._by_name_lower[entry.name.lower()] = entry
+
+            # Index by each amino acid in origin
+            if isinstance(entry.origin, AminoAcid):
+                self._by_origin.setdefault(str(entry.origin), []).append(entry)
+            elif isinstance(entry.origin, Crosslink):
+                for site in entry.origin.sites:
+                    self._by_origin.setdefault(site, []).append(entry)
+
+        # Build reverse is_a index after all entries are loaded
+        for entry in self._by_id.values():
+            for parent_id in entry.is_a:
+                self._children.setdefault(parent_id, []).append(entry.id)
+
+    # ------------------------------------------------------------------
+    # Lookup by identity
+    # ------------------------------------------------------------------
+
+    def get_by_id(self, id: int | str) -> PsiModEntry | None:
+        """Return the entry for the given ID, or None if not found.
+
+        Accepts an integer (34) or a string in MOD:NNNNN format ("MOD:00034").
+        """
+        if isinstance(id, str):
+            # Accept "MOD:00034" or plain "34"
+            if id.upper().startswith("MOD:"):
+                id = int(id[4:])
+            else:
+                id = int(id)
+        return self._by_id.get(id)
+
+    def get_by_name(self, name: str) -> PsiModEntry | None:
+        """Return the entry with the given name (case-insensitive), or None."""
+        return self._by_name_lower.get(name.lower())
+
+    def __getitem__(self, id: int | str) -> PsiModEntry:
+        """Return entry by ID; raise KeyError if not found."""
+        entry = self.get_by_id(id)
+        if entry is None:
+            raise KeyError(id)
+        return entry
+
+    def __len__(self) -> int:
+        return len(self._by_id)
+
+    def __iter__(self) -> Iterator[PsiModEntry]:
+        return iter(self._by_id.values())
+
+    # ------------------------------------------------------------------
+    # Search
+    # ------------------------------------------------------------------
+
+    def search(self, query: str) -> list[PsiModEntry]:
+        """Return entries whose name, definition, or any synonym contains query (case-insensitive).
+
+        An empty query returns all entries.
+        """
+        q = query.lower()
+        if not q:
+            return list(self._by_id.values())
+        results = []
+        for entry in self._by_id.values():
+            if (
+                q in entry.name.lower()
+                or q in entry.definition.lower()
+                or any(q in s.value.lower() for s in entry.synonyms)
+            ):
+                results.append(entry)
+        return results
+
+    def get_by_origin(self, aa: str) -> list[PsiModEntry]:
+        """Return all entries whose origin includes the given amino acid code.
+
+        Crosslink entries with origin "C, C" will appear in get_by_origin("C").
+        Entries with origin "X" (any) appear in get_by_origin("X").
+        """
+        return list(self._by_origin.get(aa, []))
+
+    # ------------------------------------------------------------------
+    # Graph traversal
+    # ------------------------------------------------------------------
+
+    def get_parents(self, entry: PsiModEntry) -> list[PsiModEntry]:
+        """Return the direct parent entries (via is_a relationships)."""
+        return [self._by_id[pid] for pid in entry.is_a if pid in self._by_id]
+
+    def get_children(self, entry: PsiModEntry) -> list[PsiModEntry]:
+        """Return entries that have this entry as a direct parent."""
+        return [self._by_id[cid] for cid in self._children.get(entry.id, []) if cid in self._by_id]
+
+    def get_related(self, entry: PsiModEntry, rel_type: RelationshipType) -> list[PsiModEntry]:
+        """Return entries reachable from entry via the given relationship type."""
+        return [
+            self._by_id[r.target_id] for r in entry.relationships if r.type == rel_type and r.target_id in self._by_id
+        ]
+
+    # ------------------------------------------------------------------
+    # Filtering
+    # ------------------------------------------------------------------
+
+    def filter(
+        self,
+        *,
+        include_obsolete: bool = False,
+        slim_only: bool = False,
+    ) -> list[PsiModEntry]:
+        """Return a filtered list of entries.
+
+        Args:
+            include_obsolete: If False (default), exclude obsolete entries.
+            slim_only: If True, return only PSI-MOD-slim subset entries.
+        """
+        entries = list(self._by_id.values())
+        if not include_obsolete:
+            entries = [e for e in entries if not e.is_obsolete]
+        if slim_only:
+            entries = [e for e in entries if e.in_slim_subset]
+        return entries
+
+
+def load(*, include_obsolete: bool = True) -> PsiModDatabase:
+    """Load the bundled PSI-MOD database.
+
+    Args:
+        include_obsolete: If True (default), include obsolete entries. Obsolete
+            entries carry xref_remap redirects useful for cross-reference resolution.
+            Pass False to exclude them.
+
+    Returns:
+        A PsiModDatabase populated from the bundled PSI-MOD.obo file.
+    """
+    from psimodpy.parser import parse_obo
+
+    pkg_data = importlib.resources.files("psimodpy.data")
+    obo_path = pkg_data.joinpath("PSI-MOD.obo")
+    # importlib.resources returns a Traversable; write to a temp path if needed
+    with importlib.resources.as_file(obo_path) as path:
+        db = parse_obo(Path(path))
+
+    if not include_obsolete:
+        return PsiModDatabase(e for e in db if not e.is_obsolete)
+    return db
+
+
+def load_from(path: Path | str) -> PsiModDatabase:
+    """Load PSI-MOD database from a custom OBO file path."""
+    from psimodpy.parser import parse_obo
+
+    return parse_obo(path)

psimodpy/models.py

@@ -0,0 +1,209 @@
+"""Domain model for PSI-MOD protein modification ontology entries."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class SynonymType(StrEnum):
+    """Synonym type labels defined in the PSI-MOD OBO file."""
+
+    DELTA_MASS_LABEL = "DeltaMass-label"
+    OMSSA_LABEL = "OMSSA-label"
+    PSI_MOD_LABEL = "PSI-MOD-label"
+    PSI_MOD_ALTERNATE = "PSI-MOD-alternate"
+    PSI_MS_LABEL = "PSI-MS-label"
+    RESID_NAME = "RESID-name"
+    RESID_ALTERNATE = "RESID-alternate"
+    RESID_SYSTEMATIC = "RESID-systematic"
+    RESID_MISNOMER = "RESID-misnomer"
+    UNIMOD_DESCRIPTION = "Unimod-description"
+    UNIMOD_ALTERNATE = "Unimod-alternate"
+    UNIMOD_INTERIM = "Unimod-interim"
+    UNIPROT_FEATURE = "UniProt-feature"
+
+
+class RelationshipType(StrEnum):
+    """Complex relationship types used in PSI-MOD beyond simple is_a hierarchy."""
+
+    DERIVES_FROM = "derives_from"
+    HAS_FUNCTIONAL_PARENT = "has_functional_parent"
+    CONTAINS = "contains"
+    PART_OF = "part_of"
+
+
+class TermSpec(StrEnum):
+    """Positional specificity of a modification on the protein sequence."""
+
+    NONE = "none"
+    N_TERM = "N-term"
+    C_TERM = "C-term"
+
+
+class Source(StrEnum):
+    """Origin classification of a modification."""
+
+    NATURAL = "natural"
+    ARTIFACT = "artifact"
+    # Four entries in the OBO use "artifactual" as a variant spelling
+    ARTIFACTUAL = "artifactual"
+    HYPOTHETICAL = "hypothetical"
+    NONE = "none"
+
+
+class AminoAcid(StrEnum):
+    """Single-letter amino acid codes used in PSI-MOD Origin xrefs."""
+
+    ALA = "A"
+    ARG = "R"
+    ASN = "N"
+    ASP = "D"
+    CYS = "C"
+    GLN = "Q"
+    GLU = "E"
+    GLY = "G"
+    HIS = "H"
+    ILE = "I"
+    LEU = "L"
+    LYS = "K"
+    MET = "M"
+    PHE = "F"
+    PRO = "P"
+    SER = "S"
+    THR = "T"
+    TRP = "W"
+    TYR = "Y"
+    VAL = "V"
+    SEC = "U"  # selenocysteine
+    PYL = "O"  # pyrrolysine
+    ANY = "X"  # unspecified / any residue
+
+
+@dataclass(frozen=True, slots=True)
+class Crosslink:
+    """Multi-residue or MOD-referenced modification origin.
+
+    Each site is either an :class:`AminoAcid` value (single letter) or a
+    ``"MOD:NNNNN"`` string for modifications-of-modifications.
+    """
+
+    sites: tuple[str, ...]
+    """Ordered residue sites, e.g. ``("C", "C")`` for a disulfide."""
+
+
+@dataclass(frozen=True, slots=True)
+class Synonym:
+    """A typed synonym for a PSI-MOD entry."""
+
+    value: str
+    type: SynonymType
+
+
+@dataclass(frozen=True, slots=True)
+class Relationship:
+    """A directed relationship from a PSI-MOD entry to another entry."""
+
+    type: RelationshipType
+    target_id: int
+
+
+@dataclass(frozen=True, slots=True)
+class PsiModEntry:
+    """A single term from the PSI-MOD protein modification ontology."""
+
+    id: int
+    """Numeric part of the MOD:NNNNN identifier."""
+
+    name: str
+    definition: str
+    """Quoted definition text; citation block stripped."""
+
+    synonyms: tuple[Synonym, ...]
+    is_a: tuple[int, ...]
+    """Parent term IDs (numeric). PSI-MOD entries can have multiple parents."""
+
+    relationships: tuple[Relationship, ...]
+    """derives_from / contains / part_of / has_functional_parent links."""
+
+    comment: str | None
+
+    # Mass and formula xrefs
+    diff_mono: float | None
+    """Monoisotopic mass difference (xref: DiffMono)."""
+
+    diff_avg: float | None
+    """Average mass difference (xref: DiffAvg)."""
+
+    diff_formula: str | None
+    """Elemental difference formula in PSI-MOD format, e.g. 'C 0 H 0 N 0 O 3 P 1'."""
+
+    mass_mono: float | None
+    """Full monoisotopic mass (xref: MassMono)."""
+
+    mass_avg: float | None
+    """Full average mass (xref: MassAvg)."""
+
+    formula: str | None
+    """Full elemental formula in PSI-MOD format. None when OBO value is 'none'."""
+
+    # Position/context xrefs
+    origin: AminoAcid | Crosslink | None
+    """Residue origin. Single residues are :class:`AminoAcid`; multi-residue
+    crosslinks or MOD-referenced origins are :class:`Crosslink`."""
+
+    term_spec: TermSpec | None
+    """Positional specificity (xref: TermSpec)."""
+
+    source: Source | None
+    """Modification source classification (xref: Source)."""
+
+    formal_charge: int | None
+    """Net formal charge as a signed integer, e.g. ``1``, ``-2`` (xref: FormalCharge)."""
+
+    # External cross-references
+    xref_unimod: str | None
+    """Unimod cross-reference, e.g. 'Unimod:21#S' (xref: Unimod)."""
+
+    xref_uniprot_ptm: str | None
+    """UniProt PTM cross-reference, e.g. 'PTM-0369' (xref: uniprot.ptm)."""
+
+    xref_gnome: str | None
+    """GNOme glycan ontology cross-reference, e.g. 'GNO:G29068FM' (xref: GNOme)."""
+
+    xref_remap: int | None
+    """Replacement term ID for obsolete entries (xref: Remap). Stored as numeric ID."""
+
+    in_slim_subset: bool
+    """True if this entry belongs to the PSI-MOD-slim curated subset."""
+
+    is_obsolete: bool
+    """True if this entry is marked obsolete in the OBO file."""
+
+    @property
+    def dict_diff_formula(self) -> dict[str, int] | None:
+        """Parse diff_formula into {element: count}. Returns None if no formula."""
+        if self.diff_formula is None:
+            return None
+        from psimodpy._formula import parse_formula
+
+        return parse_formula(self.diff_formula)
+
+    @property
+    def dict_formula(self) -> dict[str, int] | None:
+        """Parse formula into {element: count}. Returns None if no formula."""
+        if self.formula is None:
+            return None
+        from psimodpy._formula import parse_formula
+
+        return parse_formula(self.formula)
+
+    @property
+    def proforma_diff_formula(self) -> str | None:
+        """Hill-notation string for diff_formula, e.g. 'C2H2O'. Returns None if no formula."""
+        composition = self.dict_diff_formula
+        if composition is None:
+            return None
+        from psimodpy._formula import formula_to_hill
+
+        return formula_to_hill(composition)

psimodpy/parser.py

@@ -0,0 +1,250 @@
+"""OBO file parser for PSI-MOD protein modification ontology."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from psimodpy.models import (
+    AminoAcid,
+    Crosslink,
+    PsiModEntry,
+    Relationship,
+    RelationshipType,
+    Source,
+    Synonym,
+    SynonymType,
+    TermSpec,
+)
+
+if TYPE_CHECKING:
+    from psimodpy.database import PsiModDatabase
+
+# Compiled regexes (module-level, compiled once)
+_DEF_RE = re.compile(r'^def: "(.+?)"')
+_SYNONYM_RE = re.compile(r'^synonym: "(.+?)"\s+\w+\s+(\S+)\s+\[\]')
+_IS_A_RE = re.compile(r"^is_a:\s+MOD:(\d+)")
+_RELATIONSHIP_RE = re.compile(r"^relationship:\s+(\S+)\s+MOD:(\d+)")
+_XREF_RE = re.compile(r'^xref:\s+([^:]+):\s+"(.+?)"$')
+_XREF_UNIPROT_RE = re.compile(r"^xref:\s+(uniprot\.ptm):(\S+)$")
+_SUBSET_SLIM_RE = re.compile(r"^subset:\s+PSI-MOD-slim")
+
+
+def _parse_float(value: str | None) -> float | None:
+    if value is None or value == "none":
+        return None
+    return float(value)
+
+
+def _parse_str_or_none(value: str | None) -> str | None:
+    if value is None or value == "none":
+        return None
+    return value
+
+
+def _parse_formal_charge(value: str) -> int:
+    """Parse '1+' → 1, '2-' → -2."""
+    if value.endswith("+"):
+        return int(value[:-1])
+    if value.endswith("-"):
+        return -int(value[:-1])
+    return int(value)
+
+
+def _parse_origin(value: str) -> AminoAcid | Crosslink | None:
+    """Parse an Origin xref value into a typed representation.
+
+    - ``"none"`` → ``None``
+    - Single letter code → :class:`AminoAcid`
+    - Comma-separated, multi-residue, or MOD reference → :class:`Crosslink`
+    """
+    if value == "none":
+        return None
+    parts = [p.strip() for p in value.split(",")]
+    if len(parts) == 1:
+        try:
+            return AminoAcid(parts[0])
+        except ValueError:
+            # MOD:NNNNN reference or unrecognised code
+            return Crosslink(sites=(parts[0],))
+    return Crosslink(sites=tuple(parts))
+
+
+def _parse_mod_id(mod_str: str) -> int:
+    """Parse 'MOD:NNNNN' to int."""
+    return int(mod_str[4:])
+
+
+def _build_entry(block: list[str]) -> PsiModEntry | None:
+    """Parse a list of OBO lines for one [Term] block into a PsiModEntry."""
+    entry_id: int | None = None
+    name: str | None = None
+    definition: str = ""
+    synonyms: list[Synonym] = []
+    is_a: list[int] = []
+    relationships: list[Relationship] = []
+    comment: str | None = None
+    in_slim_subset: bool = False
+    is_obsolete: bool = False
+    xrefs: dict[str, str] = {}
+    xref_uniprot_ptm: str | None = None
+
+    for line in block:
+        if line.startswith("id: MOD:"):
+            entry_id = int(line[8:].split()[0])
+        elif line.startswith("name: "):
+            name = line[6:]
+        elif line.startswith("def: "):
+            m = _DEF_RE.match(line)
+            if m:
+                definition = m.group(1)
+        elif line.startswith("synonym: "):
+            m = _SYNONYM_RE.match(line)
+            if m:
+                value, type_str = m.group(1), m.group(2)
+                try:
+                    synonyms.append(Synonym(value=value, type=SynonymType(type_str)))
+                except ValueError:
+                    pass  # unknown synonym type — skip
+        elif line.startswith("is_a: "):
+            m = _IS_A_RE.match(line)
+            if m:
+                is_a.append(int(m.group(1)))
+        elif line.startswith("relationship: "):
+            m = _RELATIONSHIP_RE.match(line)
+            if m:
+                rel_type_str, target_id_str = m.group(1), m.group(2)
+                try:
+                    relationships.append(
+                        Relationship(
+                            type=RelationshipType(rel_type_str),
+                            target_id=int(target_id_str),
+                        )
+                    )
+                except ValueError:
+                    pass  # unknown relationship type — skip
+        elif _SUBSET_SLIM_RE.match(line):
+            in_slim_subset = True
+        elif line.startswith("comment: "):
+            comment = line[9:]
+        elif line == "is_obsolete: true":
+            is_obsolete = True
+        elif line.startswith("xref: "):
+            # Try uniprot.ptm special case first (no space before value)
+            m = _XREF_UNIPROT_RE.match(line)
+            if m:
+                xref_uniprot_ptm = m.group(2)
+                continue
+            # Standard xref: KEY: "VALUE"
+            m = _XREF_RE.match(line)
+            if m:
+                xrefs[m.group(1)] = m.group(2)
+
+    if entry_id is None or name is None:
+        return None
+
+    # Parse TermSpec
+    term_spec: TermSpec | None = None
+    if "TermSpec" in xrefs:
+        try:
+            term_spec = TermSpec(xrefs["TermSpec"])
+        except ValueError:
+            pass
+
+    # Parse Source
+    source: Source | None = None
+    if "Source" in xrefs:
+        try:
+            source = Source(xrefs["Source"])
+        except ValueError:
+            pass
+
+    # Parse Remap (obsolete redirect)
+    xref_remap: int | None = None
+    if "Remap" in xrefs:
+        try:
+            xref_remap = _parse_mod_id(xrefs["Remap"])
+        except (ValueError, IndexError):
+            pass
+
+    return PsiModEntry(
+        id=entry_id,
+        name=name,
+        definition=definition,
+        synonyms=tuple(synonyms),
+        is_a=tuple(is_a),
+        relationships=tuple(relationships),
+        comment=comment,
+        diff_mono=_parse_float(xrefs.get("DiffMono")),
+        diff_avg=_parse_float(xrefs.get("DiffAvg")),
+        diff_formula=_parse_str_or_none(xrefs.get("DiffFormula")),
+        mass_mono=_parse_float(xrefs.get("MassMono")),
+        mass_avg=_parse_float(xrefs.get("MassAvg")),
+        formula=_parse_str_or_none(xrefs.get("Formula")),
+        origin=_parse_origin(xrefs["Origin"]) if "Origin" in xrefs else None,
+        term_spec=term_spec,
+        source=source,
+        formal_charge=_parse_formal_charge(xrefs["FormalCharge"]) if "FormalCharge" in xrefs else None,
+        xref_unimod=xrefs.get("Unimod"),
+        xref_uniprot_ptm=xref_uniprot_ptm,
+        xref_gnome=xrefs.get("GNOme"),
+        xref_remap=xref_remap,
+        in_slim_subset=in_slim_subset,
+        is_obsolete=is_obsolete,
+    )
+
+
+def parse_obo(path: Path | str) -> PsiModDatabase:
+    """Parse a PSI-MOD OBO file and return a PsiModDatabase.
+
+    Args:
+        path: Path to the OBO file (str or Path).
+
+    Returns:
+        A PsiModDatabase populated with all parsed entries.
+    """
+    from psimodpy.database import PsiModDatabase
+
+    path = Path(path)
+    entries: list[PsiModEntry] = []
+    current_block: list[str] = []
+    in_term = False
+
+    with path.open(encoding="utf-8") as fh:
+        for raw_line in fh:
+            line = raw_line.rstrip("\n").rstrip("\r")
+
+            if line == "[Term]":
+                in_term = True
+                current_block = []
+                continue
+
+            if line.startswith("[") and line != "[Term]":
+                # End of a term block when another stanza starts
+                if in_term and current_block:
+                    entry = _build_entry(current_block)
+                    if entry is not None:
+                        entries.append(entry)
+                in_term = False
+                current_block = []
+                continue
+
+            if in_term:
+                if line == "":
+                    # Blank line ends the current block
+                    entry = _build_entry(current_block)
+                    if entry is not None:
+                        entries.append(entry)
+                    in_term = False
+                    current_block = []
+                else:
+                    current_block.append(line)
+
+    # Handle last block if file doesn't end with blank line
+    if in_term and current_block:
+        entry = _build_entry(current_block)
+        if entry is not None:
+            entries.append(entry)
+
+    return PsiModDatabase(entries)

psimodpy-0.1.0.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: psimodpy
+Version: 0.1.0
+Summary: Python library for the PSI-MOD protein modification ontology
+Project-URL: Homepage, https://github.com/tacular-omics/psimodpy
+Project-URL: Repository, https://github.com/tacular-omics/psimodpy
+Project-URL: Issues, https://github.com/tacular-omics/psimodpy/issues
+Project-URL: Changelog, https://github.com/tacular-omics/psimodpy/blob/main/HISTORY.md
+Author-email: Patrick Garrett <pgarrett@scripps.edu>
+Maintainer-email: Patrick Garrett <pgarrett@scripps.edu>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: PSI-MOD,bioinformatics,mass spectrometry,ontology,protein modification,proteomics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# psimodpy
+
+[![CI](https://github.com/tacular-omics/psimodpy/actions/workflows/ci.yml/badge.svg)](https://github.com/tacular-omics/psimodpy/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/psimodpy)](https://pypi.org/project/psimodpy/)
+[![Python](https://img.shields.io/pypi/pyversions/psimodpy)](https://pypi.org/project/psimodpy/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Python library for parsing and querying the [PSI-MOD](https://github.com/HUPO-PSI/psi-mod-CV) protein modification ontology.
+
+- Zero dependencies
+- Bundled PSI-MOD data (2,116 entries) — works offline out of the box
+- Typed, immutable data models (`py.typed` / PEP 561)
+
+## Installation
+
+```bash
+pip install psimodpy
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add psimodpy
+```
+
+Requires Python 3.12+. No third-party dependencies.
+
+## Quick Start
+
+```python
+import psimodpy
+
+# Load the bundled PSI-MOD database
+db = psimodpy.load()
+
+# Lookup by ID
+entry = db[46]  # O-phospho-L-serine
+print(entry.name)       # "O-phospho-L-serine"
+print(entry.diff_mono)  # 79.966331
+print(entry.origin)     # AminoAcid.SER
+
+# Lookup by name (case-insensitive)
+entry = db.get_by_name("O-phospho-L-serine")
+
+# Also accepts MOD:NNNNN format
+entry = db.get_by_id("MOD:00046")
+
+# Search across names, definitions, and synonyms
+results = db.search("phospho")
+
+# Find all modifications for an amino acid
+ser_mods = db.get_by_origin("S")
+
+# Filter entries
+slim = db.filter(slim_only=True, include_obsolete=False)
+
+# Formula parsing
+print(entry.dict_diff_formula)      # {'C': 0, 'H': 0, 'N': 0, 'O': 3, 'P': 1}
+print(entry.proforma_diff_formula)  # 'O3P'
+```
+
+## API Overview
+
+### Loading
+
+| Function | Description |
+|----------|-------------|
+| `psimodpy.load()` | Load the bundled PSI-MOD database. |
+| `psimodpy.load_from(path)` | Load from a custom OBO file. |
+| `psimodpy.parse_obo(path)` | Parse an OBO file into a database. |
+| `psimodpy.download_obo()` | Download the latest OBO file from GitHub. |
+
+### PsiModDatabase
+
+| Method | Description |
+|--------|-------------|
+| `db[id]` | Lookup by ID (int or `"MOD:00046"`), raises `KeyError`. |
+| `db.get_by_id(id)` | Lookup by ID, returns `None` if missing. |
+| `db.get_by_name(name)` | Case-insensitive name lookup. |
+| `db.search(query)` | Full-text search in names, definitions, synonyms. |
+| `db.get_by_origin(aa)` | Find entries by amino acid origin. |
+| `db.get_parents(entry)` | Direct parent entries (is_a hierarchy). |
+| `db.get_children(entry)` | Direct child entries. |
+| `db.get_related(entry, type)` | Follow relationship edges (derives_from, contains, etc.). |
+| `db.filter(...)` | Filter by obsolete/slim status. |
+
+### PsiModEntry
+
+Each entry provides: `id`, `name`, `definition`, `synonyms`, `is_a`, `relationships`,
+`origin`, `diff_mono`, `diff_avg`, `diff_formula`, `mass_mono`, `mass_avg`, `formula`,
+`term_spec`, `source`, `formal_charge`, `xref_unimod`, `xref_uniprot_ptm`, `xref_gnome`,
+`xref_remap`, `in_slim_subset`, `is_obsolete`.
+
+Computed properties: `dict_diff_formula`, `dict_formula`, `proforma_diff_formula`.
+
+### Data Types
+
+- `AminoAcid` — single-letter amino acid codes
+- `Crosslink` — multi-residue or MOD-referenced origins
+- `Synonym` / `SynonymType` — typed synonyms
+- `Relationship` / `RelationshipType` — directed relationships
+- `TermSpec` — positional specificity
+- `Source` — modification origin
+
+## Development
+
+```bash
+just install   # install dependencies with uv
+just lint      # ruff check
+just format    # ruff format
+just ty        # ty type check
+just test      # pytest
+just check     # lint + type check + test
+```
+
+## Related Projects
+
+| Package | Description |
+|---------|-------------|
+| [unimodpy](https://github.com/tacular-omics/unimodpy) | Parse and query the UNIMOD mass spectrometry modifications database |
+| [uniprotptmpy](https://github.com/tacular-omics/uniprotptmpy) | Parse and query the UniProt PTM controlled vocabulary |
+
+## License
+
+[MIT](LICENSE)

psimodpy-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+psimodpy/__init__.py,sha256=5CmPXmjdqJywxhuLjE_BiYJ4odYiSyThvxjcHGadAa0,665
+psimodpy/_download.py,sha256=oESOt1ewYBztzKLPrXfBGO6uE1M-RWDbwC3_g1-x5SU,1030
+psimodpy/_formula.py,sha256=-dY6bCaKgykgK09wrNauqL01UJS_6Fo1ivNjBt11stc,3147
+psimodpy/database.py,sha256=jgJabOB9FohKX53VPF5z2u0LlipjJtQ4AFg_qWh-uVM,6493
+psimodpy/models.py,sha256=re7m5RSfkM-O0zkNMC_ftCCDaGcdN8x_mVEaHMXANSA,5912
+psimodpy/parser.py,sha256=M3ypV0iZ7c1E97D8Bu5VQD8n3dX4c-xznrH3871KpF0,7983
+psimodpy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+psimodpy-0.1.0.dist-info/METADATA,sha256=IXLxtQ4yKpNKOL8QJ4WSH03c47TwYA99Q8Nz97YEatk,5175
+psimodpy-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+psimodpy-0.1.0.dist-info/licenses/LICENSE,sha256=pJQM8iXrAidark8oVv-HfWDWDgOrG5FCXUqXw1jWGfQ,1072
+psimodpy-0.1.0.dist-info/RECORD,,

psimodpy-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

psimodpy-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Garrett
+
+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.