PubMed Client - Python Bindings

PyPI version Python 3.12+ License: MIT

Python bindings for the PubMed and PMC (PubMed Central) API client library.

Overview

This package provides Python bindings to the Rust-based PubMed client library, enabling high-performance access to PubMed and PMC APIs from Python.

Features

  • PubMed API: Search and retrieve article metadata
  • PMC API: Access full-text articles from PubMed Central
  • ELink API: Get related articles, citations, and PMC links
  • SearchQuery Builder: Build complex queries programmatically with filters
  • High Performance: Built with Rust for speed and reliability
  • Type-Safe: Full type hints for better IDE support

Installation

From PyPI

pip install pubmed-client-py

With uv

uv add pubmed-client-py

From Source

# Clone the repository
git clone https://github.com/illumination-k/pubmed-client.git
cd pubmed-client/pubmed-client-py

# Create virtual environment and install
uv venv
uv run --with maturin maturin develop

Quick Start

Basic Usage

import pubmed_client

# Create a unified client
client = pubmed_client.Client()

# Search PubMed
articles = client.pubmed.search_and_fetch("covid-19 vaccine", max_results=10)

for article in articles:
    print(f"Title: {article.title}")
    print(f"PMID: {article.pmid}")
    print(f"Journal: {article.journal}")
    print()

Fetch Single Article

import pubmed_client

client = pubmed_client.Client()

# Fetch article by PMID
article = client.pubmed.fetch_article("31978945")

print(f"Title: {article.title}")
print(f"Authors: {article.author_count}")
print(f"Abstract: {article.abstract_text[:200]}...")

# Access authors and affiliations
for author in article.authors():
    print(f"  {author.full_name}")
    if author.orcid:
        print(f"    ORCID: {author.orcid}")

Fetch PMC Full-Text

import pubmed_client

client = pubmed_client.Client()

# Fetch full text from PMC
full_text = client.pmc.fetch_full_text("PMC7906746")

print(f"Title: {full_text.title}")
print(f"Sections: {len(full_text.sections())}")
print(f"References: {len(full_text.references())}")

# Access article sections
for section in full_text.sections():
    print(f"Section: {section.title}")
    print(f"Content: {section.content[:200]}...")

# Access figures and tables
for figure in full_text.figures():
    print(f"Figure: {figure.label}")
    print(f"Caption: {figure.caption}")

# Convert to Markdown
markdown = full_text.to_markdown()
print(markdown)

Citation Analysis

import pubmed_client

client = pubmed_client.Client()

# Get citations for an article
citations = client.get_citations([31978945])
print(f"Citation count: {len(citations)}")

# Get citing article PMIDs
for citing_pmid in citations.citing_pmids[:10]:
    print(f"Cited by: {citing_pmid}")

Related Articles and PMC Links

import pubmed_client

client = pubmed_client.Client()

# Find related articles
related = client.get_related_articles([31978945])
print(f"Found {len(related.related_pmids)} related articles")

# Check PMC full-text availability
pmc_links = client.get_pmc_links([31978945])
print(f"PMC IDs available: {pmc_links.pmc_ids}")

Using SearchQuery Builder

import pubmed_client

client = pubmed_client.Client()

# Build a complex query
query = (
    pubmed_client.SearchQuery()
    .query("cancer")
    .published_between(2020, 2024)
    .article_type("Clinical Trial")
    .free_full_text_only()
    .limit(50)
)

# Execute the search
articles = client.pubmed.search_and_fetch(query, 0)  # limit ignored when using SearchQuery

for article in articles:
    print(f"[{article.pmid}] {article.title}")

Boolean Query Combinations

import pubmed_client

# Build complex queries with boolean logic
q1 = pubmed_client.SearchQuery().query("covid-19")
q2 = pubmed_client.SearchQuery().query("vaccine")
q3 = pubmed_client.SearchQuery().query("efficacy")

# Combine with AND
combined = q1.and_(q2).and_(q3)
print(combined.build())  # ((covid-19) AND (vaccine)) AND (efficacy)

