Publishing WRTKit to PyPI¶

This guide explains how to publish the wrtkit package to PyPI.

Prerequisites¶

Create accounts on:
PyPI
TestPyPI (for testing)
Install build tools:
```
pip install build twine
```

Before Publishing¶

Update version in pyproject.toml:
```
version = "0.1.0"  # Update this
```

Update author information in pyproject.toml:

authors = [
    {name = "Your Name", email = "your.email@example.com"}
]

Update URLs in pyproject.toml:

[project.urls]
Homepage = "https://github.com/yourusername/wrtkit"
Repository = "https://github.com/yourusername/wrtkit"

Run tests:
```
pytest
```

Check code quality:

black src/ tests/ examples/
ruff check src/ tests/ examples/
mypy src/

Building the Package¶

Build the distribution packages:

python -m build

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

Testing on TestPyPI¶

Upload to TestPyPI:

python -m twine upload --repository testpypi dist/*

Test installation from TestPyPI:

pip install --index-url https://test.pypi.org/simple/ wrtkit

Test the installed package:

python -c "from wrtkit import UCIConfig; print('Success!')"

Publishing to PyPI¶

Once you've verified everything works on TestPyPI:

Upload to PyPI:
```
python -m twine upload dist/*
```
Install from PyPI:
```
pip install wrtkit
```

Using GitHub Actions for Automated Publishing¶

The repository includes a GitHub Actions workflow that automatically publishes to PyPI when you create a release.

Setup¶

Create a PyPI API token:
Go to https://pypi.org/manage/account/token/
Create a new token with upload permissions
Copy the token (it starts with pypi-)
Add the token to GitHub Secrets:
Go to your repository on GitHub
Settings → Secrets and variables → Actions
Click "New repository secret"
Name: PYPI_API_TOKEN
Value: Your PyPI token

Creating a Release¶

Update the version in pyproject.toml

Commit and push the changes:

git add pyproject.toml
git commit -m "Bump version to 0.1.0"
git push

Create a git tag:
```
git tag v0.1.0
git push origin v0.1.0
```
Create a release on GitHub:
Go to your repository on GitHub
Click "Releases" → "Create a new release"
Select the tag you created
Add release notes
Click "Publish release"

The GitHub Action will automatically build and publish the package to PyPI.

Versioning¶

Follow Semantic Versioning: - MAJOR version for incompatible API changes - MINOR version for new functionality in a backwards compatible manner - PATCH version for backwards compatible bug fixes

Examples: - 0.1.0 - Initial release - 0.1.1 - Bug fix - 0.2.0 - New features - 1.0.0 - First stable release

Troubleshooting¶

Authentication Issues¶

If you have trouble authenticating, use API tokens instead of passwords:

python -m twine upload --repository pypi dist/* --username __token__ --password pypi-YOUR-TOKEN

File Already Exists Error¶

You cannot upload the same version twice. Increment the version number in pyproject.toml and rebuild.

Import Errors After Installation¶

Make sure the package structure is correct:

src/
  wrtkit/
    __init__.py
    ...

And that pyproject.toml has:

[tool.setuptools.packages.find]
where = ["src"]