🚀 KHX-Publish-PyPI

✨ A beautiful, intelligent CLI tool to streamline Python package publishing to PyPI and TestPyPI

KHX-Publish-PyPI is an interactive command-line interface that simplifies the entire process of preparing, building, and publishing Python packages. With enhanced version detection supporting all modern build backends, rich visual feedback, intelligent error handling, and secure token management, it makes package publishing as smooth as a breeze.

🎯 NEW: Enhanced Version Detection System - Works with ANY modern Python package configuration including setuptools, scikit-build-core, setuptools-scm, flit, hatchling, and more!

🆕 What's New in Latest Version

🚀 Enhanced Version Detection System

• ✅ Universal compatibility with all modern Python build backends
• ✅ Intelligent 5-stage fallback detection process
• ✅ Rich diagnostics showing detection method, source, and confidence
• ✅ Programmatic API for advanced integration
• ✅ Comprehensive support for dynamic versioning configurations

📊 Before vs After

Before: Limited to basic setuptools configurations
After: Works with setuptools, scikit-build-core, setuptools-scm, flit, hatchling, and more!

Before: 🔢 Version .......................... ✅ (0.1.11)
After: 🔢 Version .......................... ✅ (v0.1.12 (setuptools_dynamic_attr) dynamic backend:setuptools)

🎯 Enhanced Output Example

🔢 Version .......................... ✅ (v0.1.12 (setuptools_dynamic_attr) dynamic backend:setuptools)

This shows you:

• Version: 0.1.12
• Detection Method: setuptools_dynamic_attr
• Type: dynamic versioning
• Build Backend: setuptools

🌟 Features

• 🎨 Beautiful Interface: Rich, colorful output with progress bars and interactive prompts
• 🔍 Smart Pre-checks: Validates your package structure, version, and configuration before publishing
• � Enhanced Version Detection: Comprehensive support for all modern Python packaging approaches
  • ✅ Static versions in pyproject.toml
  • ✅ Dynamic versions with setuptools, scikit-build-core, setuptools-scm, flit, hatchling
  • ✅ Intelligent fallback system with 5-stage detection process
  • ✅ Rich diagnostics showing detection method, source, and confidence scoring
• �🔐 Secure Token Management: Stores API tokens securely using your system's keyring
• 📦 One-Command Publishing: Complete workflow from checks to upload in a single command
• 🧪 TestPyPI Support: Publish to TestPyPI first for safe testing
• 📈 Version Management: Automatic version bumping with semantic versioning
• 🛠️ Error Intelligence: Provides specific suggestions when uploads fail
• 🚀 CI/CD Ready: Perfect for automated publishing pipelines

📸 Screenshots

🛠️ Installation

From PyPI (Recommended)

pip install khx-publish-pypi

Check the latest version:

khx-publish-pypi --version

From GitHub (Release or main)

• Install from a tagged GitHub Release asset (requires download first):
  • Go to Releases, download the .whl or .tar.gz from assets, then:

    pip install path/to/khx_publish_pypi-<version>-py3-none-any.whl
    # or
    pip install path/to/khx_publish_pypi-<version>.tar.gz
    

• Or install directly from the repo using pip’s VCS support:

  # specific tag
  pip install git+https://github.com/Khader-X/khx-publish-pypi.git@vX.Y.Z#egg=khx_publish_pypi
  # latest on default branch
  pip install git+https://github.com/Khader-X/khx-publish-pypi.git@main#egg=khx_publish_pypi
  

From Source (Development)

git clone https://github.com/Khader-X/khx-publish-pypi.git
cd khx-publish-pypi
pip install -e .

Requirements

• Python 3.9+
• twine for uploads
• build for package building
• keyring for secure token storage

🚀 Quick Start

1. Install the package

   pip install khx-publish-pypi
   

2. Set up your API tokens

   khx-publish-pypi setup-tokens
   

3. Publish your package

   khx-publish-pypi run
   

That's it! The guided workflow will handle everything else.

📖 Usage

Interactive Publishing (Recommended)

khx-publish-pypi run

This command provides a complete guided experience:

• ✅ Runs pre-publish checks with enhanced version detection
• 🔑 Manages API token configuration
• 📈 Offers version bumping options
• 🏗️ Builds your package distributions
• 📤 Publishes to TestPyPI and/or PyPI

Individual Commands

# Run pre-publish checks with enhanced version detection
khx-publish-pypi check

# Bump version
khx-publish-pypi bump patch

# Publish to TestPyPI only
khx-publish-pypi publish-test

# Publish to PyPI only
khx-publish-pypi publish-prod

Programmatic API (New!)

KHX-Publish-PyPI now exposes a powerful programmatic API for version detection:

from khx_publish_pypi import detect_package_version, get_package_version
from pathlib import Path

# Simple version detection (legacy interface)
version = get_package_version(Path("."))
print(f"Version: {version}")

# Enhanced detection with full diagnostics
result = detect_package_version(Path("."))
if result.version_info:
    info = result.version_info
    print(f"Version: {info.version}")
    print(f"Method: {info.method}")
    print(f"Backend: {info.build_backend}")
    print(f"Confidence: {info.confidence}%")
    print(f"Source: {info.source}")
