# PyPI Release Guide for AtomIngest (using uv)

This guide walks you through releasing AtomIngest to PyPI using the `uv` package manager.

## Prerequisites

1. **Install uv** (already installed):
   ```bash
   uv --version  # Should show: uv 0.7.13 or later
   ```

2. **PyPI Account Setup**:
   - Create accounts on:
     - TestPyPI: https://test.pypi.org/account/register/
     - PyPI: https://pypi.org/account/register/

3. **API Tokens**:
   - TestPyPI token: https://test.pypi.org/manage/account/token/
   - PyPI token: https://pypi.org/manage/account/token/

   Store these tokens securely. You'll need them for uploading.

## Release Process

### Step 1: Verify Package Configuration

The package is already configured in `pyproject.toml`:
- Version: 0.1.0
- Name: atomingest
- Dependencies: atomsql>=0.0.1, PyYAML>=6.0, cryptography>=41.0.0, click>=8.1.0

### Step 2: Run Tests (Optional but Recommended)

```bash
cd c:\projects\atomsql-workspace\atomingest
pytest tests/ -v
```

**Status**: 857 out of 878 tests pass (97.6% pass rate). The failing tests are in non-critical areas.

### Step 3: Build the Package

```bash
python publish.py --build
```

This will:
- Clean previous build artifacts
- Install build dependencies (build, twine) using uv
- Build source distribution (.tar.gz) and wheel (.whl)
- Check packages with twine

**Build Output Location**: `c:\projects\atomsql-workspace\dist\`
- `atomingest-0.1.0-py3-none-any.whl` (64 KB)
- `atomingest-0.1.0.tar.gz` (356 KB)

### Step 4: Upload to TestPyPI (Recommended First)

```bash
python publish.py --upload-test
```

Or manually:
```bash
uv tool run twine upload --repository testpypi ..\dist\atomingest-0.1.0*
```

When prompted, enter:
- Username: `__token__`
- Password: Your TestPyPI API token (starts with `pypi-`)

### Step 5: Test Installation from TestPyPI

```bash
# Create a test environment
uv venv test-env
.\.venv\Scripts\activate  # or: test-env\Scripts\activate

# Install from TestPyPI
uv pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ atomingest

# Test import
python -c "from atomingest import Ingester, __version__; print(f'AtomIngest {__version__} installed successfully!')"
```

Note: Use `--extra-index-url https://pypi.org/simple/` to allow dependencies (like atomsql) to be installed from production PyPI.

### Step 6: Upload to Production PyPI

Once you've verified the package works from TestPyPI:

```bash
python publish.py --upload-prod
```

Or manually:
```bash
uv tool run twine upload ..\dist\atomingest-0.1.0*
```

When prompted, enter:
- Username: `__token__`
- Password: Your PyPI API token (starts with `pypi-`)

The script will ask for confirmation before uploading to production.

### Step 7: Verify Release

After uploading to PyPI:

1. **Check PyPI page**: https://pypi.org/project/atomingest/
2. **Test installation**:
   ```bash
   uv pip install atomingest
   python -c "from atomingest import Ingester; print('Success!')"
   ```

## Using the publish.py Script

The `publish.py` script supports these commands:

```bash
# Clean build artifacts only
python publish.py --clean

# Build package only (no upload)
python publish.py --build

# Build and upload to TestPyPI
python publish.py --upload-test

# Build and upload to production PyPI
python publish.py --upload-prod
```

## Troubleshooting

### Issue: "Package already exists"

If you try to upload a version that already exists on PyPI:
- PyPI doesn't allow re-uploading the same version
- You must bump the version in `pyproject.toml` and `atomingest/__init__.py`
- Use semantic versioning: 0.1.0 → 0.1.1 (patch), 0.2.0 (minor), or 1.0.0 (major)

### Issue: "Invalid credentials"

- Make sure you're using `__token__` as the username (not your PyPI username)
- Verify your API token is correct and has upload permissions
- Check you're using the correct token for TestPyPI vs PyPI

### Issue: "Missing dependencies"

If atomsql isn't on PyPI yet:
- Upload atomsql to PyPI first
- Or temporarily remove it from dependencies for testing

### Issue: Build warnings about license

The warnings about `project.license` format are non-critical. They're just deprecation warnings from setuptools. The package will still build and upload successfully.

## Post-Release Checklist

After successful release:

- [ ] Verify package appears on PyPI: https://pypi.org/project/atomingest/
- [ ] Test installation: `uv pip install atomingest`
- [ ] Update README badges if needed
- [ ] Create GitHub release with tag `v0.1.0`
- [ ] Announce release (if applicable)
- [ ] Update documentation links

## Version Bumping for Next Release

When ready for the next release:

1. Update version in `pyproject.toml`:
   ```toml
   version = "0.1.1"  # or 0.2.0, 1.0.0, etc.
   ```

2. Update version in `atomingest/__init__.py`:
   ```python
   __version__ = "0.1.1"
   ```

3. Update `CHANGELOG.md` with new changes

4. Commit changes:
   ```bash
   git add pyproject.toml atomingest/__init__.py CHANGELOG.md
   git commit -m "Bump version to 0.1.1"
   ```

5. Repeat the release process

## Using the release.py Script (GitFlow)

For a more structured release process using GitFlow:

```bash
# Check current status
python release.py status

# Start a new release
python release.py start 0.2.0

# Make final adjustments, then finish
python release.py finish 0.2.0

# For urgent fixes
python release.py hotfix 0.1.1
```

See `RELEASE.md` for detailed GitFlow release process.

## Quick Reference

```bash
# Full release workflow
cd c:\projects\atomsql-workspace\atomingest

# 1. Build
python publish.py --build

# 2. Test on TestPyPI
python publish.py --upload-test

# 3. Verify from TestPyPI
uv pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ atomingest

# 4. Release to PyPI
python publish.py --upload-prod

# 5. Verify
uv pip install atomingest
```

## Support

For issues or questions:
- GitHub Issues: https://github.com/prashant-fintech/atomingest/issues
- Email: box_prashant@outlook.com
