# Publishing pywasot to PyPI

This guide covers how to build and publish the `pywasot` Python package to PyPI.

## Prerequisites

- [uv](https://docs.astral.sh/uv/) installed
- PyPI account at https://pypi.org/account/register/
- API token from https://pypi.org/manage/account/token/

## Building

Run the build script:

```bash
./scripts/build_python.sh
```

This creates two files in `dist/`:
- `pywasot-X.Y.Z-cp38-abi3-linux_x86_64.whl` - Pre-built wheel for Linux
- `pywasot-X.Y.Z.tar.gz` - Source distribution

## Publishing

### First-time setup

Create `~/.pypirc` with your API token:

```ini
[pypi]
username = __token__
password = pypi-YOUR-API-TOKEN-HERE
```

Or set the environment variable:

```bash
export UV_PUBLISH_TOKEN=pypi-YOUR-API-TOKEN-HERE
```

### Publish to PyPI

```bash
uv publish dist/*
```

Or with twine:

```bash
pip install twine
twine upload dist/*
```

### Publish to TestPyPI first (recommended)

Test your release on TestPyPI before publishing to the real PyPI:

1. Get a TestPyPI token from https://test.pypi.org/manage/account/token/

2. Publish to TestPyPI:
   ```bash
   uv publish --publish-url https://test.pypi.org/legacy/ dist/*
   ```

3. Test installation:
   ```bash
   pip install --index-url https://test.pypi.org/simple/ pywasot
   ```

4. If everything works, publish to real PyPI:
   ```bash
   uv publish dist/*
   ```

## Versioning

Update the version in `pyproject.toml` before each release:

```toml
[project]
version = "0.1.1"  # Bump this
```

PyPI does not allow re-uploading the same version, so always increment.

## Troubleshooting

### "File already exists" error

You're trying to upload a version that already exists. Bump the version in `pyproject.toml` and rebuild.

### Authentication failed

Check that your API token is correct and has upload permissions. Tokens start with `pypi-`.

### Build fails with Python version error

The package uses PyO3 with ABI3, which requires the stable Python ABI. If you see Python version errors, ensure you have Python 3.8+ installed.
