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 Jul 13, 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 Jul 13, 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.0.tar.gz (836.7 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.0-cp314-cp314-win_amd64.whl (3.7 MB view details)

Uploaded CPython 3.14Windows x86-64

pubmed_client_py-0.3.0-cp314-cp314-macosx_11_0_arm64.whl (3.9 MB view details)

Uploaded CPython 3.14macOS 11.0+ ARM64

pubmed_client_py-0.3.0-cp314-cp314-macosx_10_12_x86_64.whl (4.0 MB view details)

Uploaded CPython 3.14macOS 10.12+ x86-64

pubmed_client_py-0.3.0-cp313-cp313-win_amd64.whl (3.7 MB view details)

Uploaded CPython 3.13Windows x86-64

pubmed_client_py-0.3.0-cp313-cp313-macosx_11_0_arm64.whl (3.9 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

pubmed_client_py-0.3.0-cp313-cp313-macosx_10_12_x86_64.whl (4.0 MB view details)

Uploaded CPython 3.13macOS 10.12+ x86-64

pubmed_client_py-0.3.0-cp312-cp312-win_amd64.whl (3.7 MB view details)

Uploaded CPython 3.12Windows x86-64

pubmed_client_py-0.3.0-cp312-cp312-manylinux_2_38_x86_64.whl (6.5 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.38+ x86-64

pubmed_client_py-0.3.0-cp312-cp312-macosx_11_0_arm64.whl (3.9 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

pubmed_client_py-0.3.0-cp312-cp312-macosx_10_12_x86_64.whl (4.0 MB view details)

Uploaded CPython 3.12macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: pubmed_client_py-0.3.0.tar.gz
  • Upload date:
  • Size: 836.7 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.0.tar.gz
Algorithm Hash digest
SHA256 65ba5c713fe28e1833f89cd079a23690aaf832e8972f9decb0d7642b5b6816a5
MD5 bd998214f038a95a36786f9d1cec126e
BLAKE2b-256 38c1c3920d1d6995190024b54b76e8ca13cfbd4c1077fdf40a46794abd05c5c9

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.0.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.0-cp314-cp314-win_amd64.whl.

File metadata

File hashes

Hashes for pubmed_client_py-0.3.0-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 358385ecdd206461ad2c20f918d9dd68e38871ec888ae4143bcf46ff8c3da0fe
MD5 4f997e5d983d17ebd1089ef9b297b05c
BLAKE2b-256 b03afd3d6e36a91d8d4e0297c239bc95555c5c1bada493198bd60e6536631423

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.0-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.0-cp314-cp314-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pubmed_client_py-0.3.0-cp314-cp314-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 0c38acff351181f616baad66f63e1e5af82f7e3c132c761806368f30bccbf460
MD5 c794414b37b7be8ff3112a56d5e99bbd
BLAKE2b-256 881cf4c33d92155c99f21645d905ed1964d6d87243178feceaf13bdf5252800e

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.0-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.0-cp314-cp314-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for pubmed_client_py-0.3.0-cp314-cp314-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 340dc914ee7d1d6eeaf433ed77f4bd0e322b3964e39841c59f9346786dc37fac
MD5 848907a323f843dd1b6d87513e15048c
BLAKE2b-256 f6e9963aa741110079ea74349a64304f7d56cc685653f313da72699d7eae02f1

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.0-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.0-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for pubmed_client_py-0.3.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 b58513cd0ad7e948dcdfcee7e7fe664fc23e0e5f45845211aa5924f92a162a15
MD5 0c1f81ef1fb6e24263a74586d26697f5
BLAKE2b-256 31fc681d940eb52cf57420fc58f8d615b8aad0f1532b175802934beec2525f6c

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.0-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.0-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pubmed_client_py-0.3.0-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 05be25edabb2b5137ac82b113d69e3899f986d9940614490ea8ee151c625aafa
MD5 5fb3e83abb1fe473708b01ee28c60fb7
BLAKE2b-256 f585092cf2d677048224fcc4580e38d99fcd72f6604f41ba8f0c8c2e339c1eb7

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.0-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.0-cp313-cp313-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for pubmed_client_py-0.3.0-cp313-cp313-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 17f7bc293cef19e4aca028379492ff0f5764020589fa6222864ce44f002c3d31
MD5 bdfc5f60a399da298db1a0b01d343f67
BLAKE2b-256 ef1d435f24b70a7b914dbd634cc3528b980859a52f2012833e3b053bd98ed760

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.0-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.0-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for pubmed_client_py-0.3.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 7134b92cd3dac5a89930db7edabc962f08448e965bf67483dee61872508509cb
MD5 548e2221af192ba8596a878e14bc6610
BLAKE2b-256 f6a29104c3c54cdd18d2f7a90b1edb35b2e67eedd6132b3b954f7d8eed3aa2e1

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.0-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.0-cp312-cp312-manylinux_2_38_x86_64.whl.

File metadata

File hashes

Hashes for pubmed_client_py-0.3.0-cp312-cp312-manylinux_2_38_x86_64.whl
Algorithm Hash digest
SHA256 a87e7e2f3d9a1cbeaf1a34946a0769e517bd7b3e0e24fcd70f67040a7b8df2e3
MD5 62ccd861d9a4b6b2927cbf40d8c9dddb
BLAKE2b-256 cd88a4c16e2928a3b9c9ac5258fb4c8a64535fc9fa5e6e4326b054d2531b5117

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.0-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.0-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for pubmed_client_py-0.3.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 fb3856abd229e111a7697c72b2ec2af651fda7ffad80213653eff1d040596215
MD5 cd3b247da5b358bb802ae3e75a0be0ec
BLAKE2b-256 787cab6f63d1c5d04302f650a04f1435d6d60e99733ecaf042562674562b6813

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.0-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.0-cp312-cp312-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for pubmed_client_py-0.3.0-cp312-cp312-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 6b985841a29af0ffb8ad05d866582e8f443562b99e82a03766f8981f18a2eb89
MD5 2da8847cc94c53afad6e11535ae540d6
BLAKE2b-256 40793d499d5f54655ea71a4f160adbd4e1abad2b160a5afe00c33eaa536f2a98

See more details on using hashes here.

Provenance

The following attestation bundles were made for pubmed_client_py-0.3.0-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

0.3.1

11 files

This release

0.3.0 This release

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