Metadata-Version: 2.5
Name: pip-weigh
Version: 0.2.0
Summary: Know the cost of your imports - Audit your dependencies before you commit
Author: pip-weigh contributors
License: MIT
License-File: LICENSE
Keywords: analysis,dependencies,disk,pip,size,uv
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Requires-Dist: rich>=13.0.0
Requires-Dist: tomli>=2.0.1; python_version < '3.11'
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# pip-weigh

[![Tests](https://github.com/muddassir-lateef/pip-weigh/actions/workflows/tests.yml/badge.svg)](https://github.com/muddassir-lateef/pip-weigh/actions/workflows/tests.yml)
[![PyPI version](https://badge.fury.io/py/pip-weigh.svg)](https://badge.fury.io/py/pip-weigh)
[![Python versions](https://img.shields.io/pypi/pyversions/pip-weigh.svg)](https://pypi.org/project/pip-weigh/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> *"Know the cost of your imports."*

A CLI tool that measures the true disk size of Python packages, including all their dependencies. Perfect for optimizing Docker images, Lambda functions, and understanding your dependency footprint.

## Features

- 🔍 **Accurate Size Analysis** - Measures the real disk footprint of packages and all dependencies
- 📁 **Local Project Analysis** - Weigh everything your own `pyproject.toml` pulls in
- 🌐 **Cross-Platform Analysis** - Check Linux package sizes from macOS/Windows (great for Docker planning)
- 🐍 **Python Version Support** - Analyze sizes across different Python versions
- 📊 **Beautiful Output** - Rich terminal output with dependency trees
- 🔄 **CI/CD Ready** - JSON output and budget checks for pipelines
- ⚡ **Fast** - Leverages uv's speed and caching

## Installation

```bash
pip install pip-weigh
```

Or with uv:
```bash
uv pip install pip-weigh
```

## Requirements

- Python 3.9+
- [uv](https://github.com/astral-sh/uv) must be installed and available in PATH

## Usage

### Basic Usage

```bash
pip-weigh pandas
```

Output:
```
📦 pandas (2.1.4)
├── Total Size: 138 MB
├── Self Size: 45 MB
├── Platform: linux
├── Python: 3.12
└── Dependencies (3):
    ├── numpy (1.26.2): 85 MB
    ├── pytz (2023.3): 5 MB
    └── python-dateutil (2.8.2): 3 MB
```

### Analyzing a Local Project

Point pip-weigh at your own project to weigh everything its `pyproject.toml` pulls in:

```bash
pip-weigh .                       # current directory
pip-weigh ./services/api          # any directory with a pyproject.toml
pip-weigh path/to/pyproject.toml  # the file itself
pip-weigh requirements.txt        # a requirements file
```

If the project has a `uv.lock`, pip-weigh measures the **locked** versions, so the
number matches what you will actually ship. Pass `--no-lock` to re-resolve the
declared specifiers instead.

Optional extras and [PEP 735](https://peps.python.org/pep-0735/) dependency
groups are excluded by default — dev tooling shouldn't count against your image
budget — and can be opted into:

```bash
pip-weigh . --extra api --extra worker
pip-weigh . --group test
pip-weigh . --dev
```

Your project is never modified: no `.venv` is created in it, no lockfile is
written, and the project's own code is not installed. Only its dependency
closure is measured.

This makes a neat CI gate:

```bash
pip-weigh . --platform linux --budget 250MB
```

> **Note:** a bare name is always treated as a PyPI package. Write `./rich` (not
> `rich`) if you mean a local directory of that name.

### Cross-Platform Analysis

Check what the size would be on Linux (great for Docker):

```bash
pip-weigh torch --platform linux
```

Accepts `linux`, `macos`, `windows`, or a full target triple such as
`x86_64-manylinux_2_28` or `aarch64-apple-darwin`.

### Multiple Packages

```bash
pip-weigh pandas numpy requests
```

Each package is measured in isolation, and pip-weigh additionally installs them
*together* to report the deduplicated footprint — shared dependencies are
counted once, so the combined total is smaller than the sum of the rows. Skip
that extra pass with `--no-combined`.

### Seeing Every Dependency

The tree lists the 15 largest dependencies by default. To see them all:

```bash
pip-weigh pandas --limit 0    # no limit
pip-weigh pandas --limit 40   # a specific cap
pip-weigh pandas -v           # verbose implies no limit
```

`--json` always includes every dependency regardless of `--limit`.

### JSON Output (for CI/CD)

```bash
pip-weigh pandas --json
```

### Budget Check

Fail if a package or project exceeds a size limit:

```bash
pip-weigh pandas --budget 100MB
# Exit code 1 if exceeded
```

### Specify Python Version

```bash
pip-weigh pandas --python 3.12
```

## CLI Options

| Option | Short | Description |
|--------|-------|-------------|
| `--platform` | `-p` | Target platform (linux, macos, windows, or a target triple) |
| `--python` | | Python version to analyze (e.g., 3.11) |
| `--json` | `-j` | Output as JSON |
| `--budget` | `-b` | Maximum allowed size (e.g., 100MB, 1GB) |
| `--limit` | `-l` | Max dependencies to list (default 15; `0` for all) |
| `--no-deps` | | Show only the package itself, not dependencies |
| `--extra` | | Project mode: include an optional-dependency extra (repeatable) |
| `--group` | | Project mode: include a PEP 735 dependency group (repeatable) |
| `--dev` | | Project mode: include the `dev` dependency group |
| `--no-lock` | | Project mode: re-resolve instead of using `uv.lock` |
| `--no-combined` | | Skip the deduplicated total for multiple packages |
| `--verbose` | `-v` | Show detailed output, including every dependency |
| `--check` | | Check that uv is installed |
| `--version` | | Show version |
| `--help` | `-h` | Show help message |

## How It Works

1. Creates a temporary isolated environment using uv
2. Installs the target package(s) with all dependencies, honoring `--python-platform` so cross-platform estimates use the right wheels
3. Reads the installed `.dist-info` directories to get the exact resolved set
4. Scans `.dist-info/RECORD` files for accurate file-to-package mapping
5. Calculates logical sizes (important for Docker/Lambda accuracy)
6. Presents results with a beautiful dependency tree

## Why Logical Size Matters

`uv` uses hardlinks from a global cache, so disk usage tools might show misleading numbers. `pip-weigh` always reports the **logical size** - the actual bytes your package would consume in a Docker image or cloud function.

## License

MIT
