# PyPI Publishing Guide for CompALGO

**Package:** compalgo  
**Version:** 0.1.0  
**PyPI URL:** https://pypi.org/project/compalgo/

---

## 🚀 Step-by-Step Publishing Process

### Step 1: Install Build Tools

```powershell
# Install build and twine (PyPI upload tool)
pip install --upgrade build twine
```

### Step 2: Clean Previous Builds (if any)

```powershell
# Remove old build artifacts
if (Test-Path dist) { Remove-Item -Recurse -Force dist }
if (Test-Path build) { Remove-Item -Recurse -Force build }
if (Test-Path *.egg-info) { Remove-Item -Recurse -Force *.egg-info }
```

### Step 3: Build Distribution Packages

```powershell
# Build both wheel and source distribution
python -m build
```

**Expected output:**
```
Successfully built compalgo-0.1.0.tar.gz and compalgo-0.1.0-py3-none-any.whl
```

This creates:
- `dist/compalgo-0.1.0.tar.gz` (source distribution)
- `dist/compalgo-0.1.0-py3-none-any.whl` (wheel distribution)

### Step 4: Verify Package Contents (Optional but Recommended)

```powershell
# Check what's in the package
tar -tzf dist/compalgo-0.1.0.tar.gz

# Or use twine to check
twine check dist/*
```

**Expected:** No errors, all files included correctly

### Step 5: Configure PyPI API Token

**Option A: Interactive (Recommended for first time)**
```powershell
# Twine will prompt for credentials when you upload
# Username: __token__
# Password: <your-pypi-token>
```

**Option B: Store in .pypirc file**

Create `~/.pypirc` (in your home directory):
```ini
[pypi]
username = __token__
password = pypi-AgEIcHlwaS5vcmc...your-full-token...
```

**Windows location:** `C:\Users\sarth\.pypirc`

**⚠️ IMPORTANT:** 
- Username must be `__token__` (literally, not your username)
- Password is your full API token starting with `pypi-`

### Step 6: Upload to PyPI

```powershell
# Upload to PyPI (will prompt for token if not in .pypirc)
twine upload dist/*
```

**You'll be prompted:**
```
Uploading distributions to https://upload.pypi.org/legacy/
Enter your username: __token__
Enter your password: <paste-your-token>
```

**Expected output:**
```
Uploading compalgo-0.1.0-py3-none-any.whl
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 50.0/50.0 kB
Uploading compalgo-0.1.0.tar.gz
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 45.0/45.0 kB

View at:
https://pypi.org/project/compalgo/0.1.0/
```

### Step 7: Verify on PyPI

1. Visit: https://pypi.org/project/compalgo/
2. Check version shows 0.1.0
3. Verify README displays correctly
4. Check all metadata is correct

### Step 8: Test Installation

```powershell
# Create a new test environment
python -m venv test_env
.\test_env\Scripts\activate

# Install from PyPI
pip install compalgo

# Test it works
compalgo --version
compalgo list-policies

# Clean up
deactivate
Remove-Item -Recurse -Force test_env
```

---

## 🔧 Troubleshooting

### Error: "Invalid or non-existent authentication information"
**Solution:** Make sure:
- Username is `__token__` (not your PyPI username)
- Password is your full API token
- Token has upload permissions

### Error: "File already exists"
**Solution:** You can't re-upload the same version. Either:
- Increase version in `pyproject.toml` to 0.1.1
- Delete the release on PyPI (not recommended)

### Error: "Package name already taken"
**Solution:** The name `compalgo` should be available. If not:
- Check if you own it already
- Use `compalgo-sdk` or similar variant

### Error: "README rendering failed"
**Solution:** Check README.md syntax:
```powershell
twine check dist/*
```

---

## 📦 What Gets Uploaded

Your package will include:
- ✅ `compalgo/` - Main package code
- ✅ `README.md` - Package description
- ✅ `LICENSE` - MIT License
- ✅ `pyproject.toml` - Package metadata
- ❌ `tests/` - Not included (good!)
- ❌ `.env` - Not included (good!)
- ❌ `examples/` - Not included (optional)

To check what's included:
```powershell
tar -tzf dist/compalgo-0.1.0.tar.gz
```

---

## 🎯 Post-Publishing Checklist

After successful upload:

- [ ] Visit https://pypi.org/project/compalgo/
- [ ] Verify package page looks good
- [ ] Test `pip install compalgo` in fresh environment
- [ ] Test CLI: `compalgo --version`
- [ ] Update README with PyPI badge
- [ ] Create GitHub release (v0.1.0)
- [ ] Announce on social media
- [ ] Update documentation to use `pip install compalgo`

---

## 📈 Adding PyPI Badge to README

Add this to your README.md:

```markdown
[![PyPI version](https://badge.fury.io/py/compalgo.svg)](https://badge.fury.io/py/compalgo)
[![Downloads](https://pepy.tech/badge/compalgo)](https://pepy.tech/project/compalgo)
[![Python Versions](https://img.shields.io/pypi/pyversions/compalgo.svg)](https://pypi.org/project/compalgo/)
```

---

## 🔄 Publishing Updates (Future Versions)

When you want to publish 0.1.1, 0.2.0, etc.:

1. Update version in `pyproject.toml`
2. Update CHANGELOG (create if needed)
3. Commit changes
4. Tag release: `git tag v0.1.1`
5. Build: `python -m build`
6. Upload: `twine upload dist/*`
7. Push tag: `git push --tags`

---

## 🔐 Security Best Practices

**DO:**
- ✅ Store API token in `.pypirc` with secure permissions
- ✅ Use scoped tokens (project-specific)
- ✅ Add `.pypirc` to `.gitignore`

**DON'T:**
- ❌ Commit API token to git
- ❌ Share API token publicly
- ❌ Use account password (use token)

---

## 📊 Quick Command Reference

```powershell
# Full publishing workflow
pip install --upgrade build twine
python -m build
twine check dist/*
twine upload dist/*

# Test installation
pip install compalgo
compalgo --version

# Update version and republish
# 1. Edit pyproject.toml version
# 2. Rebuild and upload
python -m build
twine upload dist/*
```

---

## ✅ Success Criteria

You'll know it worked when:

1. ✅ Twine upload shows "View at: https://pypi.org/project/compalgo/"
2. ✅ PyPI page is live and readable
3. ✅ `pip install compalgo` works in fresh environment
4. ✅ `compalgo --version` shows 0.1.0
5. ✅ All CLI commands work

---

## 🎉 After Publishing

**Share the news!**

```
🚀 CompALGO v0.1.0 is now live on PyPI!

Install: pip install compalgo

CompALGO is a complete compliance platform for Algorand smart contracts:
- ✅ Security analysis (9+ P0 rules)
- ✅ Blockchain anchoring
- ✅ 8 policy packs (PCI-DSS, SOC2, etc.)
- ✅ CLI + Python API

https://pypi.org/project/compalgo/
https://github.com/Compliledger/Comp_Algo
```

---

**Ready to publish?** Follow the steps above! 🚀

**Questions?** Check PyPI docs: https://packaging.python.org/