# Combine with OR
either = q1.or_(q2)
print(either.build())  # (covid-19) OR (vaccine)

# Exclude specific terms
base = pubmed_client.SearchQuery().query("treatment")
excluded = pubmed_client.SearchQuery().query("animal studies")
human_only = base.exclude(excluded)
print(human_only.build())  # (treatment) NOT (animal studies)

Extract Figures from PMC Articles

import pubmed_client

client = pubmed_client.Client()

# Download and extract figures with captions
figures = client.pmc.extract_figures_with_captions("PMC7906746", "./output")

for fig in figures:
    print(f"Figure: {fig.figure.label}")
    print(f"Caption: {fig.figure.caption}")
    print(f"File: {fig.extracted_file_path}")
    print(f"Size: {fig.file_size} bytes")
    if fig.dimensions:
        print(f"Dimensions: {fig.dimensions[0]}x{fig.dimensions[1]}")

Configuration

With API Key

Using an NCBI API key increases rate limits from 3 to 10 requests per second:

import pubmed_client

config = (
    pubmed_client.ClientConfig()
    .with_api_key("your_ncbi_api_key")
    .with_email("your@email.com")
    .with_tool("YourAppName")
)

client = pubmed_client.Client.with_config(config)

Rate Limiting

import pubmed_client

config = (
    pubmed_client.ClientConfig()
    .with_rate_limit(2.0)  # 2 requests per second
    .with_timeout_seconds(60)  # 60 second timeout
)

client = pubmed_client.Client.with_config(config)

Type Hints and IDE Support

The package includes complete type stubs (.pyi files) for full IDE autocomplete and type checking:

import pubmed_client

# Type hints work automatically
config: pubmed_client.ClientConfig = pubmed_client.ClientConfig()
client: pubmed_client.Client = pubmed_client.Client.with_config(config)
articles: list[pubmed_client.PubMedArticle] = client.pubmed.search_and_fetch("query", 10)

Run type checking with mypy:

mypy your_script.py

Maintaining the type stub

pubmed_client.pyi is generated, not hand-edited. It is produced from the #[gen_stub_pyclass] / #[gen_stub_pymethods] annotations in the Rust source by the stub_gen binary, which then splices in the members pyo3-stub-gen cannot introspect (__version__ and the create_exception! hierarchy).

When you add or change a PyO3 class, method, or attribute:

  1. Annotate the new #[pyclass] with #[gen_stub_pyclass] and every #[pymethods] block with #[gen_stub_pymethods] (module-level items added via m.add(...), such as new exceptions, also need to be listed in stub_gen.rs).

  2. Regenerate the stub:

    MISE_ENV=python mise run stubgen:py     # or: cargo run --bin stub_gen

  3. Verify it matches the compiled module:

    MISE_ENV=python mise run stubtest:py    # maturin develop + python -m mypy.stubtest

  4. Commit the regenerated pubmed_client.pyi.

CI enforces both halves: the Python Type Stub Check job regenerates the stub and fails on git diff if the checked-in copy is stale, then runs stubtest so the stub can never silently drift from the compiled module. stubtest-allowlist.txt records the intentionally-unstubbed internal extension submodule.

Development

Prerequisites

  • Python >= 3.12
  • Rust toolchain (installed via rustup)
  • uv (for Python package management)
  • maturin (for building Python bindings)

Setup Development Environment

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment
cd pubmed-client-py
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Build and install in development mode
uv run --with maturin maturin develop

Running Tests

# Install dev dependencies
uv sync --group dev

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=pubmed_client

Code Quality

# Format code
uv run ruff format

# Lint code
uv run ruff check

# Type checking
uv run mypy tests/

Building

# Build wheel
uv run --with maturin maturin build --release

# Build for distribution
uv run --with maturin maturin build --release --sdist

Publishing

# Publish to PyPI (requires credentials)
uv run --with maturin maturin publish

License

MIT

Links

Project links

Data verified by PyPI on Aug 3, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.4.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for illumination-k from gravatar.com illumination-k

Credits

Author: illumination-k

GitHub Statistics

Data verified by PyPI on Aug 3, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.12

