feat: modernize API - #22
Open
cvigilv wants to merge 22 commits into
Open
Conversation
BREAKING CHANGE: - Rename all public API functions to use `kegg_` prefix (e.g., `find` → `kegg_find`, `conv` → `kegg_conv`, etc.) - Remove deprecated `Images.jl` and related image helper functions - Refactor `kegg_get` for improved chunking, option validation, and response parsing - Update exports and tests to use new function names and signatures - Improve documentation and warnings for API usage and rate limits
…equests - Add HTTP dependency for direct API requests - Refactor `kegg_list` to support pathway, brite, and organism queries with improved docstrings - Implement chunked batch requests for lists of dbentries with rate limiting - Improve error handling and result structuring - Update documentation for new usage patterns
Owner
Author
|
This should more or less be done, I did a pass over everything. @bwbioinfo have a minute to check if things look good? |
There was a problem hiding this comment.
Pull request overview
This PR modernizes KEGGAPI’s public interface by consolidating REST operations under a consistent kegg_* API surface, unifying request outputs, and expanding parsing/option support (including a kegg"..." string macro), with corresponding test and documentation updates.
Changes:
- Renames and standardizes core endpoints (
kegg_info,kegg_list,kegg_find,kegg_get,kegg_conv,kegg_link) and updates exports/includes accordingly. - Refactors
kegg_getto supportoption::Union{Symbol,Nothing}and adds response processors (including image handling) plus thekegg"..."macro. - Updates tests and docs to use the modernized API and expands REST coverage.
Reviewed changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| test/test_requests.jl | Updates and expands request/API tests for the modernized kegg_* surface. |
| src/utils.jl | Adds a chunk_vector helper (currently not wired into the module). |
| src/Structures.jl | Adjusts KeggTupleList fields to support multi-URL requests and missing column names. |
| src/Requests.jl | Extends request to support typed body conversion via an optional type parameter. |
| src/Parsers.jl | Improves parser signatures/formatting and returns Kegg*List objects directly. |
| src/List.jl | Reworks kegg_list and adds vector-entry overload with chunking and timeouts. |
| src/Link.jl | Renames and extends link operations, including chunked vector-entry support. |
| src/Conv.jl | Renames and extends conversion operations, including chunked vector-entry support. |
| src/Get.jl | Major rework of kegg_get: option validation, processors, chunking, and string macro. |
| src/Find.jl | Renames find → kegg_find. |
| src/Info.jl | Renames info → kegg_info and expands docs. |
| src/KEGGAPI.jl | Updates exports and include list (removes Images include). |
| src/Images.jl | Removes legacy get_image/save_image implementation in favor of kegg_get(..., :image). |
| docs/src/man/getting-started.md | Updates docs examples to use kegg_list. |
| docs/src/man/examples.md | Updates docs examples to use kegg_conv. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
150
to
154
| function kegg_get(dbentry::String, args...; kwargs...) | ||
| r = kegg_get([dbentry], args...; kwargs...) | ||
| if length(args) > 0 && args[1] == :image | ||
| d = r.data | ||
| else |
Comment on lines
+54
to
+58
| data = [] | ||
| try | ||
| HTTP.open(:GET, url) do stream | ||
| while !eof(stream) | ||
| chunk = readavailable(stream) |> String |
Owner
Author
There was a problem hiding this comment.
While I'm completely on board with this observation, it rules out the possibility of running big queries. Maybe we can add a flag to stream the contents? @bwbioinfo what do you think?
Comment on lines
+1
to
+3
| function chunk_vector(vec::Vector, chunk_size::Int) | ||
| return [vec[i:min(i + chunk_size - 1, end)] for i in 1:chunk_size:length(vec)] | ||
| end |
| """ | ||
| function kegg_get(dbentries::Vector{String}, option::Union{Symbol, Nothing} = nothing; timeout::Float64 = 0.4) | ||
| validate_get_option(option) | ||
| timeout < 0.334 && @warn "Setting timeout to less than 0.4 seconds may lead to API rate limit errors. Consider increasing the timeout to avoid this issue." |
Owner
Author
There was a problem hiding this comment.
@copilot Maybe we can change the warning message to "KEGG API accepts 3 requests per second. Current timeout may lead to API rate limit errors..."
There was a problem hiding this comment.
Updated in 4793e87: the timeout warning now reads KEGG API accepts 3 requests per second. Current timeout may lead to API rate limit errors. and the related warning assertion in test/test_requests.jl was updated to match.
bwbioinfo
reviewed
Jul 9, 2026
|
|
||
| # Define the URL for the API request based on the provided 'list' argument. | ||
| function kegg_list(query::String, query_type::String = "") | ||
| url = "https://rest.kegg.jp/list/$query" |
Collaborator
There was a problem hiding this comment.
The two-argument form is documented above (kegg_list(pathway::String, org::String) / kegg_list(brite::String, option::String)), but this URL still ignores query_type. For example, kegg_list("pathway", "hsa") currently calls /list/pathway and returns generic map... pathways instead of /list/pathway/hsa with organism-specific hsa... pathways. Since this PR modernizes and documents the list API, this should either append the second path segment when provided or remove the documented overload.
Owner
Author
There was a problem hiding this comment.
You are right! This slipped between the cracks when normalizing the naming convention. I'll change it and properly cover this with a test
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
…KEGGAPI.jl into feat-standarize-function-naming
Bring the wrapper surface closer to the current KEGG REST API: - Add kegg_ddi (adverse drug-drug interactions) in src/Ddi.jl with a ddi_parser producing 4 columns (Entry 1, Entry 2, Interaction Type, Mechanism); wire include/export/precompile. - Rewrite kegg_find as pass-through: any recognized KEGG database is allowed, unknown names warn but still pass through, and options (formula/exact_mass/mol_weight/nop) are validated for compound/drug. Fixes the old whitelist that rejected ko/enzyme/genome/etc. and the bogus "orthology" database name. - Add the :image2x get option (doubled-size reference-pathway PNG), routed through request_other/parse_as_image; simplify the redundant scalar-method image branch. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- kegg_link gains an optional `option` argument on both methods: a taxonomic rank (species..phylum) for genome/taxonomy links, or an RDF output format (turtle/n-triple) for drug/atc/jtc. RDF options return the raw response text; all other results stay as KeggTupleList. - Refresh the "allowed database" tables in the info/list/get docstrings to the current KEGG database set (adds ag/vg/vp/vtax/vgenome/rmodule/ network/ntmap/variant). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Add live integration tests for kegg_ddi, the generalized kegg_find (new databases, option validation, unknown-db warning), the kegg_link RDF (turtle) path, and the kegg_get :image2x option. - Update examples/example01.jl to the current kegg_* API (the old info/list/find/conv/link and get_image/save_image names were removed), fix orthology -> ko, and add kegg_ddi + image-save examples. - Update the AGENTS.md export list to the current public surface. - Apply Runic formatting across src/test/docs/examples. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…build resilient KEGG removed the special `organism` database name from the `list` operation (https://rest.kegg.jp/list/organism now returns HTTP 400); the list of KEGG organisms is obtained via the `genome` database instead (e.g. list/genome, list/genome/<group>, list/genome/<rank_id>). This had broken the docdeploy, which runs the manual @example blocks against the live API at build time. - docs/getting-started: list organisms via kegg_list("genome") (returns a KeggTupleList) instead of the removed kegg_list("organism"). - List.jl docstring: drop `organism` from the allowed databases, document the genome/brite option forms, and point organism listing at `genome`. - examples/example01.jl: same organism -> genome switch. - docs/make.jl: keep `warnonly = [:example_block]` so a transient KEGG outage during a build degrades to a warning instead of failing the deploy. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The special `organism` database name was removed from the KEGG list
operation (see previous commit), so the `query == "organism"` branch in
kegg_list could only ever produce a RequestError. Remove it along with
its now-unused organism_parser and KeggOrganismList type. Organism
listing is handled by the generic path via kegg_list("genome").
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Translate the example Colab case notebooks (examples/Case1-4.ipynb) into Documenter tutorial pages under a new "Use cases" nav section: - Case 1: UniProt/Swiss-Prot ID to KEGG gene, sequences, orthology, reactions and pathways. - Case 2: EC number to KEGG reactions, compounds and orthology. - Case 3: find a compound by name, its entry and linked reactions. - Case 4: target molecule to gene, pathways and associated drugs. The pages are modernized to the current kegg_* API (symbol get options, NamedTuple .data access) and correct the notebooks where they misused find with full IDs (now kegg_get). KEGG-query steps run as live @example blocks; file/image I/O steps are shown as non-executed code. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR aims to modernize and streamline all API calls implemented to date. The idea is to provide a unified way to access request results, improve error handling, and support additional parsers and processors for responses.
Things to do:
getunderstandoptionparameter in REST APIgetandget_imagekegg"<string>"macrogetflat file parserOnce this modernization is complete, the idea is to add package extensions to read from commonly used packages (e.g., DataFrames.jl, MolecularGraphs.jl, Graphs.jl, etc.).