# PyPI release guide

This package is intended for the Python Package Index, `PyPI`, not `PyPy`.

## 1. Configure trusted publishing

For GitHub Actions publishing, configure trusted publishing on both TestPyPI and PyPI:

1. Create the project on GitHub.
2. On TestPyPI and PyPI, add a trusted publisher for this repository.
3. Point it to:
   - Owner: your GitHub user or org
   - Repository: `litellm-detector`
   - Workflow:
     - `.github/workflows/publish-testpypi.yml` for TestPyPI
     - `.github/workflows/publish-pypi.yml` for PyPI

This removes the need for long-lived API tokens in GitHub secrets.

## 2. Create the project on TestPyPI first

1. Create accounts on:
   - <https://test.pypi.org/>
   - <https://pypi.org/>
2. If you want manual local uploads too, generate an API token on both sites.
3. Store them in `~/.pypirc`:

```ini
[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = pypi-...

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-...
```

## 3. Build the package

```bash
python -m pip install --upgrade build twine
python -m build
```

This should create both `.tar.gz` and `.whl` files in `dist/`.

## 4. Validate the artifacts

```bash
python -m twine check dist/*
```

## 5. Upload to TestPyPI

```bash
python -m twine upload --repository testpypi dist/*
```

Then verify install:

```bash
python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple litellm-detector
litellm-detector --help
```

You can also use the included GitHub Actions workflow:

- Push a tag like `test-v0.1.0`, or
- Run the `Publish TestPyPI` workflow manually from the Actions tab

## 6. Upload to PyPI

```bash
python -m twine upload dist/*
```

Or use GitHub Releases:

1. Push your code and tag.
2. Create a GitHub release for the version.
3. Publishing the release triggers `.github/workflows/publish-pypi.yml`.

## 7. Tag the release

```bash
git tag v0.1.0
git push origin v0.1.0
```

For TestPyPI workflow tags:

```bash
git tag test-v0.1.0
git push origin test-v0.1.0
```

## 8. Recommended hardening

- Enable trusted publishing if the repo will publish from GitHub Actions.
- Reserve the exact package name early on PyPI.
- Add a screenshot or terminal GIF to the GitHub README.
- Publish from a clean environment so you do not accidentally ship extra files.