else:
    print(f"Failed: {', '.join(result.attempts)}")

📚 CLI Commands

Command Options

Token Setup

# Interactive setup
khx-publish-pypi setup-tokens

# Non-interactive setup
khx-publish-pypi setup-tokens --test-token YOUR_TEST_TOKEN --prod-token YOUR_PROD_TOKEN

Version Bumping

khx-publish-pypi bump patch  # 1.0.0 → 1.0.1
khx-publish-pypi bump minor  # 1.0.1 → 1.1.0
khx-publish-pypi bump major  # 1.1.0 → 2.0.0

⚙️ Configuration

API Tokens

KHX-Publish-PyPI securely stores your PyPI API tokens using your system's keyring:

• TestPyPI: Stored as khx-publish-testpypi
• PyPI: Stored as khx-publish-pypi

Getting API Tokens

1. TestPyPI Token: Generate at test.pypi.org
2. PyPI Token: Generate at pypi.org

Environment Variables (Alternative)

You can also provide tokens via environment variables:

export TESTPYPI_TOKEN=your_test_token
export PYPI_TOKEN=your_prod_token

Package Requirements

Your Python package must have:

• ✅ pyproject.toml with project metadata
• ✅ README.md file
• ✅ LICENSE file
• ✅ Package directory in src/ or root
• ✅ Version defined anywhere! Our enhanced detection supports:
  • Static version in pyproject.toml
  • Dynamic versions with setuptools, scikit-build-core, setuptools-scm, flit, hatchling
  • __version__.py files in various locations
  • Package __init__.py with __version__ attribute

🔍 Enhanced Version Detection

KHX-Publish-PyPI now features a comprehensive version detection system that handles all modern Python packaging approaches:

Supported Configurations

Intelligent Detection Process

1. Static version from pyproject.toml (100% confidence)
2. Dynamic version from build backend configs (90-95% confidence)
3. Direct package import attempts (85% confidence)
4. File parsing of __version__.py files (80% confidence)
5. Setuptools-scm fallback for git-based projects (70% confidence)

Rich Diagnostics

When version detection succeeds, you'll see detailed information:

🔢 Version .......................... ✅ (v0.1.11 (setuptools_dynamic_attr) dynamic backend:setuptools)

When it fails, you get helpful diagnostics:

🔢 Version .......................... ❌ Failed to detect version. Tried: static_pyproject_version, dynamic_pyproject_version, import_package_version. Errors: Import failed: No module named 'missing_package'

📖 Read the Complete Enhanced Version Detection Guide

🔧 Troubleshooting

Common Issues

❌ Version Detection Failed

Cause: Package version not found or improperly configured Solutions:

1. Ensure __version__ is properly exported in __init__.py:

   from .__version__ import __version__
   __all__ = ["__version__"]
   

2. Check dynamic version configuration in pyproject.toml
3. Verify version file locations match expected patterns
4. Use enhanced diagnostics: khx-publish-pypi check shows detailed detection attempts

❌ Upload Fails with 400 Error

Cause: Package version already exists on PyPI Solution: Bump the version

khx-publish-pypi bump patch

❌ Authentication Failed (403)

Cause: Invalid or expired API token Solution: Reconfigure tokens

khx-publish-pypi setup-tokens

❌ Build Fails

Cause: Missing build dependencies or invalid pyproject.toml Solution: Install build tools and validate configuration

pip install build twine
python -m build --help

❌ Token Storage Issues

Cause: Keyring not available or corrupted Solution: Use environment variables or reinstall keyring

pip uninstall keyring
pip install keyring

Debug Mode

Enable verbose output for troubleshooting:

khx-publish-pypi run --verbose

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature
   

3. Make your changes
4. Run tests

   python -m pytest
   

5. Submit a pull request

Development Setup

git clone https://github.com/Khader-X/khx-publish-pypi.git
cd khx-publish-pypi
pip install -e ".[dev]"

Code Style

• Follow PEP 8
• Use type hints
• Write docstrings for all functions
• Add tests for new features

📊 CI/CD Integration

KHX-Publish-PyPI works great with CI/CD pipelines:

# GitHub Actions example
- name: Publish to PyPI
  run: |
    khx-publish-pypi setup-tokens --test-token ${{ secrets.TEST_PYPI_TOKEN }} --prod-token ${{ secrets.PYPI_TOKEN }}
    khx-publish-pypi publish-prod

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Click for CLI magic
• Beautiful output powered by Rich
• Secure token storage via Keyring
• Package building with Build
• Uploads handled by Twine
• Enhanced version detection supports modern packaging standards

📚 Documentation

• 📖 Enhanced Version Detection Guide: Complete guide to the new version detection system
• 🧪 Test Examples: Comprehensive test suite demonstrating all capabilities
• 💻 API Usage Examples: Programmatic usage examples

📞 Support

• 📧 Email: abueltayef.khader@gmail.com
• 🐛 Issues: GitHub Issues
• 📖 Documentation: GitHub Wiki
• 💬 Discussions: GitHub Discussions

Made with ❤️ by ABUELTAYEF Khader

⭐ Star this repo • 📦 View on PyPI • 📝 Blog