Metadata-Version: 2.4
Name: grateful_py
Version: 0.2.1
Summary: Automatic citation generation for Python projects, inspired by the R package grateful.
Author-email: J Kyle Armstrong <j.kyle.armstrong@gmail.com>
Project-URL: Homepage, https://github.com/jkylearmstrong/grateful_py
Project-URL: Repository, https://github.com/jkylearmstrong/grateful_py
Project-URL: Issues, https://github.com/jkylearmstrong/grateful_py/issues
Keywords: citation,bibliography,bibtex,reproducibility,packages
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jinja2>=3
Requires-Dist: tomli>=2; python_version < "3.11"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

# grateful-py README


- [grateful-py 🐍](#grateful-py-snake)
  - [Features](#features)
  - [Installation](#installation)
  - [Usage](#usage)
    - [CLI](#cli)
    - [Python API](#python-api)
  - [Development](#development)
  - [Acknowledgments](#acknowledgments)

# grateful-py 🐍

Automatic citation generation for Python projects.

`grateful-py` is a Python port of the R package
[**grateful**](https://pakillo.github.io/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](https://pandoc.org) — 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, CSV, 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](https://github.com/citation-style-language/styles) (APA, PeerJ,
  …) by name
- 🚀 CLI (`grateful-py`) + Python API
- ⚙️ Configurable `omit` (use `omit="none"` to include all packages),
  `skip_missing`, and dependency-group scanning

## Installation

``` bash
pip install grateful_py
```

Word/PDF/LaTeX report generation additionally requires
[Pandoc](https://pandoc.org/installing.html) to be installed and on
`PATH`. All other formats (`bib`, `csv`, `json`, `txt`, `md`, `html`)
work without it.

## Usage

### CLI

``` bash
# 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:

| R grateful            | grateful-py           |
|-----------------------|-----------------------|
| `scan_packages()`     | `scan_packages()`     |
| `get_pkgs_info()`     | `get_pkgs_info()`     |
| `get_citations()`     | `get_citations()`     |
| `cite_packages()`     | `cite_packages()`     |
| `get_csl()`           | `get_csl()`           |
| `nocite_references()` | `nocite_references()` |

``` python
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/csv/json/txt/md/html, via Pandoc for
# docx/pdf/tex-fragment/tex-document/Rmd
g.cite_packages(".", output="file", out_format="csv", 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

``` bash
pip install -e ".[test]"
pytest
```

## Acknowledgments

This project is inspired by the R package
[**grateful**](https://pakillo.github.io/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.
