Skip to content

PYPI_PUBLISH.md

Latest commit

 

History

History
435 lines (304 loc) · 7.97 KB

PYPI_PUBLISH.md

File metadata and controls

435 lines (304 loc) · 7.97 KB
Raw

📦 Publishing Valkeyrie to PyPI

Complete guide to publish your Python client so users can install with pip install valkeyrie

🚀 Quick Start

Prerequisites

# Install required tools
pip install --upgrade pip setuptools wheel twine build

Create PyPI Account

  1. Go to https://pypi.org/account/register/
  2. Create account
  3. Verify email
  4. Enable 2FA (recommended)

Create API Token

  1. Go to https://pypi.org/manage/account/
  2. Scroll to "API tokens"
  3. Click "Add API token"
  4. Name: "valkeyrie-upload"
  5. Scope: "Entire account" (or specific project after first upload)
  6. Copy the token (starts with pypi-)

📋 Step-by-Step Publishing

Step 1: Prepare Package

cd "Distributed Cache System\mini-redis\clients\python"

# Verify structure
dir
# Should see:
# - valkeyrie.py
# - setup.py
# - pyproject.toml
# - README.md
# - LICENSE
# - MANIFEST.in

Step 2: Build Distribution

# Clean old builds
rmdir /s /q build dist valkeyrie.egg-info 2>nul

# Build package
python -m build

# This creates:
# dist/valkeyrie-1.0.0.tar.gz       (source distribution)
# dist/valkeyrie-1.0.0-py3-none-any.whl  (wheel)

Step 3: Test with TestPyPI (Optional but Recommended)

