psimodpy 0.1.0__tar.gz

psimodpy-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,38 @@
+## Copilot Instructions
+
+### VERY IMPORTANT INSTRUCTIONS
+
+USE THE JUSTFILE WHENEVER POSSIBLE. IF THERE IS NOT A JUSTFILE COMMAND CHECK AGAIN... IF THERE IS STILL NOT A FUCKING JUST COMAND... USE UV PACKAGE MANAGER! THIS IS ALREADY INSTALLED AND AVAILABLE. DO NOT, UNDER ANY CIRCUMSTANCES, INSTALL ANY DEPENDENCIES USING NPM, YARN, PIP, GEM, OR ANY OTHER PACKAGE MANAGER. AND NEVER USE PYHTON / PYTEST DIRECTLY!!! ALWAYS USE JUST FOR AVAILABLE COMMANDS AND ONLY FALL BACK TO UV IF THERE IS NO JUST COMMAND AVAILABLE. 
+
+### Available Tools
+- Use `just` for all project commands. See `just --list` for available commands.
+- Use `uv` for package management and running scripts. See `uv --help` for usage.
+- Use `git` for version control.
+- Use ty for type checking. `uv run ty check src/ tests/` or `just ty`
+- Use pytest for testing. `uv run pytest tests/` or `just test`
+- use ruff for linting and formatting. `uv run ruff check src/ tests/` or `just lint` and `uv run ruff format src/` or `just format`
+
+### Code Style & Philosophy
+
+- **Type everything**: Use comprehensive type hints (NDArray, Literal, Protocol, Self, etc.). Generic types should be specific. Use pyhton 3.12 features where applicable. Match-case statements preferred over if-elif chains for discrete values >= 3. Use list, tuple, set over List, Tuple, Set where possible. Dont use Union or Optional, use | operator.
+- **Immutability**: Prefer frozen dataclasses with `slots=True` and functional transformations over mutation. Though this is not absolute.
+- **Explicit over implicit**: Clear, descriptive names. No magic. If there's a performance trade-off, make it obvious.
+- **Simplicity**: Simple, readable code over clever one-liners. Break complex logic into smaller functions.
+
+Test do not need to be strongly typed but should still use type hints where reasonable. dont worry about exhaustive typing in tests, nor running ruff/ty on tests.
+
+### Documentation
+
+- Concise docstrings - no novels
+- Document the "why" when non-obvious, not the "what"
+- Type hints are documentation - don't repeat them in docstrings. Methods/Function should be able to get by with no/minimal docstrings if types are clear.
+- Use `Raises` section in docstrings for exceptions
+- No placeholder comments like "TODO: implement later" - use `raise NotImplementedError("reason")`
+
+### Response Style
+
+- Get to the point
+- Show code, minimal explanation
+- If I'm wrong, tell me directly
+- Assume I know Python well - no hand-holding
+

psimodpy-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync
+      - run: uv run ruff check src
+      - run: uv run ruff format --check src
+
+  type-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync
+      - run: uv run ty check src
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --python ${{ matrix.python-version }}
+      - run: uv run pytest tests
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

psimodpy-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

psimodpy-0.1.0/.gitignore

@@ -0,0 +1,118 @@
+# Data files (bundled copy lives in src/psimodpy/data/)
+PSI-MOD.obo
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   with no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducible builds.
+#   However, if you need to use different versions of dependencies on different environments,
+#   you may want to ignore it.
+#poetry.lock
+
+# uv
+.venv
+uv.lock
+
+# ruff
+.ruff_cache/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# editors
+.vscode/
+.idea/

psimodpy-0.1.0/HISTORY.md

@@ -0,0 +1,5 @@
+# History
+
+## 0.1.0 (2026-03-26)
+
+* First release on PyPI.

psimodpy-0.1.0/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.

psimodpy-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include HISTORY.md
+include README.md
+include .gitignore
+
+recursive-include tests *
+recursive-include .github *
+
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+
+recursive-include *.md justfile *.jpg *.png *.gif

psimodpy-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,125 @@
+# 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/justfile

@@ -0,0 +1,28 @@
+default: lint format check test
+
+# Install dependencies
+install:
+    uv sync
+
+# Run linting checks
+lint:
+    uv run ruff check src
+
+# Format code
+format:
+	uv run ruff check --select I --fix src
+	uv run ruff format src
+
+# Run ty type checker
+ty:
+    uv run ty check src
+
+# Run type checking
+check:
+    just lint
+    just ty
+    just test
+
+# Run tests
+test:
+    uv run pytest tests

psimodpy-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "psimodpy"
+version = "0.1.0"
+description = "Python library for the PSI-MOD protein modification ontology"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+dependencies = []
+authors = [
+    { name = "Patrick Garrett", email = "pgarrett@scripps.edu" }
+]
+maintainers = [
+    { name = "Patrick Garrett", email = "pgarrett@scripps.edu" }
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Typing :: Typed",
+]
+keywords = ["proteomics", "PSI-MOD", "protein modification", "ontology", "bioinformatics", "mass spectrometry"]
+
+[project.urls]
+Homepage = "https://github.com/tacular-omics/psimodpy"
+Repository = "https://github.com/tacular-omics/psimodpy"
+Issues = "https://github.com/tacular-omics/psimodpy/issues"
+Changelog = "https://github.com/tacular-omics/psimodpy/blob/main/HISTORY.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/psimodpy"]
+
+[tool.uv]
+package = true
+dev-dependencies = [
+    "pytest>=9.0.2",
+    "ruff>=0.14.11",
+    "ty>=0.0.11",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # Pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "UP",  # pyupgrade
+]
+