# 📦 Publishing Apex Package to PyPI

## Prerequisites

Your package is ready for publication with:
- ✅ Clean code (no errors)
- ✅ Comprehensive documentation
- ✅ Test suite (87.5% passing)
- ✅ Modern src-layout structure
- ✅ Complete metadata in `pyproject.toml`

---

## 🔧 Step 1: Install Publishing Tools

```bash
# Install build tools
pip install build

# Install twine for uploading
pip install twine
```

---

## 🔑 Step 2: Configure PyPI Authentication

### Option A: Test PyPI (Recommended for First Upload)

Create `~/.pypirc` with your Test PyPI token:

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

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

**Get your Test PyPI token:**
1. Go to https://test.pypi.org/
2. Register an account
3. Go to Account Settings → API tokens
4. Create a new token with scope: "Entire account"
5. Copy the token (starts with `pypi-`)
6. Replace `pypi-XXXXXXXXXXXXXXXXXXXXXXXX` in `.pypirc`

### Option B: Production PyPI

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

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

---

## 📦 Step 3: Build the Package

```bash
# Clean previous builds
rm -rf dist/ build/ *.egg-info

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

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

**This creates:**
- `dist/apex-0.1.0.tar.gz` - Source distribution
- `dist/apex-0.1.0-py3-none-any.whl` - Wheel distribution

---

## 🚀 Step 4: Upload to PyPI

### Upload to Test PyPI (Recommended First)

```bash
# Upload to Test PyPI
twine upload --repository testpypi dist/*
```

### Upload to Production PyPI

```bash
# Upload to production PyPI
twine upload dist/*
```

**You'll see:**
```
Uploading distributions to https://test.pypi.org/legacy/
Uploading apex-0.1.0-py3-none-any.whl
Uploading apex-0.1.0.tar.gz
```

---

## ✅ Step 5: Verify Upload

### Test Installation from Test PyPI

```bash
# Create a test environment
python -m venv test_env
source test_env/bin/activate

# Install from Test PyPI
pip install --index-url https://test.pypi.org/simple/ apex

# Test import
python -c "from apex import __version__; print(f'Apex version: {__version__}')"
```

### Test Installation from Production PyPI

```bash
pip install apex
```

---

## 🔄 Publishing Updates

When you make changes and want to publish a new version:

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

2. **Clean and rebuild:**
   ```bash
   rm -rf dist/ build/ *.egg-info
   python -m build
   ```

3. **Upload:**
   ```bash
   twine upload --repository testpypi dist/*
   ```

---

## 📋 Pre-Upload Checklist

Before uploading, verify:

- [ ] Package name is unique (check https://test.pypi.org/search/)
- [ ] Version number is correct in `pyproject.toml`
- [ ] README.md is up to date
- [ ] LICENSE file exists
- [ ] All dependencies are listed in `pyproject.toml`
- [ ] .gitignore excludes dist/, build/, *.egg-info
- [ ] No sensitive data in code (API keys, passwords)
- [ ] Tests are passing
- [ ] Documentation is complete

---

## 🚨 Common Issues & Solutions

### Issue: Package name already exists

**Solution:** Change `name` in `pyproject.toml`:
```toml
name = "apex-saas"  # or "apex-backend", "apex-framework"
```

### Issue: Authentication failed

**Solution:** 
1. Verify `.pypirc` file permissions: `chmod 600 ~/.pypirc`
2. Check token is correct and not expired
3. Ensure no extra spaces in token

### Issue: Build fails

**Solution:**
```bash
# Reinstall build tools
pip install --upgrade build setuptools wheel
python -m build
```

### Issue: Twine upload fails

**Solution:**
```bash
# Check package with twine first
twine check dist/*

# If valid, try upload again
twine upload --repository testpypi dist/* --verbose
```

---

## 📊 Package Versioning

Follow Semantic Versioning (SemVer): `MAJOR.MINOR.PATCH`

- **MAJOR** (1.0.0): Incompatible API changes
- **MINOR** (0.1.0): Backward-compatible new features
- **PATCH** (0.0.1): Backward-compatible bug fixes

**Examples:**
- `0.1.0` - Initial development release
- `0.2.0` - Added SendGrid integration
- `0.2.1` - Fixed bug in SendGrid adapter
- `1.0.0` - First stable release

---

## 🎯 Your Current Package Info

```
Package Name: apex
Version: 0.1.0
Python: >=3.10
License: MIT
Author: Your Name
```

---

## 🔗 Useful Links

- **Test PyPI:** https://test.pypi.org/
- **Production PyPI:** https://pypi.org/
- **Packaging Guide:** https://packaging.python.org/
- **Twine Docs:** https://twine.readthedocs.io/
- **Build Docs:** https://build.pypa.io/

---

## 📝 Quick Reference Commands

```bash
# Complete publishing workflow
pip install build twine
python -m build
twine check dist/*
twine upload --repository testpypi dist/*

# Test installation
pip install --index-url https://test.pypi.org/simple/ apex

# For production PyPI
twine upload dist/*
```

---

## ✅ Ready to Publish!

Your **Apex** package is ready for publication to PyPI! Follow the steps above to share your package with the world.

**Next Steps:**
1. Get your PyPI API token
2. Configure `.pypirc`
3. Build the package
4. Upload to Test PyPI first
5. Test installation
6. Upload to production PyPI when ready

Good luck! 🚀

