grateful-py README

• grateful-py 🐍
  • Features
  • Installation
  • Usage
    • CLI
    • Python API
  • Development
  • Acknowledgments

grateful-py 🐍

Automatic citation generation for Python projects.

grateful-py is a Python port of the R package grateful: it scans a project (or the current session, or pyproject.toml), resolves the packages actually used, pulls their metadata, and generates formatted citations (BibTeX, Markdown, JSON, plain text, HTML, and — via Pandoc — Word/PDF/LaTeX).

Features

• 🔍 Detect imported packages via AST scanning of a project, the current session (sys.modules), a single file, or pyproject.toml dependency groups
• 📦 Resolve import names to installed distributions (handling name mismatches like yaml → PyYAML, cv2 → opencv-python, sklearn → scikit-learn)
• 🌳 Optionally expand to the full transitive dependency closure
• 🧠 Extract metadata via importlib.metadata, with unique BibTeX citekeys
• 📝 Generate citations as a BibTeX file, Markdown, JSON, a plain-text paragraph, an HTML report, or — with Pandoc installed — DOCX/PDF/LaTeX with real CSL-styled bibliographies
• 🎨 Fetch any CSL citation style (APA, PeerJ, …) by name
• 🚀 CLI (grateful-py) + Python API
• ⚙️ Configurable omit, skip_missing, and dependency-group scanning

Installation

pip install grateful_py

Word/PDF/LaTeX report generation additionally requires Pandoc to be installed and on PATH. All other formats (bib, json, txt, md, html) work without it.

Usage

CLI

# List packages detected in the current project
grateful-py scan .

# Generate a Markdown citation report (grateful-report.md + grateful-refs.bib)
grateful-py cite . --out-dir .

# Generate a Word document, styled with a specific CSL citation style
# (requires Pandoc)
grateful-py cite . --out-format docx --citation-style apa --out-dir .

# Just the inline citation paragraph
grateful-py cite . --output paragraph

# Only packages declared in pyproject.toml
grateful-py scan . --pkgs pyproject --groups dependencies

# Download a CSL style file
grateful-py csl peerj --out-dir .

Run grateful-py cite --help / grateful-py scan --help for the full list of options (--omit, --include-dependencies, --skip-missing, --pkgs, …).

Python API

grateful-py’s API mirrors R grateful’s function names:

import grateful_py as g

# Detect packages used in a project
packages = g.scan_packages(".")

# Same, but scan the current session (sys.modules) instead of files on disk
packages = g.scan_packages(pkgs="session")

# Or read dependencies straight from pyproject.toml
packages = g.scan_packages(".", pkgs="pyproject", groups=["dependencies"])

# Get full citation metadata + write a BibTeX file
citations = g.get_pkgs_info(".", out_dir=".")

# Just an inline citation sentence, for embedding in a paper/report
print(g.cite_packages(".", output="paragraph"))
# "We used Python version 3.12.2 [@python] and the following Python
#  packages: numpy v1.26.4 [@numpy], pandas v2.2.1 [@pandas]."

# A table of package/version/citation, e.g. for a Quarto/Jupyter document
g.cite_packages(".", output="table")

# A full report file — natively for bib/json/txt/md/html, via Pandoc for
# docx/pdf/tex-fragment/tex-document/Rmd
g.cite_packages(".", output="file", out_format="html", out_dir=".")

# Fetch a CSL citation style and use it when rendering
g.get_csl("apa", out_dir=".")
g.cite_packages(".", out_format="docx", citation_style="apa", out_dir=".")

# Force specific citekeys into a references list without an inline mention
print(g.nocite_references(["numpy", "pandas"]))

Development

pip install -e ".[test]"
pytest

Acknowledgments

This project is inspired by the R package grateful by Francisco Rodríguez-Sánchez (Pakillo). grateful-py aims to bring the same spirit of reproducibility, transparency, and scholarly respect for software authors to the Python ecosystem.