Imported from wikipathways/pywikipathways (
AGENTS.md). Install upstream withnpx skills add wikipathways/pywikipathways. Copyright stays with the author.
pywikipathways Agent Guide
Use this file as the first stop when changing code or docs. Default triage order: keep regressions and API compatibility first, then small improvements, then new endpoints.
Mission and Scope
- This Python package is a faithful port of rWikiPathways to Python. Function behaviour and processing logic must match the R original.
- Provide Python interfaces for WikiPathways operations; parity with rWikiPathways is the long-term goal.
- Core package lives in
pywikipathways/; each module wraps either a static JSON endpoint or a live webservice call. - This repo is user-facing (published on PyPI) and powers scientific workflows; prioritise backwards compatibility and clear error handling.
Porting from rWikiPathways
- Naming: Apply the same porting rules as RCy3 → py4cytoscape: convert file names and function names from camelCase to snake_case (e.g.
getPathwayInfo→get_pathway_info,FindPathwaysByLiterature→find_pathways_by_literature). - Behaviour: Port function processing faithfully from the R source—same inputs, same outputs, same edge cases and error semantics. Do not change logic or add behaviour that diverges from the original.
- Keep argument names aligned with the R originals where possible (snake_case in Python).
- Do not port rWikiPathways
R/utilities.R: it is deprecated; do not add the porting to this package. - Do not port any R functions annotated with
#' @title DEPRECATED:. Port only the non-deprecated functions (e.g. https://github.com/wikipathways/rWikiPathways/blob/devel/R/getCurationStatus.R#L1-L19 ).
Code Structure and Conventions
pywikipathways/utilities.pyholds shared HTTP helpers (wikipathways_get,build_url). Reuse and extend these rather than duplicating request code.- Individual feature modules (for example
find_pathways_by_literature.py,get_pathway_info.py,get_counts.py) follow a consistent pattern: validate inputs, request JSON (static files underhttps://www.wikipathways.org/json/when available), normalise intopandas.DataFrameorSeries, returnNonewhen nothing is found, and print a diagnostic on exceptions. Match this behaviour in new wrappers. - Docstrings stay descriptive and include example calls; mimic the concise numpy-style tone used today.
- Maintain snake_case function names and keep argument names aligned with the R originals whenever possible.
- Data shapes: pathway lists are typically
DataFramerows with pathway identifiers, names, species, and URLs; single lookups often returnSerieskeyed by field name. Preserve column/index naming when adding wrappers.
Error Handling Checklist
- Validate inputs early; prefer informative
ValueErroronly when caller mistakes are clear. - On network or parsing issues return
Noneand print a short diagnostic so downstream code can detect outages. - Access JSON defensively (use
.getwith defaults) because static mirrors can drift. - Avoid raising raw exceptions from third-party libraries; translate into the patterns above.
New Endpoint Recipe
- Inspect the remote JSON first (manual
requestscall) to confirm shape and required params. - Build URLs with
build_urland fetch withwikipathways_get; keep new helper logic inutilities.pyif it will be shared. - Normalise to
pandasobjects with stable column/index names; avoid hard-coding counts. - Add a concise docstring example, a focused pytest (happy path, schema not counts), and a brief docs note in
README.mdordocs/.
Network and Tests
- Tests live in
tests/and usepytest. Run from the repo root. They rely on live WikiPathways endpoints; avoid hammering the service (space out runs, prefer targetedpytest tests/<module> -k happyduring iteration). - If network is unavailable (CI or local), mark affected tests
xfailor skip with a clear reason instead of removing them. - Manual smoke checks are encouraged for new endpoints before wiring them into
pandas.
Development Workflow
- Use a virtual environment and install locally with
pip install -e .to iterate quickly. uvworks out of the box withpyproject.toml;uv pip install -e .anduv run pytestmirror the pip workflow.- Respect the repo’s minimum Python version (see
pyproject.toml) and keep dependencies lightweight—prefer standard library or existing deps (requests,pandas,lxml). - When touching generation scripts or notebooks (see
docs/pywikipathways_Overview.ipynb), keep output size modest and consider moving long examples into docs instead of inline tests. - For new functionality, update
README.mdand Read the Docs sources underdocs/so users discover additions. - Friendly API behaviour matters: deprecate gently and note behavioural changes in
LITERATURE_API_UPDATE.mdor a similar short note.
Release and Tooling
- Packaging metadata lives in
pyproject.toml; bump the version there when releasing. Build withpython -m buildand publish withtwineafter verifyingREADME.mdrenders. - Licensing is MIT (
LICENSE). - Prefer existing formatting/lint settings in the repo; if unsure, mirror current style and keep changes minimal.
Common Pitfalls
- Static JSON mirrors can drift; handle missing keys defensively and emit user-friendly messages instead of raising raw exceptions.
- Downstream consumers expect
Noneon network failures—mirror this behaviour so callers can detect outages. - Avoid large downloads or storing generated data in the repo; rely on runtime fetching.
