Metadata-Version: 2.5
Name: peta
Version: 0.3.0
Summary: Human-friendly Python package metadata viewer
Project-URL: changelog, https://github.com/hasansezertasan/peta/blob/main/CHANGELOG.md
Project-URL: documentation, https://hasansezertasan.github.io/peta
Project-URL: homepage, https://github.com/hasansezertasan/peta
Project-URL: issues, https://github.com/hasansezertasan/peta/issues
Project-URL: releasenotes, https://github.com/hasansezertasan/peta/releases
Project-URL: source, https://github.com/hasansezertasan/peta.git
Author-email: Hasan Sezer Tasan <hasansezertasan@gmail.com>
Maintainer-email: Hasan Sezer Tasan <hasansezertasan@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,command-line,metadata,packaging,pypi,python,typer
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx
Requires-Dist: packaging>=24.2
Requires-Dist: rich
Requires-Dist: typer
Requires-Dist: typing-extensions>=4.6
Description-Content-Type: text/markdown

# peta

[![CI](https://github.com/hasansezertasan/peta/actions/workflows/ci.yml/badge.svg)](https://github.com/hasansezertasan/peta/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/codecov/c/github/hasansezertasan/peta)](https://codecov.io/gh/hasansezertasan/peta)
[![Documentation Status](https://img.shields.io/github/deployments/hasansezertasan/peta/github-pages?label=docs)](https://hasansezertasan.github.io/peta)
[![PyPI - Version](https://img.shields.io/pypi/v/peta.svg)](https://pypi.org/project/peta)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/peta.svg)](https://pypi.org/project/peta)
[![License - MIT](https://img.shields.io/github/license/hasansezertasan/peta.svg)](https://opensource.org/licenses/MIT)
[![GitHub Stars](https://img.shields.io/github/stars/hasansezertasan/peta?style=social)](https://github.com/hasansezertasan/peta/stargazers)
[![Latest Commit](https://img.shields.io/github/last-commit/hasansezertasan/peta)](https://github.com/hasansezertasan/peta)

[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
[![linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/hasansezertasan/peta/badge)](https://scorecard.dev/viewer/?uri=github.com/hasansezertasan/peta)
[![GitHub Tag](https://img.shields.io/github/tag/hasansezertasan/peta?include_prereleases=&sort=semver&color=black)](https://github.com/hasansezertasan/peta/releases/)

[![Downloads](https://pepy.tech/badge/peta)](https://pepy.tech/project/peta)
[![Downloads/Month](https://pepy.tech/badge/peta/month)](https://pepy.tech/project/peta)
[![Downloads/Week](https://pepy.tech/badge/peta/week)](https://pepy.tech/project/peta)

**Human-friendly Python package metadata viewer.** Think `cargo info` for Python.

`peta` shows detailed metadata for a Python package — from your local environment
or from PyPI — with clean, Rich-formatted terminal output.

## Features

- **Local + remote** — inspect installed packages or any package on PyPI
- **Rich output** — readable tables, panels, and trees
- **Dependency listing** — see a package's declared dependencies
- **File listing** — list files installed by a local package
- **Version listing** — browse published versions from PyPI
- **Release artifacts** — wheels, sdists, digests, compatibility, and provenance
- **Structured output** — Rich, plain text, versioned JSON, or Markdown

## Installation

`peta` is an end-user CLI tool; install it into an isolated environment:

```bash
# Run without installing
uvx peta requests

# Install as a tool
uv tool install peta
pipx install peta
```

On macOS/Linux via [Homebrew](https://github.com/hasansezertasan/homebrew-tap):

```bash
brew install hasansezertasan/tap/peta
```

On Windows via [Scoop](https://github.com/hasansezertasan/scoop-bucket):

```bash
scoop bucket add hasansezertasan https://github.com/hasansezertasan/scoop-bucket
scoop install peta
```

**Requires:** Python 3.11+ (3.11 through 3.14 are tested; see
[supported Python versions](https://hasansezertasan.github.io/peta/latest/installation.html#supported-python-versions))

## Usage

### Inspect another Python environment

`info`, `compare`, `deps`, `files`, and `origin` normally inspect the environment running
`peta`. Pass `--python PATH` to inspect an explicit interpreter, or repeat
`--path` to search explicit metadata directories:

```shell
peta info django --local --python .venv/bin/python
peta deps django --local --path .venv/lib/python3.14/site-packages
peta files django --python .venv/bin/python
peta origin django --python .venv/bin/python --verify
peta compare django flask --local --python .venv/bin/python
```

`--path` selects the metadata search directories. `--python` selects both the
interpreter's search path and its marker environment; when both are supplied,
the paths come from `--path` and markers come from `--python`. With only
`--path`, markers come from the running interpreter. Peta never guesses a
nearby `.venv`; human output and JSON identify the target and marker values.

```bash
peta requests                 # info (local first, falls back to PyPI)
peta info requests            # explicit info
peta info requests==2.31.0    # a specific version from PyPI
peta deps flask               # declared metadata tree
peta deps flask --why certifi # why is certifi pulled in?
peta files rich               # files installed locally
peta origin rich              # how it was installed, and do its files match?
peta versions httpx           # published versions on PyPI
peta artifacts cryptography   # what the latest release ships
peta artifacts numpy==2.3.0 --files --python 3.12
peta compare requests httpx   # side-by-side comparison plus semantic changes
peta compare django==5.2 django==6.0 --changes-only  # what an upgrade changes
peta requests --format json   # versioned machine-readable output
peta requests --json          # compatibility alias for --format json
```

### Flags

| Flag | Applies to | Meaning |
| ------ | ----------- | --------- |
| `--format <format>` | all | `rich`, `text`, `json`, or `markdown` (default `rich`) |
| `--json` | all | compatibility alias for `--format json` |
| `--local` / `-l` | info, compare, deps | force local lookup |
| `--remote` / `-r` | info, compare, deps | force PyPI lookup |
| `--limit` / `-n` | versions | max versions to show (default 20) |
| `--python <path>` | info, compare, deps, files, origin | interpreter whose search path and markers to inspect |
| `--path <dir>` | info, compare, deps, files, origin | metadata search directory; repeatable |
| `--python <x.y>` | artifacts | target Python **version** for compatibility (default: running) |
| `--files` | artifacts | list every distribution file |
| `--provenance` | artifacts | fetch PEP 740 provenance for publisher identity |
| `--why <target>` | deps | show why `<target>` is a dependency |
| `--depth <n>` | deps | max recursion depth (default 10) |
| `--extra <name>` | deps | activate optional extra dependencies on root; repeatable |
| `--python-version <ver>` | deps | target Python version (e.g. 3.12) |
| `--platform <plat>` | deps | target platform (e.g. win32, linux, darwin) |
| `--no-osv` | info, compare | skip OSV vulnerability lookup |
| `--no-stats` | info, compare | skip download/dependent count lookups |
| `--verify` | origin | hash every installed file against `RECORD` |
| `--changes-only` | compare | show only the grouped semantic changes |
| `--artifacts` | compare | also compare release dates, artifacts, and provenance |
| `--no-color` | (root) | disable colored output (also via `NO_COLOR`) |
| `--version` / `-V` | (root) | print version and exit |

## License

MIT
