| Name | ppget JSON |
| Version |
0.1.3
JSON |
| download |
| home_page | None |
| Summary | A simple CLI tool to download PubMed articles without the complexity of EDirect |
| upload_time | 2025-10-19 01:33:57 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | MIT |
| keywords |
cli
literature
medicine
papers
pubmed
research
search
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ppget
**A simple CLI tool to easily download PubMed articles**
[日本語版README](README_ja.md) | [English](README.md)
`ppget` is a command-line tool for searching and downloading literature data from PubMed. Unlike [EDirect](https://www.ncbi.nlm.nih.gov/books/NBK179288/), which requires complex setup, **you can start using it immediately**.
## ✨ Features
- 🚀 **No installation required** - Run instantly with `uvx`
- 📝 **CSV/JSON support** - Easy to use in spreadsheets or programs
- 🔍 **Flexible search** - Full support for PubMed search syntax (AND, OR, MeSH, etc.)
- 📊 **Automatic metadata** - Automatically records search queries and timestamps
- 🎯 **Simple API** - Clear and intuitive options
## 🚀 Quick Start
### Run without installation (Recommended)
If you have [uv](https://github.com/astral-sh/uv) installed, **you can run it instantly without installation**:
```bash
# Basic usage
uvx ppget "machine learning AND medicine"
# Specify number of results
uvx ppget "COVID-19 vaccine" -l 50
# Save as JSON
uvx ppget "cancer immunotherapy" -f json
```
### Install and use
For frequent use, you can install it:
```bash
# Install with pip
pip install ppget
# Install with uv
uv tool install ppget
# Run
ppget "your search query"
```
## 📖 Usage
### Basic usage
```bash
# Simple search (CSV format by default, up to 100 results)
ppget "diabetes treatment"
# Example output:
# Searching PubMed...
# Query: 'diabetes treatment'
# Max results: 100
# ✓ Found 100 articles
# ✓ Saved 100 articles to pubmed_20251018_143022.csv
# ✓ Metadata saved to pubmed_20251018_143022.meta.txt
```
### Options
```bash
ppget [query] [options]
Required:
query Search query
Options:
-l, --limit Maximum number of results (default: 100)
-o, --output Output file or directory
-f, --format Output format: csv or json (default: csv)
-e, --email Email address (for API rate limit relaxation)
-q, --quiet Suppress progress messages (errors only)
-v, --version Show version and exit
-h, --help Show help message
```
### Advanced usage
#### 1. Change number of results
```bash
# Retrieve up to 200 results
ppget "machine learning healthcare" -l 200
```
#### 2. Specify output format
```bash
# Save as JSON
ppget "spine surgery" -f json
# Default is CSV (can be opened in Excel)
ppget "orthopedics" -f csv
```
#### 3. Specify filename
```bash
# Specify file path directly
ppget "cancer research" -o results/cancer_papers.csv
# Specify directory (filename is auto-generated)
ppget "neuroscience" -o ./data/
# Extension determines format
ppget "cardiology" -o heart_disease.json
```
#### 4. Specify email address (API rate limit relaxation)
NCBI's API has relaxed limits when you provide an email address:
```bash
ppget "genomics" -e your.email@example.com -l 500
```
#### 5. Use PubMed search syntax
```bash
# AND search
ppget "machine learning AND radiology"
# OR search
ppget "COVID-19 OR SARS-CoV-2"
# MeSH term search
ppget "Diabetes Mellitus[MeSH] AND Drug Therapy[MeSH]"
# Filter by year
ppget "cancer immunotherapy AND 2024[PDAT]"
# Search by author
ppget "Smith J[Author]"
# Complex search
ppget "(machine learning OR deep learning) AND (radiology OR imaging) AND 2023:2024[PDAT]"
```
## 📁 Output Format
### CSV format (default)
Easy to open in spreadsheets. A metadata file (`.meta.txt`) is also generated.
```
pubmed_20251018_143022.csv # Article data
pubmed_20251018_143022.meta.txt # Search metadata
```
**CSV columns:**
- `pubmed_id` - PubMed ID
- `title` - Title
- `abstract` - Abstract
- `journal` - Journal name
- `publication_date` - Publication date
- `doi` - DOI
- `authors` - Author list (semicolon-separated)
- `keywords` - Keywords (semicolon-separated)
### JSON format
Easy to process programmatically.
```json
[
{
"pubmed_id": "12345678",
"title": "...",
"abstract": "...",
...
}
]
```
**Metadata file (.meta.txt):**
```
Query: machine learning
Search Date: 2025-10-18 14:30:22
Retrieved Results: 100
Data File: pubmed_20251018_143022.json
```
## 🆚 Comparison with EDirect
| Feature | ppget | EDirect |
|---------|------|---------|
| Installation | Not required (`uvx` instant run) | Complex setup required |
| Ease of use | Single command | Multiple command combinations |
| Output format | CSV/JSON | XML/Text |
| Metadata | Automatic | Manual management |
| Learning curve | Low | High |
### EDirect example (complex)
```bash
# Search with EDirect (multiple steps required)
esearch -db pubmed -query "machine learning" | \
efetch -format abstract | \
xtract -pattern PubmedArticle -element MedlineCitation/PMID,ArticleTitle
```
### ppget example (simple)
```bash
# With ppget, just one command
ppget "machine learning"
```
## 💡 Use Cases
### Collecting research papers
```bash
# Collect latest papers on a specific topic
ppget "CRISPR gene editing" -l 100 -o crispr_papers.csv
# Run multiple searches at once
ppget "diabetes treatment 2024[PDAT]" -o diabetes_2024.csv
ppget "cancer immunotherapy 2024[PDAT]" -o cancer_2024.csv
```
### For data analysis
```bash
# Retrieve in JSON format and analyze with Python
ppget "artificial intelligence healthcare" -f json -l 500 -o ai_health.json
# Example Python code to read
import json
with open('ai_health.json') as f:
data = json.load(f)
# Analysis...
```
### Literature review
```bash
# Retrieve in CSV and manage in Excel
ppget "systematic review AND meta-analysis" -l 200 -o reviews.csv
# → Open in Excel and review titles and abstracts
```
## 🤝 Contributing
Bug reports and feature requests are welcome at [Issues](https://github.com/masaki39/ppget/issues).
## 📄 License
MIT License - See [LICENSE](LICENSE) for details.
## 🙏 Acknowledgments
This tool uses [pymed-paperscraper](https://github.com/jannisborn/pymed).
---
**Start searching PubMed easily and quickly!**
```bash
uvx ppget "your research topic"
```
Raw data
{
"_id": null,
"home_page": null,
"name": "ppget",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "cli, literature, medicine, papers, pubmed, research, search",
"author": null,
"author_email": "masaki39 <masa21gifus@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/27/23/6325f506582fe43d372678df6ae67f9a0f276c210b7e46b21f7ed07f4aa9/ppget-0.1.3.tar.gz",
"platform": null,
"description": "# ppget\n\n**A simple CLI tool to easily download PubMed articles**\n\n[\u65e5\u672c\u8a9e\u7248README](README_ja.md) | [English](README.md)\n\n`ppget` is a command-line tool for searching and downloading literature data from PubMed. Unlike [EDirect](https://www.ncbi.nlm.nih.gov/books/NBK179288/), which requires complex setup, **you can start using it immediately**.\n\n## \u2728 Features\n\n- \ud83d\ude80 **No installation required** - Run instantly with `uvx`\n- \ud83d\udcdd **CSV/JSON support** - Easy to use in spreadsheets or programs\n- \ud83d\udd0d **Flexible search** - Full support for PubMed search syntax (AND, OR, MeSH, etc.)\n- \ud83d\udcca **Automatic metadata** - Automatically records search queries and timestamps\n- \ud83c\udfaf **Simple API** - Clear and intuitive options\n\n## \ud83d\ude80 Quick Start\n\n### Run without installation (Recommended)\n\nIf you have [uv](https://github.com/astral-sh/uv) installed, **you can run it instantly without installation**:\n\n```bash\n# Basic usage\nuvx ppget \"machine learning AND medicine\"\n\n# Specify number of results\nuvx ppget \"COVID-19 vaccine\" -l 50\n\n# Save as JSON\nuvx ppget \"cancer immunotherapy\" -f json\n```\n\n### Install and use\n\nFor frequent use, you can install it:\n\n```bash\n# Install with pip\npip install ppget\n\n# Install with uv\nuv tool install ppget\n\n# Run\nppget \"your search query\"\n```\n\n## \ud83d\udcd6 Usage\n\n### Basic usage\n\n```bash\n# Simple search (CSV format by default, up to 100 results)\nppget \"diabetes treatment\"\n\n# Example output:\n# Searching PubMed...\n# Query: 'diabetes treatment'\n# Max results: 100\n# \u2713 Found 100 articles\n# \u2713 Saved 100 articles to pubmed_20251018_143022.csv\n# \u2713 Metadata saved to pubmed_20251018_143022.meta.txt\n```\n\n### Options\n\n```bash\nppget [query] [options]\n\nRequired:\n query Search query\n\nOptions:\n -l, --limit Maximum number of results (default: 100)\n -o, --output Output file or directory\n -f, --format Output format: csv or json (default: csv)\n -e, --email Email address (for API rate limit relaxation)\n -q, --quiet Suppress progress messages (errors only)\n -v, --version Show version and exit\n -h, --help Show help message\n```\n\n### Advanced usage\n\n#### 1. Change number of results\n\n```bash\n# Retrieve up to 200 results\nppget \"machine learning healthcare\" -l 200\n```\n\n#### 2. Specify output format\n\n```bash\n# Save as JSON\nppget \"spine surgery\" -f json\n\n# Default is CSV (can be opened in Excel)\nppget \"orthopedics\" -f csv\n```\n\n#### 3. Specify filename\n\n```bash\n# Specify file path directly\nppget \"cancer research\" -o results/cancer_papers.csv\n\n# Specify directory (filename is auto-generated)\nppget \"neuroscience\" -o ./data/\n\n# Extension determines format\nppget \"cardiology\" -o heart_disease.json\n```\n\n#### 4. Specify email address (API rate limit relaxation)\n\nNCBI's API has relaxed limits when you provide an email address:\n\n```bash\nppget \"genomics\" -e your.email@example.com -l 500\n```\n\n#### 5. Use PubMed search syntax\n\n```bash\n# AND search\nppget \"machine learning AND radiology\"\n\n# OR search\nppget \"COVID-19 OR SARS-CoV-2\"\n\n# MeSH term search\nppget \"Diabetes Mellitus[MeSH] AND Drug Therapy[MeSH]\"\n\n# Filter by year\nppget \"cancer immunotherapy AND 2024[PDAT]\"\n\n# Search by author\nppget \"Smith J[Author]\"\n\n# Complex search\nppget \"(machine learning OR deep learning) AND (radiology OR imaging) AND 2023:2024[PDAT]\"\n```\n\n## \ud83d\udcc1 Output Format\n\n### CSV format (default)\n\nEasy to open in spreadsheets. A metadata file (`.meta.txt`) is also generated.\n\n```\npubmed_20251018_143022.csv # Article data\npubmed_20251018_143022.meta.txt # Search metadata\n```\n\n**CSV columns:**\n- `pubmed_id` - PubMed ID\n- `title` - Title\n- `abstract` - Abstract\n- `journal` - Journal name\n- `publication_date` - Publication date\n- `doi` - DOI\n- `authors` - Author list (semicolon-separated)\n- `keywords` - Keywords (semicolon-separated)\n\n### JSON format\n\nEasy to process programmatically.\n\n```json\n[\n {\n \"pubmed_id\": \"12345678\",\n \"title\": \"...\",\n \"abstract\": \"...\",\n ...\n }\n]\n```\n\n**Metadata file (.meta.txt):**\n```\nQuery: machine learning\nSearch Date: 2025-10-18 14:30:22\nRetrieved Results: 100\nData File: pubmed_20251018_143022.json\n```\n\n## \ud83c\udd9a Comparison with EDirect\n\n| Feature | ppget | EDirect |\n|---------|------|---------|\n| Installation | Not required (`uvx` instant run) | Complex setup required |\n| Ease of use | Single command | Multiple command combinations |\n| Output format | CSV/JSON | XML/Text |\n| Metadata | Automatic | Manual management |\n| Learning curve | Low | High |\n\n### EDirect example (complex)\n\n```bash\n# Search with EDirect (multiple steps required)\nesearch -db pubmed -query \"machine learning\" | \\\nefetch -format abstract | \\\nxtract -pattern PubmedArticle -element MedlineCitation/PMID,ArticleTitle\n```\n\n### ppget example (simple)\n\n```bash\n# With ppget, just one command\nppget \"machine learning\"\n```\n\n## \ud83d\udca1 Use Cases\n\n### Collecting research papers\n\n```bash\n# Collect latest papers on a specific topic\nppget \"CRISPR gene editing\" -l 100 -o crispr_papers.csv\n\n# Run multiple searches at once\nppget \"diabetes treatment 2024[PDAT]\" -o diabetes_2024.csv\nppget \"cancer immunotherapy 2024[PDAT]\" -o cancer_2024.csv\n```\n\n### For data analysis\n\n```bash\n# Retrieve in JSON format and analyze with Python\nppget \"artificial intelligence healthcare\" -f json -l 500 -o ai_health.json\n\n# Example Python code to read\nimport json\nwith open('ai_health.json') as f:\n data = json.load(f)\n # Analysis...\n```\n\n### Literature review\n\n```bash\n# Retrieve in CSV and manage in Excel\nppget \"systematic review AND meta-analysis\" -l 200 -o reviews.csv\n\n# \u2192 Open in Excel and review titles and abstracts\n```\n\n## \ud83e\udd1d Contributing\n\nBug reports and feature requests are welcome at [Issues](https://github.com/masaki39/ppget/issues).\n\n## \ud83d\udcc4 License\n\nMIT License - See [LICENSE](LICENSE) for details.\n\n## \ud83d\ude4f Acknowledgments\n\nThis tool uses [pymed-paperscraper](https://github.com/jannisborn/pymed).\n\n---\n\n**Start searching PubMed easily and quickly!**\n\n```bash\nuvx ppget \"your research topic\"\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple CLI tool to download PubMed articles without the complexity of EDirect",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/masaki39/ppget",
"Issues": "https://github.com/masaki39/ppget/issues",
"Repository": "https://github.com/masaki39/ppget"
},
"split_keywords": [
"cli",
" literature",
" medicine",
" papers",
" pubmed",
" research",
" search"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a3f948254a4ffe86a55a4c1d4be761ca74804043e694b0ef27db0b43ec514a2b",
"md5": "2b033235e74579842e7b7a582e23f063",
"sha256": "477070cc345072e23082f07562e614ba5fd211fe514f3a5803e19eeed2ba3dc3"
},
"downloads": -1,
"filename": "ppget-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2b033235e74579842e7b7a582e23f063",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 10963,
"upload_time": "2025-10-19T01:33:56",
"upload_time_iso_8601": "2025-10-19T01:33:56.633728Z",
"url": "https://files.pythonhosted.org/packages/a3/f9/48254a4ffe86a55a4c1d4be761ca74804043e694b0ef27db0b43ec514a2b/ppget-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "27236325f506582fe43d372678df6ae67f9a0f276c210b7e46b21f7ed07f4aa9",
"md5": "04dcae67308b6520e0708b90ef762e97",
"sha256": "347c6294fd2453b3d3bd73ad3fcd650292b6827a34c98a96f0a47fb9a40d2067"
},
"downloads": -1,
"filename": "ppget-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "04dcae67308b6520e0708b90ef762e97",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 22776,
"upload_time": "2025-10-19T01:33:57",
"upload_time_iso_8601": "2025-10-19T01:33:57.770442Z",
"url": "https://files.pythonhosted.org/packages/27/23/6325f506582fe43d372678df6ae67f9a0f276c210b7e46b21f7ed07f4aa9/ppget-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-19 01:33:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "masaki39",
"github_project": "ppget",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ppget"
}