# Upload to TestPyPI first
python -m twine upload --repository testpypi dist/*

# Username: __token__
# Password: <your-testpypi-token>

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

# Test it works
python -c "from valkeyrie import ValkeyreClient; print('Success!')"

Step 4: Upload to PyPI

# Upload to real PyPI
python -m twine upload dist/*

# Username: __token__
# Password: <your-pypi-token>

Step 5: Verify Published

Go to https://pypi.org/project/valkeyrie/

🎉 Users Can Now Install

pip install valkeyrie
from valkeyrie import ValkeyreClient

with ValkeyreClient('localhost', 6379) as client:
    client.set('hello', 'world')
    print(client.get('hello'))

🔄 Publishing Updates

For New Versions

  1. Update version in setup.py and pyproject.toml:

    version="1.0.1"  # Increment version

  2. Rebuild and upload:

    # Clean
rmdir /s /q build dist valkeyrie.egg-info 2>nul

# Build new version
python -m build

# Upload
python -m twine upload dist/*

Semantic Versioning

  • 1.0.0 → 1.0.1 - Bug fixes
  • 1.0.0 → 1.1.0 - New features (backward compatible)
  • 1.0.0 → 2.0.0 - Breaking changes

🔐 Secure Token Storage

Option 1: .pypirc File

Create C:\Users\<username>\.pypirc:

[pypi]
username = __token__
password = pypi-YOUR_TOKEN_HERE

[testpypi]
username = __token__
password = pypi-YOUR_TESTPYPI_TOKEN_HERE

Then simply run:

python -m twine upload dist/*

Option 2: Environment Variable

# PowerShell
$env:TWINE_USERNAME = "__token__"
$env:TWINE_PASSWORD = "pypi-YOUR_TOKEN_HERE"

python -m twine upload dist/*

📊 Post-Publishing Checklist

Update Project README

Add installation badge to main README.md:

[![PyPI version](https://badge.fury.io/py/valkeyrie.svg)](https://badge.fury.io/py/valkeyrie)
[![Downloads](https://pepy.tech/badge/valkeyrie)](https://pepy.tech/project/valkeyrie)

## Installation

```bash
pip install valkeyrie

### Announce Your Package

- **Reddit**: r/Python, r/programming
- **Twitter/X**: #Python #OpenSource
- **LinkedIn**: Share with network
- **Dev.to**: Write a blog post
- **Hacker News**: Show HN post

### Monitor Usage

- **PyPI Stats**: https://pypi.org/project/valkeyrie/#history
- **Downloads**: https://pepy.tech/project/valkeyrie
- **GitHub Stars**: Track interest

---

## 🐛 Troubleshooting

### Error: "File already exists"

The version is already published. Increment version number.

### Error: "Invalid authentication credentials"

Check your API token:
- Must start with `pypi-`
- Username must be `__token__`
- Token must be active

### Error: "Distribution not found"

```bash
# Rebuild package
python -m build

Import Error After Install

# Reinstall in development mode for testing
pip install -e .

README not showing on PyPI

  • Ensure README.md exists
  • Verify long_description_content_type="text/markdown" in setup.py
  • Check MANIFEST.in includes README.md

📚 Package Quality Checklist

Before publishing, ensure:

  • README.md with clear examples
  • LICENSE file (MIT)
  • Version number follows semver
  • All imports work correctly
  • No hardcoded credentials/secrets
  • Type hints (optional but recommended)
  • Docstrings in functions
  • Test on fresh Python environment

🔄 Automated Publishing with GitHub Actions

Create .github/workflows/publish-pypi.yml:

name: Publish to PyPI

on:
  release:
    types: [published]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    
    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.9'
    
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install build twine
    
    - name: Build package
      working-directory: clients/python
      run: python -m build
    
    - name: Publish to PyPI
      working-directory: clients/python
      env:
        TWINE_USERNAME: __token__
        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
      run: twine upload dist/*

Add PYPI_API_TOKEN to GitHub repository secrets.

🎯 Marketing Your Package

Create Examples Repository

# examples/quickstart.py
from valkeyrie import ValkeyreClient

def main():
    with ValkeyreClient('localhost', 6379) as cache:
        # Store user session
        cache.set('session:user123', 'active')
        cache.expire('session:user123', 3600)
        
        # Check session
        if cache.exists('session:user123'):
            print("Session valid!")

if __name__ == '__main__':
    main()

Create Blog Post

Title: "Introducing Valkeyrie: A Redis-Compatible Python Client"

Content:

  • Why you built it
  • Key features
  • Code examples
  • Performance comparisons
  • How to contribute

Social Media Template

🚀 Just published Valkeyrie to PyPI!

A lightweight, Redis-compatible Python client for distributed caching.

Install: pip install valkeyrie

✨ Features:
- Simple API
- Full RESP protocol
- No dependencies
- Python 3.7+

Try it out: https://pypi.org/project/valkeyrie/

#Python #OpenSource #Redis #Caching

📈 Tracking Success

Week 1 Goals

  • ✅ Published to PyPI
  • ✅ 10+ downloads
  • ✅ GitHub README updated
  • ✅ Social media posts

Month 1 Goals

  • ✅ 100+ downloads
  • ✅ 50+ GitHub stars
  • ✅ 1-2 issues/feedback
  • ✅ Documentation site

Month 3 Goals

  • ✅ 1000+ downloads
  • ✅ First external contributor
  • ✅ v1.1.0 with community features

🤝 Maintaining Your Package

Responding to Issues

  • Respond within 24-48 hours
  • Be friendly and helpful
  • Link to documentation
  • Fix bugs promptly

Accepting Pull Requests

  • Thank contributors
  • Review code thoroughly
  • Test before merging
  • Credit in CHANGELOG

Regular Updates

  • Monthly dependency updates
  • Security patches ASAP
  • Feature releases quarterly
  • Bug fix releases as needed

✅ Final Checklist

Before first publish:

  • PyPI account created
  • API token generated
  • Package tested locally
  • README is comprehensive
  • LICENSE file included
  • Version is 1.0.0
  • Built successfully
  • Uploaded to TestPyPI
  • Tested installation from TestPyPI
  • Uploaded to PyPI
  • Installed and tested from PyPI
  • GitHub README updated
  • Announced on social media

🎊 Congratulations!

Your package is now live on PyPI! Anyone can install it with:

pip install valkeyrie

Share your achievement and help others discover your project! 🚀

Questions? Open an issue on GitHub or check PyPI documentation: https://packaging.python.org/