# Publishing to PyPI

This guide will help you publish `octopy-energy-api` to PyPI.

## Prerequisites

1. Create accounts on:
  - [TestPyPI](https://test.pypi.org/account/register/) (for testing)
  - [PyPI](https://pypi.org/account/register/) (for production)

2. Install required tools:
  ```bash
  pip install build twine
  ```

## Step 1: Build the Package

```bash
python -m build
```

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

## Step 2: Test on TestPyPI (Recommended)

Before publishing to the real PyPI, test on TestPyPI:

```bash
# Upload to TestPyPI
python3 -m twine upload --repository testpypi dist/*

# You'll be prompted for:
# Username: __token__
# Password: (your TestPyPI API token)
```

Test the installation:
```bash
# Install from TestPyPI
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ octopy-energy-api

# Test it
python3 -c "from octopy import Octopy; print('Import successful!')"
```

## Step 3: Publish to PyPI

Once you've verified everything works on TestPyPI:

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

# You'll be prompted for:
# Username: __token__
# Password: (your PyPI API token)
```

## Step 4: Verify Installation

After publishing:

```bash
pip install octopy-energy-api

# Test it
python3 -c "from octopy import Octopy; print('Successfully installed from PyPI!')"
```

## API Tokens

For security, use API tokens instead of passwords:

### TestPyPI Token
1. Go to https://test.pypi.org/manage/account/token/
2. Create a new API token
3. Set scope to "Entire account" or specific project
4. Save the token securely

### PyPI Token
1. Go to https://pypi.org/manage/account/token/
2. Create a new API token
3. Set scope to "Entire account" or specific project
4. Save the token securely

## Using .pypirc (Optional)

Create `~/.pypirc` to avoid entering credentials each time:

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

[pypi]
username = __token__
password = pypi-YOUR-ACTUAL-TOKEN-HERE

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-YOUR-ACTUAL-TESTPYPI-TOKEN-HERE
```

Then you can simply run:
```bash
twine upload --repository testpypi dist/*  # For TestPyPI
twine upload dist/*                         # For PyPI
```

## Future Releases

For subsequent releases:

1. Update version in `src/octopy/__about__.py`
2. Add entry to `CHANGELOG.md`
3. Clean previous builds: `rm -rf dist/ build/ *.egg-info`
4. Build: `python3 -m build`
5. Test on TestPyPI
6. Publish to PyPI

## Troubleshooting

### "File already exists" error
- You cannot re-upload the same version
- Increment the version number in `__about__.py`
- Clean and rebuild

### Import errors after installation
- Check that all dependencies are properly specified in `pyproject.toml`
- Verify the package structure with `python3 -m zipfile -l dist/*.whl`

### README not rendering on PyPI
- Validate with: `twine check dist/*`
- Ensure README.md uses standard Markdown (no custom extensions)

## Additional Resources

- [Python Packaging Guide](https://packaging.python.org/)
- [Twine Documentation](https://twine.readthedocs.io/)
- [PyPI Help](https://pypi.org/help/)
