Proposal: Archive eutils and recommend that people use biopython

[reece]

Summary

The eutils package has outlived the motivations for its creation. With the exception of some recent work by Reece, it's been effectively unmaintained for years. BioPython is more comprehensive and better maintained. Therefore, eutils should be archived and we should recommend that developers use BioPython.

Background

eutils was started in 2014 in order to provide specific functionality to build uta and other tools at Locus Development (later acquired by Invitae). It was a conscious decision to create a pure Python package to interact with NCBI eutils, rather than to use biopython, which took many (many) minutes to compile dependencies and had fragile dependencies that needed to be compiled. Since then, eutils has been effectively abandoned whereas BioPython is more comprehensive and maintained. Furthermore, the Python packaging ecosystem has improved dramatically; with uv, installing BioPython from a local cache and takes one second (SSD).

uta loading needs to be overhauled and can likely be readily refactored to use BioPython rather than eutils. No other biocommons packages use eutils.

eutils currently has one known bug that is expected to represent a class of existing unknown bugs and future work. Changing XML formats from NCBI means some of the xmlfacades currently give incorrect results (see #177). There is little point in fixing these since they are believed to work correctly in BioPython.

Alternatives Considered

• Look for a new maintainer
• Keep eutils for the simplified interface, but use BioPython for fetching and parsing

Appendix: What does Claude think?

I asked Claude Code to review eutils code and compare with BioPython.

Review the code in this repo. Compare the functionality with that of biopython. Create a list of anything that eutils can do that is not available in biopython. I'm looking for the honest answer, so no fluff.

Honest Assessment: eutils vs Biopython

Based on a review of the eutils codebase and comparison with biopython's capabilities, here's the straightforward answer:

What eutils can do that biopython cannot:

Very little that's truly unique. Most of what eutils provides is a convenience layer. Here are the only substantive differences:

1. Unified object-oriented facades for multiple data types - eutils provides pre-built Python classes with property accessors for parsing GenBank sequences, PubMed articles, Gene records, and SNP data. Biopython's Entrez.read() returns nested dictionaries/lists that you have to manually navigate. Eutils handles the boilerplate of extracting data from XML with named properties like .acv, .pmid, .title, etc.

2. Persistent SQLite caching - eutils has built-in compressed caching of NCBI responses with optional expiration. Biopython has no built-in caching mechanism.

3. Specialized convenience lookups - The ClientX class (in sketchy/) provides high-level functions like fetch_gene_by_hgnc() and fetch_snps_for_gene(). Biopython requires you to construct the queries yourself.

4. Cleaner API for common tasks - Things like accessing exon coordinates or parsing gene commentary data are simpler with eutils' property-based accessors versus navigating the XML trees that biopython returns.

What biopython does better or equivalently:

• API access: Both provide the same underlying e-utilities (esearch, efetch, elink, einfo, esummary, etc.)
• Rate limiting: Both respect NCBI's 3 req/sec limit and support API keys for 10 req/sec
• Format conversion: Biopython's Bio.SeqIO seamlessly converts between sequence formats (GenBank, FASTA, etc.), which is more powerful for general bioinformatics work
• Ecosystem: Biopython integrates with everything else in the bioinformatics world (alignment tools, structure analysis, etc.)

The honest bottom line:

For most users, biopython is the better choice. Here's why:

• You get all the core NCBI query functionality
• The dictionary/list output is actually flexible enough for most use cases
• When you need structured access to specific fields, you can quickly write simple helper functions
• You get a massive ecosystem of bioinformatics tools that work with biopython's objects
• Better community support and documentation
• More actively maintained

eutils makes sense only if:

• You're doing extensive work with specific NCBI data types where the pre-built facades save significant typing
• You need the SQLite caching for repeated queries
• You're already locked into it in an existing codebase
• You want the convenience of fetch_gene_by_hgnc() style lookups

The reality is that eutils primarily provides syntactic convenience. It doesn't enable anything fundamentally different from biopython—it just wraps the XML parsing with named properties. For new projects, recommending biopython would be honest and accurate guidance.

Sources

• Bio.Entrez package — Biopython 1.86 documentation
• Accessing NCBI's Entrez databases — Biopython 1.87.dev0 documentation

[korikuzma]

I'm fine archiving eutils if biopython does a better job and is better maintained.

We don't use eutils in any of the projects I help maintain, and I think I'd rather see effort go towards more frequently used biocommons projects (such as hgvs, seqrepo, uta, etc.) than eutils.

[ahwagner]

Agree. We should leverage and support other actively maintained community packages where they exist and meet our needs.