Tags

pubmed pmc biomedical research api bioinformatics

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pubmed_client_py-0.3.1.tar.gz (840.0 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

pubmed_client_py-0.3.1-cp314-cp314-win_amd64.whl (3.8 MB view details)

Uploaded CPython 3.14Windows x86-64

pubmed_client_py-0.3.1-cp314-cp314-macosx_11_0_arm64.whl (4.0 MB view details)

Uploaded CPython 3.14macOS 11.0+ ARM64

pubmed_client_py-0.3.1-cp314-cp314-macosx_10_12_x86_64.whl (4.1 MB view details)

Uploaded CPython 3.14macOS 10.12+ x86-64

pubmed_client_py-0.3.1-cp313-cp313-win_amd64.whl (3.8 MB view details)

Uploaded CPython 3.13Windows x86-64

pubmed_client_py-0.3.1-cp313-cp313-macosx_11_0_arm64.whl (4.0 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

pubmed_client_py-0.3.1-cp313-cp313-macosx_10_12_x86_64.whl (4.1 MB view details)

Uploaded CPython 3.13macOS 10.12+ x86-64

pubmed_client_py-0.3.1-cp312-cp312-win_amd64.whl (3.8 MB view details)

Uploaded CPython 3.12Windows x86-64

pubmed_client_py-0.3.1-cp312-cp312-manylinux_2_38_x86_64.whl (6.7 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.38+ x86-64

pubmed_client_py-0.3.1-cp312-cp312-macosx_11_0_arm64.whl (4.0 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

pubmed_client_py-0.3.1-cp312-cp312-macosx_10_12_x86_64.whl (4.1 MB view details)

Uploaded CPython 3.12macOS 10.12+ x86-64

File details

Details for the file pubmed_client_py-0.3.1.tar.gz.

File metadata

  • Download URL: pubmed_client_py-0.3.1.tar.gz
  • Upload date:
  • Size: 840.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for pubmed_client_py-0.3.1.tar.gz
Algorithm Hash digest
SHA256 d2532aa9c8ed8057dae69b1fb10a62078b52af55c5562e683f196e648b3761cb
MD5 6fefbce5ed731c775aae073aec0e022a
BLAKE2b-256 91cf6afbe77bddc48c85f37b8b0abb633c110392e8eb9cefad5f1faed6e62d34

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.1.tar.gz:

Publisher: release.yml on illumination-k/pubmed-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pubmed_client_py-0.3.1-cp314-cp314-win_amd64.whl.

File metadata

File hashes

Hashes for pubmed_client_py-0.3.1-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 3097ff1d2cf28b050d7afdc9c134a53902fc81c0d4e6021bb740a49edeabfe16
MD5 62ec7b222f8b21fce70fe7862ac34cf4
BLAKE2b-256 7ffa06c449434ff84d913df508d9ab267124e1f81e1bf746da44bc5ca574aaaa

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.1-cp314-cp314-win_amd64.whl:

Publisher: release.yml on illumination-k/pubmed-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pubmed_client_py-0.3.1-cp314-cp314-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pubmed_client_py-0.3.1-cp314-cp314-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 6cc3f8b88c6506bb381d7b9d33cfc5b32ccecdf4ccb1ac539a60bce362906245
MD5 fea73e7498e66c2ae32388326294cc5a
BLAKE2b-256 0dc0823268bcc9f3735dfde1dbff0ceee6ae06ea58d1834176f43f4e4beaa315

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.1-cp314-cp314-macosx_11_0_arm64.whl:

Publisher: release.yml on illumination-k/pubmed-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pubmed_client_py-0.3.1-cp314-cp314-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for pubmed_client_py-0.3.1-cp314-cp314-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 9493de5cff7cef4ef1c605bc2d5c206fbff4acbd07877f854ea932a3350775ae
MD5 ca861a129c5a3cc4d7b68dc1b6c74c09
BLAKE2b-256 f43c66e874fb10fd5ee50633f6fa7c0162f7100f748a6ec49c1626ca8f369c12

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.1-cp314-cp314-macosx_10_12_x86_64.whl:

Publisher: release.yml on illumination-k/pubmed-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pubmed_client_py-0.3.1-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for pubmed_client_py-0.3.1-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 1944907092bcdfaf79f83eaab73f15130e09191db0f4817d787cafc079bc46f7
MD5 a4116b036db53bdca2f077954c771443
BLAKE2b-256 f5586c0746a6163e3220c679214ca4a076c430fef7ad924a7d281e70e9d21ead

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.1-cp313-cp313-win_amd64.whl:

Publisher: release.yml on illumination-k/pubmed-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pubmed_client_py-0.3.1-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pubmed_client_py-0.3.1-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1d7e8fd2fd24d02befe19ba377d2c646ddb5638b16fb41604c2ebb0c2b5c4da6
MD5 bd461b45eebf3340e5caf2a3cc79ef69
BLAKE2b-256 353dca594c610f3ebb1a8d2da6ac43b06a1a65f46000394de131a7991fe26922

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.1-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: release.yml on illumination-k/pubmed-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pubmed_client_py-0.3.1-cp313-cp313-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for pubmed_client_py-0.3.1-cp313-cp313-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 1ee6c04232ec82c366657e1ffbfab607fad0b1e26434b5a150d058fa23ad8922
MD5 d99512d81d8bbd489630afc60cfbb3dc
BLAKE2b-256 d3c9454c277452b9ef883ffcaa0d443f018d421cc229cb83b7fef8bee42e6af5

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.1-cp313-cp313-macosx_10_12_x86_64.whl:

Publisher: release.yml on illumination-k/pubmed-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pubmed_client_py-0.3.1-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for pubmed_client_py-0.3.1-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 af77d85473b0d78fd165d4147027c3cfe19c1589d4130ce98e43cc99235cf810
MD5 12bc3e5eecbdc26aa740ef465d713b20
BLAKE2b-256 7fa9dbf72fd3e2ed2d4561efcc4819c56c853d61b6832d1d820dd3739e6279aa

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.1-cp312-cp312-win_amd64.whl:

Publisher: release.yml on illumination-k/pubmed-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pubmed_client_py-0.3.1-cp312-cp312-manylinux_2_38_x86_64.whl.

File metadata

File hashes

Hashes for pubmed_client_py-0.3.1-cp312-cp312-manylinux_2_38_x86_64.whl
Algorithm Hash digest
SHA256 c5d86c24a468ff484fca7da97e3ab74bc352dc8d2f0a039987eb81acfc40e565
MD5 9c00d8090605964c1cf6b96562fe17e5
BLAKE2b-256 4f2a4ccf96ce970ff0e6213c4faba3b427be7f496b3a6e2d3d1b1a53af171ee7

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.1-cp312-cp312-manylinux_2_38_x86_64.whl:

Publisher: release.yml on illumination-k/pubmed-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pubmed_client_py-0.3.1-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pubmed_client_py-0.3.1-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 a79a11ece5aa6a7e98f7b4bfc8470068dc2be965ad602b9e8f16125acc55ced9
MD5 3b925c9388c1ff29e845d0086caa2ce2
BLAKE2b-256 2728035de1439efa7a125b6a8c24f9f09981a110ca2c0830463f30fafe7efcb3

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.1-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: release.yml on illumination-k/pubmed-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pubmed_client_py-0.3.1-cp312-cp312-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for pubmed_client_py-0.3.1-cp312-cp312-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 3582688c8b4ff9abb2916de53e3ca5e3e26c8fa550e38ed294ca06dbc9ee6af0
MD5 b930b317bd3c9ce3744819c87c6774b6
BLAKE2b-256 4a97d954c557f97dfeda37b6f583dbcd73d41e77fe1254ad64430f70d1eb798e

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.1-cp312-cp312-macosx_10_12_x86_64.whl:

Publisher: release.yml on illumination-k/pubmed-client

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.4.0

11 files

This release

0.3.1 This release

11 files

0.3.0

11 files

0.2.0

11 files

0.0.2

11 files

0.0.1

9 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page