# Python Package Tracker

A lightweight pip/setuptools package tracking utility similar to Reo.

## Features

- Zero runtime overhead for your application code
- Privacy-first metadata collection
- Non-blocking with strict timeout protection
- Retry logic with exponential backoff
- Configurable via environment variables and `pyproject.toml`

## Important pip/setuptools Note

Unlike npm `postinstall`, Python packaging does not guarantee dependency install hooks in all pip flows (especially wheel installs).

This implementation provides:

- A best-effort `setuptools` install hook in `setup.py`
- A manual CLI entry point: `package-tracker`

## Installation

Inside a package that uses setuptools:

```bash
pip install reo-package-tracker
```

Or from this directory:

```bash
cd python
pip install .
```

## Configuration

### Environment Variables

- `PACKAGE_TRACKER_ANALYTICS=false` - Disable tracking
- `PACKAGE_TRACKER_ANALYTICS=true` - Enable tracking for opt-in mode
- `PACKAGE_TRACKER_VERBOSE=true` - Enable verbose logging
- `PACKAGE_TRACKER_ENDPOINT=https://telemetry.reo.dev/data` - Custom endpoint

### `pyproject.toml` settings

Add this to your package:

```toml
[tool.reoSettings]
defaultOptIn = false
endpoint = "https://telemetry.reo.dev/data"
```

Settings:

- `defaultOptIn` (boolean, default: `true`)
  - `true`: opt-out mode (tracking enabled unless explicitly disabled)
  - `false`: opt-in mode (tracking disabled unless explicitly enabled)
- `endpoint` (string, optional)
  - Tracking endpoint override

## Usage

### Manual run

```bash
PACKAGE_TRACKER_VERBOSE=true package-tracker
```

### Module run

```bash
python -m package_tracker
```

## Payload Shape

The payload includes:

- `package`: package name and version
- `system`: platform, architecture, Python version, OS info
- `installation`: timestamp, cwd, install context
- `metadata`: git user/domain, CI context, pip user (if available)

## Privacy & Opt-Out

Collected:

- Package metadata
- System/platform metadata
- Installation context
- Email domain only (never full email)

Not collected:

- Source code contents
- Passwords or secrets
- Full email addresses

Users can always disable telemetry:

```bash
export PACKAGE_TRACKER_ANALYTICS=false
pip install your-package
```

## Development

See `python/TESTING.md` for test flows and verification commands.

## License

MIT
