Metadata-Version: 2.4
Name: mgz-pkmn
Version: 1.0.1
Summary: CLI and web app to look up Pokemon cards across open data sources, fetch images and prices, and emit an .xlsx, PDF binder, set-completion checklist, and JSON report for card-show prep.
Project-URL: Homepage, https://mgz-pkmn.com
Project-URL: Repository, https://github.com/mgzwarrior/mgz-pkmn
Project-URL: Issues, https://github.com/mgzwarrior/mgz-pkmn/issues
Project-URL: Documentation, https://github.com/mgzwarrior/mgz-pkmn/tree/main/docs
Author-email: Matt Grant <mattgrant33@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: card-collection,cli,pokemon,pricing,spreadsheet,tcg,trading-cards
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: openpyxl>=3.1
Requires-Dist: pillow>=10.0
Requires-Dist: reportlab>=4.5.1
Requires-Dist: requests>=2.34.2
Provides-Extra: api
Requires-Dist: fastapi>=0.136.1; extra == 'api'
Requires-Dist: uvicorn[standard]>=0.47.0; extra == 'api'
Description-Content-Type: text/markdown

<h1>
  <img src="assets/logo.svg" alt="mgz-pkmn" height="64">
</h1>

[![CI](https://github.com/mgzwarrior/mgz-pkmn/actions/workflows/ci.yml/badge.svg)](https://github.com/mgzwarrior/mgz-pkmn/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)

🌐 **Project site:** <https://mgz-pkmn.com> · 🚀 **Live demo:** <https://mgz-pkmn.onrender.com>

A toolkit for prepping Pokemon card binders for a card show: take a list
of cards, look each one up across **three open data sources**, download
images, and write an `.xlsx` with embedded thumbnails, current market
price, and 80 / 85 / 90 / 95 % negotiation comps. Optional PDF binder,
condensed binder, set-completion checklist, and JSON report alongside.

Two ways to drive it:

- **CLI** — `./pkmn lookup cards.txt` produces xlsx + (optional) PDF +
  JSON; `./pkmn set-cards` emits printable set ID cutouts.
- **Web UI** — FastAPI backend in [api/](api/) and a React + Vite
  frontend in [web/](web/) put the same pipeline behind a live
  in-browser interface with streaming results and one-click export.

The tool tries sources in this order:

1. **[pokemontcg.io]** — primary. Best coverage of English /
   international English releases, with TCGPlayer (USD) + Cardmarket
   (EUR) prices.
2. **[TCGdex]** — multilingual fallback (`en`, `ja`, `ko`, `zh-tw`,
   `zh-cn`, `de`, `fr`, `es`, `it`, `pt`, …). Has Cardmarket prices
   for many cards.
3. **[PriceCharting]** — opt-in via an explicit URL on the line. Ideal
   for region-exclusive products neither aggregator indexes (Chinese
   Gem Pack, etc.). Returns USD loose / new / graded prices.

[pokemontcg.io]: https://pokemontcg.io
[TCGdex]: https://tcgdex.dev
[PriceCharting]: https://www.pricecharting.com

## Install

Requires Python 3.11+ and [`uv`](https://docs.astral.sh/uv/).

```bash
brew install uv                                   # macOS
curl -LsSf https://astral.sh/uv/install.sh | sh   # any platform

make install-cli          # CLI only — fastest
# or
make install              # CLI + API + web + pre-commit hook
```

Run `make help` for the full target list.

## Quickstart

```bash
./pkmn lookup input/ --no-images \
  -o output/cards.xlsx \
  --pdf output/binder.pdf \
  --condensed-pdf output/binder-condensed.pdf \
  --checklist output/checklist.pdf \
  --report-json output/summary.json

./pkmn set-cards -o output/set-cards.pdf   # printable set ID cutouts (no input needed)
```

The bundled [`input/`](input/) directory ships four small example lists
that exercise every input syntax and lookup mode the tool supports —
including [`example-url-overrides.txt`](input/example-url-overrides.txt),
which walks through the "paste a PriceCharting URL once and forget it"
workflow. The tracked files in [`output/`](output/) were generated by
exactly the command above. See the [CLI reference](docs/cli.md#worked-examples)
for the full breakdown.

### API key (optional but recommended)

The pokemontcg.io API works without a key (~1000 requests/day, 30/min)
but a free key raises that to 20k/day. Grab one at
<https://dev.pokemontcg.io>, then set it as an env var:

```bash
export POKEMONTCG_IO_API_KEY=your-key-here          # current shell
echo 'export POKEMONTCG_IO_API_KEY=your-key-here' >> ~/.zshrc   # persistent
```

Prefer the env var over `--api-key` — flags get saved to shell history.

## Web UI

```bash
make install         # one-time setup
make dev-api         # Terminal 1 — API on :8000
make dev-web         # Terminal 2 — Vite dev server on :5173
```

Open <http://localhost:5173>. The Vite dev server proxies `/api/*` to
the FastAPI server. Swagger UI lives at <http://localhost:8000/docs>.

Prefer not to install anything? The same UI is hosted at
<https://mgz-pkmn.onrender.com>.

For deeper docs (endpoint reference, troubleshooting, architecture),
see [api/README.md](api/README.md) and [web/README.md](web/README.md).

## License

Released under the [MIT License](LICENSE).

## Documentation

Reference docs live under [`docs/`](docs/) and are mirrored to the
[GitHub Wiki](https://github.com/mgzwarrior/mgz-pkmn/wiki) on every
push to `main`.

| Topic | Page |
|---|---|
| Every flag and `pkmn` invocation pattern | [CLI reference](docs/cli.md) |
| Single-card + bulk `top:N` / `All …` syntax | [Input format](docs/input-format.md) |
| pokemontcg.io / TCGdex / PriceCharting layering | [Sources & coverage](docs/sources.md) |
| Non-English / regional handling | [Languages](docs/languages.md) |
| Spreadsheet + JSON report shape | [Outputs](docs/outputs.md) |
| Standard 3×3 + condensed 6×4 layouts | [PDF binder](docs/binder-pdf.md) |
| Front-of-binder set checklist | [Checklist PDF](docs/checklist.md) |
| Disk cache + URL overrides | [Cache](docs/cache.md) |
| Render / Docker / production recipe | [Deployment](docs/deployment.md) |
| Marketing site (Astro + Tailwind, Cloudflare Pages) | [site/README.md](site/README.md) |
| Project layout, dev workflow, CI, release | [Contributing](docs/contributing.md) |

## Community

Questions, ideas, or want to share what you built? Open a thread in [GitHub Discussions](https://github.com/mgzwarrior/mgz-pkmn/discussions).
