| Name | khx-publish-pypi JSON |
| Version |
0.1.12
JSON |
| download |
| home_page | None |
| Summary | A friendly CLI tool to check and publish Python packages to TestPyPI/PyPI |
| upload_time | 2025-09-07 05:22:12 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
publish
cli
pypi
packaging
release
khx
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ๐ KHX-Publish-PyPI
[](https://pypi.org/project/khx_publish_pypi/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/Khader-X/khx-publish-pypi/actions)
[](https://codecov.io/gh/Khader-X/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
<!--
### Interactive Publishing Workflow
*Complete guided publishing workflow showing checks, token setup, version bumping, and publishing*
### CLI Interface Examples
*Available CLI commands and options*
*Automated validation of package structure and requirements* -->
## ๐ ๏ธ Installation
### From PyPI (Recommended)
```bash
pip install khx-publish-pypi
```
Check the latest version:
```bash
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:
```bash
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:
```bash
# 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)
```bash
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**
```bash
pip install khx-publish-pypi
```
2. **Set up your API tokens**
```bash
khx-publish-pypi setup-tokens
```
3. **Publish your package**
```bash
khx-publish-pypi run
```
That's it! The guided workflow will handle everything else.
## ๐ Usage
### Interactive Publishing (Recommended)
```bash
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
```bash
# 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:
```python
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 | Description |
|---------|-------------|
| `khx-publish-pypi --version` | Show CLI version |
| `khx-publish-pypi check` | Run interactive pre-publish checks |
| `khx-publish-pypi bump [patch\|minor\|major]` | Bump package version |
| `khx-publish-pypi setup-tokens` | Configure API tokens interactively |
| `khx-publish-pypi update-tokens` | Update existing tokens |
| `khx-publish-pypi run` | Complete guided publishing workflow |
| `khx-publish-pypi publish-test` | Publish to TestPyPI |
| `khx-publish-pypi publish-prod` | Publish to PyPI |
### Command Options
#### Token Setup
```bash
# 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
```bash
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](https://test.pypi.org/manage/account/token/)
2. **PyPI Token**: [Generate at pypi.org](https://pypi.org/manage/account/token/)
#### Environment Variables (Alternative)
You can also provide tokens via environment variables:
```bash
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
| **Build Backend** | **Configuration Example** | **Detection Result** |
|------------------|---------------------------|---------------------|
| **Static** | `version = "1.0.0"` in pyproject.toml | `โ
v1.0.0 (static)` |
| **Setuptools** | `{attr = "package.__version__"}` | `โ
v1.0.0 (setuptools_dynamic_attr) dynamic backend:setuptools` |
| **Scikit-build-core** | `provider = "scikit_build_core.metadata.regex"` | `โ
v1.0.0 (scikit_build_regex) dynamic backend:scikit-build-core` |
| **Setuptools-SCM** | `[tool.setuptools_scm]` | `โ
v1.0.0 (setuptools_scm) dynamic backend:setuptools-scm` |
| **Flit** | `[tool.flit.module]` | `โ
v1.0.0 (flit_module) dynamic backend:flit` |
| **Hatchling** | `source = "regex"` | `โ
v1.0.0 (hatchling_regex) dynamic backend:hatchling` |
### 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**](ENHANCED_VERSION_DETECTION.md)
## ๐ง Troubleshooting
### Common Issues
#### โ Version Detection Failed
**Cause**: Package version not found or improperly configured
**Solutions**:
1. Ensure `__version__` is properly exported in `__init__.py`:
```python
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
```bash
khx-publish-pypi bump patch
```
#### โ Authentication Failed (403)
**Cause**: Invalid or expired API token
**Solution**: Reconfigure tokens
```bash
khx-publish-pypi setup-tokens
```
#### โ Build Fails
**Cause**: Missing build dependencies or invalid `pyproject.toml`
**Solution**: Install build tools and validate configuration
```bash
pip install build twine
python -m build --help
```
#### โ Token Storage Issues
**Cause**: Keyring not available or corrupted
**Solution**: Use environment variables or reinstall keyring
```bash
pip uninstall keyring
pip install keyring
```
### Debug Mode
Enable verbose output for troubleshooting:
```bash
khx-publish-pypi run --verbose
```
## ๐ค Contributing
We welcome contributions! Here's how to get started:
1. **Fork the repository**
2. **Create a feature branch**
```bash
git checkout -b feature/amazing-feature
```
3. **Make your changes**
4. **Run tests**
```bash
python -m pytest
```
5. **Submit a pull request**
### Development Setup
```bash
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:
```yaml
# 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](LICENSE) file for details.
## ๐ Acknowledgments
- Built with [Click](https://click.palletsprojects.com/) for CLI magic
- Beautiful output powered by [Rich](https://rich.readthedocs.io/)
- Secure token storage via [Keyring](https://github.com/jaraco/keyring)
- Package building with [Build](https://github.com/pypa/build)
- Uploads handled by [Twine](https://github.com/pypa/twine)
- Enhanced version detection supports modern packaging standards
## ๐ Documentation
- ๐ **[Enhanced Version Detection Guide](ENHANCED_VERSION_DETECTION.md)**: Complete guide to the new version detection system
- ๐งช **[Test Examples](test_enhanced_version_detection.py)**: Comprehensive test suite demonstrating all capabilities
- ๐ป **[API Usage Examples](example_api_usage.py)**: Programmatic usage examples
## ๐ Support
- ๐ง **Email**: abueltayef.khader@gmail.com
- ๐ **Issues**: [GitHub Issues](https://github.com/Khader-X/khx-publish-pypi/issues)
- ๐ **Documentation**: [GitHub Wiki](https://github.com/Khader-X/khx-publish-pypi/wiki)
- ๐ฌ **Discussions**: [GitHub Discussions](https://github.com/Khader-X/khx-publish-pypi/discussions)
---
<p align="center">
Made with โค๏ธ by <a href="https://github.com/Khader20">ABUELTAYEF Khader</a>
</p>
<p align="center">
<a href="https://github.com/Khader-X/khx-publish-pypi">โญ Star this repo</a> โข
<a href="https://pypi.org/project/khx_publish_pypi/">๐ฆ View on PyPI</a> โข
<a href="https://khaderabueltayef.blogspot.com/">๐ Blog</a>
</p>
Raw data
{
"_id": null,
"home_page": null,
"name": "khx-publish-pypi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "ABUELTAYEF Khader <abueltayef.khader.main@hotmail.com>",
"keywords": "publish, cli, pypi, packaging, release, khx",
"author": null,
"author_email": "ABUELTAYEF Khader <abueltayef.khader@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ea/04/f17b923c162e27fc0b9dab79689db8c7c019c52dcb17f9fae25f788141a2/khx_publish_pypi-0.1.12.tar.gz",
"platform": null,
"description": "\r\n# \ud83d\ude80 KHX-Publish-PyPI\r\n\r\n[](https://pypi.org/project/khx_publish_pypi/)\r\n[](https://www.python.org/downloads/)\r\n[](https://opensource.org/licenses/MIT)\r\n[](https://github.com/Khader-X/khx-publish-pypi/actions)\r\n[](https://codecov.io/gh/Khader-X/khx-publish-pypi)\r\n\r\n> \u2728 **A beautiful, intelligent CLI tool to streamline Python package publishing to PyPI and TestPyPI**\r\n\r\nKHX-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.\r\n\r\n\ud83c\udfaf **NEW**: **Enhanced Version Detection System** - Works with **ANY** modern Python package configuration including setuptools, scikit-build-core, setuptools-scm, flit, hatchling, and more!\r\n\r\n## \ud83c\udd95 What's New in Latest Version\r\n\r\n### \ud83d\ude80 Enhanced Version Detection System\r\n- **\u2705 Universal compatibility** with all modern Python build backends\r\n- **\u2705 Intelligent 5-stage fallback** detection process\r\n- **\u2705 Rich diagnostics** showing detection method, source, and confidence\r\n- **\u2705 Programmatic API** for advanced integration\r\n- **\u2705 Comprehensive support** for dynamic versioning configurations\r\n\r\n### \ud83d\udcca Before vs After\r\n**Before**: Limited to basic setuptools configurations \r\n**After**: Works with setuptools, scikit-build-core, setuptools-scm, flit, hatchling, and more!\r\n\r\n**Before**: `\ud83d\udd22 Version .......................... \u2705 (0.1.11)` \r\n**After**: `\ud83d\udd22 Version .......................... \u2705 (v0.1.12 (setuptools_dynamic_attr) dynamic backend:setuptools)`\r\n\r\n### \ud83c\udfaf Enhanced Output Example\r\n```\r\n\ud83d\udd22 Version .......................... \u2705 (v0.1.12 (setuptools_dynamic_attr) dynamic backend:setuptools)\r\n```\r\nThis shows you:\r\n- **Version**: 0.1.12\r\n- **Detection Method**: setuptools_dynamic_attr \r\n- **Type**: dynamic versioning\r\n- **Build Backend**: setuptools\r\n\r\n## \ud83c\udf1f Features\r\n\r\n- \ud83c\udfa8 **Beautiful Interface**: Rich, colorful output with progress bars and interactive prompts\r\n- \ud83d\udd0d **Smart Pre-checks**: Validates your package structure, version, and configuration before publishing\r\n- \ufffd **Enhanced Version Detection**: Comprehensive support for all modern Python packaging approaches\r\n - \u2705 **Static versions** in pyproject.toml\r\n - \u2705 **Dynamic versions** with setuptools, scikit-build-core, setuptools-scm, flit, hatchling\r\n - \u2705 **Intelligent fallback system** with 5-stage detection process\r\n - \u2705 **Rich diagnostics** showing detection method, source, and confidence scoring\r\n- \ufffd\ud83d\udd10 **Secure Token Management**: Stores API tokens securely using your system's keyring\r\n- \ud83d\udce6 **One-Command Publishing**: Complete workflow from checks to upload in a single command\r\n- \ud83e\uddea **TestPyPI Support**: Publish to TestPyPI first for safe testing\r\n- \ud83d\udcc8 **Version Management**: Automatic version bumping with semantic versioning\r\n- \ud83d\udee0\ufe0f **Error Intelligence**: Provides specific suggestions when uploads fail\r\n- \ud83d\ude80 **CI/CD Ready**: Perfect for automated publishing pipelines\r\n\r\n## \ud83d\udcf8 Screenshots\r\n\r\n<!-- \r\n### Interactive Publishing Workflow\r\n\r\n\r\n*Complete guided publishing workflow showing checks, token setup, version bumping, and publishing*\r\n\r\n### CLI Interface Examples\r\n\r\n*Available CLI commands and options*\r\n\r\n\r\n*Automated validation of package structure and requirements* -->\r\n\r\n## \ud83d\udee0\ufe0f Installation\r\n\r\n### From PyPI (Recommended)\r\n```bash\r\npip install khx-publish-pypi\r\n```\r\n\r\n\r\n\r\n\r\nCheck the latest version:\r\n```bash\r\nkhx-publish-pypi --version\r\n```\r\n\r\n### From GitHub (Release or main)\r\n- Install from a tagged GitHub Release asset (requires download first):\r\n - Go to Releases, download the `.whl` or `.tar.gz` from assets, then:\r\n ```bash\r\n pip install path/to/khx_publish_pypi-<version>-py3-none-any.whl\r\n # or\r\n pip install path/to/khx_publish_pypi-<version>.tar.gz\r\n ```\r\n- Or install directly from the repo using pip\u2019s VCS support:\r\n ```bash\r\n # specific tag\r\n pip install git+https://github.com/Khader-X/khx-publish-pypi.git@vX.Y.Z#egg=khx_publish_pypi\r\n # latest on default branch\r\n pip install git+https://github.com/Khader-X/khx-publish-pypi.git@main#egg=khx_publish_pypi\r\n ```\r\n\r\n### From Source (Development)\r\n```bash\r\ngit clone https://github.com/Khader-X/khx-publish-pypi.git\r\ncd khx-publish-pypi\r\npip install -e .\r\n```\r\n\r\n### Requirements\r\n- Python 3.9+\r\n- `twine` for uploads\r\n- `build` for package building\r\n- `keyring` for secure token storage\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n1. **Install the package**\r\n ```bash\r\n pip install khx-publish-pypi\r\n ```\r\n\r\n2. **Set up your API tokens**\r\n ```bash\r\n khx-publish-pypi setup-tokens\r\n ```\r\n\r\n3. **Publish your package**\r\n ```bash\r\n khx-publish-pypi run\r\n ```\r\n\r\nThat's it! The guided workflow will handle everything else.\r\n\r\n## \ud83d\udcd6 Usage\r\n\r\n### Interactive Publishing (Recommended)\r\n```bash\r\nkhx-publish-pypi run\r\n```\r\n\r\nThis command provides a complete guided experience:\r\n- \u2705 Runs pre-publish checks with enhanced version detection\r\n- \ud83d\udd11 Manages API token configuration\r\n- \ud83d\udcc8 Offers version bumping options\r\n- \ud83c\udfd7\ufe0f Builds your package distributions\r\n- \ud83d\udce4 Publishes to TestPyPI and/or PyPI\r\n\r\n### Individual Commands\r\n```bash\r\n# Run pre-publish checks with enhanced version detection\r\nkhx-publish-pypi check\r\n\r\n# Bump version\r\nkhx-publish-pypi bump patch\r\n\r\n# Publish to TestPyPI only\r\nkhx-publish-pypi publish-test\r\n\r\n# Publish to PyPI only\r\nkhx-publish-pypi publish-prod\r\n```\r\n\r\n### Programmatic API (New!)\r\n\r\nKHX-Publish-PyPI now exposes a powerful programmatic API for version detection:\r\n\r\n```python\r\nfrom khx_publish_pypi import detect_package_version, get_package_version\r\nfrom pathlib import Path\r\n\r\n# Simple version detection (legacy interface)\r\nversion = get_package_version(Path(\".\"))\r\nprint(f\"Version: {version}\")\r\n\r\n# Enhanced detection with full diagnostics\r\nresult = detect_package_version(Path(\".\"))\r\nif result.version_info:\r\n info = result.version_info\r\n print(f\"Version: {info.version}\")\r\n print(f\"Method: {info.method}\")\r\n print(f\"Backend: {info.build_backend}\")\r\n print(f\"Confidence: {info.confidence}%\")\r\n print(f\"Source: {info.source}\")\r\nelse:\r\n print(f\"Failed: {', '.join(result.attempts)}\")\r\n```\r\n\r\n## \ud83d\udcda CLI Commands\r\n\r\n| Command | Description |\r\n|---------|-------------|\r\n| `khx-publish-pypi --version` | Show CLI version |\r\n| `khx-publish-pypi check` | Run interactive pre-publish checks |\r\n| `khx-publish-pypi bump [patch\\|minor\\|major]` | Bump package version |\r\n| `khx-publish-pypi setup-tokens` | Configure API tokens interactively |\r\n| `khx-publish-pypi update-tokens` | Update existing tokens |\r\n| `khx-publish-pypi run` | Complete guided publishing workflow |\r\n| `khx-publish-pypi publish-test` | Publish to TestPyPI |\r\n| `khx-publish-pypi publish-prod` | Publish to PyPI |\r\n\r\n### Command Options\r\n\r\n#### Token Setup\r\n```bash\r\n# Interactive setup\r\nkhx-publish-pypi setup-tokens\r\n\r\n# Non-interactive setup\r\nkhx-publish-pypi setup-tokens --test-token YOUR_TEST_TOKEN --prod-token YOUR_PROD_TOKEN\r\n```\r\n\r\n#### Version Bumping\r\n```bash\r\nkhx-publish-pypi bump patch # 1.0.0 \u2192 1.0.1\r\nkhx-publish-pypi bump minor # 1.0.1 \u2192 1.1.0\r\nkhx-publish-pypi bump major # 1.1.0 \u2192 2.0.0\r\n```\r\n\r\n## \u2699\ufe0f Configuration\r\n\r\n### API Tokens\r\n\r\nKHX-Publish-PyPI securely stores your PyPI API tokens using your system's keyring:\r\n\r\n- **TestPyPI**: Stored as `khx-publish-testpypi`\r\n- **PyPI**: Stored as `khx-publish-pypi`\r\n\r\n#### Getting API Tokens\r\n\r\n1. **TestPyPI Token**: [Generate at test.pypi.org](https://test.pypi.org/manage/account/token/)\r\n2. **PyPI Token**: [Generate at pypi.org](https://pypi.org/manage/account/token/)\r\n\r\n#### Environment Variables (Alternative)\r\n\r\nYou can also provide tokens via environment variables:\r\n```bash\r\nexport TESTPYPI_TOKEN=your_test_token\r\nexport PYPI_TOKEN=your_prod_token\r\n```\r\n\r\n### Package Requirements\r\n\r\nYour Python package must have:\r\n- \u2705 `pyproject.toml` with project metadata\r\n- \u2705 `README.md` file\r\n- \u2705 `LICENSE` file\r\n- \u2705 Package directory in `src/` or root\r\n- \u2705 Version defined anywhere! Our enhanced detection supports:\r\n - Static version in `pyproject.toml`\r\n - Dynamic versions with setuptools, scikit-build-core, setuptools-scm, flit, hatchling\r\n - `__version__.py` files in various locations\r\n - Package `__init__.py` with `__version__` attribute\r\n\r\n## \ud83d\udd0d Enhanced Version Detection\r\n\r\nKHX-Publish-PyPI now features a **comprehensive version detection system** that handles all modern Python packaging approaches:\r\n\r\n### Supported Configurations\r\n\r\n| **Build Backend** | **Configuration Example** | **Detection Result** |\r\n|------------------|---------------------------|---------------------|\r\n| **Static** | `version = \"1.0.0\"` in pyproject.toml | `\u2705 v1.0.0 (static)` |\r\n| **Setuptools** | `{attr = \"package.__version__\"}` | `\u2705 v1.0.0 (setuptools_dynamic_attr) dynamic backend:setuptools` |\r\n| **Scikit-build-core** | `provider = \"scikit_build_core.metadata.regex\"` | `\u2705 v1.0.0 (scikit_build_regex) dynamic backend:scikit-build-core` |\r\n| **Setuptools-SCM** | `[tool.setuptools_scm]` | `\u2705 v1.0.0 (setuptools_scm) dynamic backend:setuptools-scm` |\r\n| **Flit** | `[tool.flit.module]` | `\u2705 v1.0.0 (flit_module) dynamic backend:flit` |\r\n| **Hatchling** | `source = \"regex\"` | `\u2705 v1.0.0 (hatchling_regex) dynamic backend:hatchling` |\r\n\r\n### Intelligent Detection Process\r\n\r\n1. **Static version** from pyproject.toml (100% confidence)\r\n2. **Dynamic version** from build backend configs (90-95% confidence)\r\n3. **Direct package import** attempts (85% confidence)\r\n4. **File parsing** of `__version__.py` files (80% confidence)\r\n5. **Setuptools-scm fallback** for git-based projects (70% confidence)\r\n\r\n### Rich Diagnostics\r\n\r\nWhen version detection succeeds, you'll see detailed information:\r\n```\r\n\ud83d\udd22 Version .......................... \u2705 (v0.1.11 (setuptools_dynamic_attr) dynamic backend:setuptools)\r\n```\r\n\r\nWhen it fails, you get helpful diagnostics:\r\n```\r\n\ud83d\udd22 Version .......................... \u274c Failed to detect version. Tried: static_pyproject_version, dynamic_pyproject_version, import_package_version. Errors: Import failed: No module named 'missing_package'\r\n```\r\n\r\n[\ud83d\udcd6 **Read the Complete Enhanced Version Detection Guide**](ENHANCED_VERSION_DETECTION.md)\r\n\r\n## \ud83d\udd27 Troubleshooting\r\n\r\n### Common Issues\r\n\r\n#### \u274c Version Detection Failed\r\n**Cause**: Package version not found or improperly configured\r\n**Solutions**: \r\n1. Ensure `__version__` is properly exported in `__init__.py`:\r\n ```python\r\n from .__version__ import __version__\r\n __all__ = [\"__version__\"]\r\n ```\r\n2. Check dynamic version configuration in `pyproject.toml`\r\n3. Verify version file locations match expected patterns\r\n4. Use enhanced diagnostics: `khx-publish-pypi check` shows detailed detection attempts\r\n\r\n#### \u274c Upload Fails with 400 Error\r\n**Cause**: Package version already exists on PyPI\r\n**Solution**: Bump the version\r\n```bash\r\nkhx-publish-pypi bump patch\r\n```\r\n\r\n#### \u274c Authentication Failed (403)\r\n**Cause**: Invalid or expired API token\r\n**Solution**: Reconfigure tokens\r\n```bash\r\nkhx-publish-pypi setup-tokens\r\n```\r\n\r\n#### \u274c Build Fails\r\n**Cause**: Missing build dependencies or invalid `pyproject.toml`\r\n**Solution**: Install build tools and validate configuration\r\n```bash\r\npip install build twine\r\npython -m build --help\r\n```\r\n\r\n#### \u274c Token Storage Issues\r\n**Cause**: Keyring not available or corrupted\r\n**Solution**: Use environment variables or reinstall keyring\r\n```bash\r\npip uninstall keyring\r\npip install keyring\r\n```\r\n\r\n### Debug Mode\r\nEnable verbose output for troubleshooting:\r\n```bash\r\nkhx-publish-pypi run --verbose\r\n```\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nWe welcome contributions! Here's how to get started:\r\n\r\n1. **Fork the repository**\r\n2. **Create a feature branch**\r\n ```bash\r\n git checkout -b feature/amazing-feature\r\n ```\r\n3. **Make your changes**\r\n4. **Run tests**\r\n ```bash\r\n python -m pytest\r\n ```\r\n5. **Submit a pull request**\r\n\r\n### Development Setup\r\n```bash\r\ngit clone https://github.com/Khader-X/khx-publish-pypi.git\r\ncd khx-publish-pypi\r\npip install -e \".[dev]\"\r\n```\r\n\r\n### Code Style\r\n- Follow PEP 8\r\n- Use type hints\r\n- Write docstrings for all functions\r\n- Add tests for new features\r\n\r\n## \ud83d\udcca CI/CD Integration\r\n\r\nKHX-Publish-PyPI works great with CI/CD pipelines:\r\n\r\n```yaml\r\n# GitHub Actions example\r\n- name: Publish to PyPI\r\n run: |\r\n khx-publish-pypi setup-tokens --test-token ${{ secrets.TEST_PYPI_TOKEN }} --prod-token ${{ secrets.PYPI_TOKEN }}\r\n khx-publish-pypi publish-prod\r\n```\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83d\ude4f Acknowledgments\r\n\r\n- Built with [Click](https://click.palletsprojects.com/) for CLI magic\r\n- Beautiful output powered by [Rich](https://rich.readthedocs.io/)\r\n- Secure token storage via [Keyring](https://github.com/jaraco/keyring)\r\n- Package building with [Build](https://github.com/pypa/build)\r\n- Uploads handled by [Twine](https://github.com/pypa/twine)\r\n- Enhanced version detection supports modern packaging standards\r\n\r\n## \ud83d\udcda Documentation\r\n\r\n- \ud83d\udcd6 **[Enhanced Version Detection Guide](ENHANCED_VERSION_DETECTION.md)**: Complete guide to the new version detection system\r\n- \ud83e\uddea **[Test Examples](test_enhanced_version_detection.py)**: Comprehensive test suite demonstrating all capabilities\r\n- \ud83d\udcbb **[API Usage Examples](example_api_usage.py)**: Programmatic usage examples\r\n\r\n## \ud83d\udcde Support\r\n\r\n- \ud83d\udce7 **Email**: abueltayef.khader@gmail.com\r\n- \ud83d\udc1b **Issues**: [GitHub Issues](https://github.com/Khader-X/khx-publish-pypi/issues)\r\n- \ud83d\udcd6 **Documentation**: [GitHub Wiki](https://github.com/Khader-X/khx-publish-pypi/wiki)\r\n- \ud83d\udcac **Discussions**: [GitHub Discussions](https://github.com/Khader-X/khx-publish-pypi/discussions)\r\n\r\n---\r\n\r\n<p align=\"center\">\r\n Made with \u2764\ufe0f by <a href=\"https://github.com/Khader20\">ABUELTAYEF Khader</a>\r\n</p>\r\n\r\n<p align=\"center\">\r\n <a href=\"https://github.com/Khader-X/khx-publish-pypi\">\u2b50 Star this repo</a> \u2022\r\n <a href=\"https://pypi.org/project/khx_publish_pypi/\">\ud83d\udce6 View on PyPI</a> \u2022\r\n <a href=\"https://khaderabueltayef.blogspot.com/\">\ud83d\udcdd Blog</a>\r\n</p>\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A friendly CLI tool to check and publish Python packages to TestPyPI/PyPI",
"version": "0.1.12",
"project_urls": {
"Author": "https://github.com/Khader20",
"Blog": "https://khaderabueltayef.blogspot.com/",
"Bug Tracker": "https://github.com/Khader-X/khx-publish-pypi/issues",
"Gravatar": "https://gravatar.com/voiddevotedlyf473f5471f",
"Homepage": "https://github.com/Khader-X/khx-publish-pypi",
"Organization": "https://github.com/Khader-X",
"PyPI": "https://pypi.org/user/Khader20/",
"Repository": "https://github.com/Khader-X/khx-publish-pypi"
},
"split_keywords": [
"publish",
" cli",
" pypi",
" packaging",
" release",
" khx"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6ea3668cfc84f5fe7c283040082127370bbf8aa1eded0de5f8bfd414a1abfed7",
"md5": "8ef4e481b4115545787cf919d2348c04",
"sha256": "8ee2c3156f34deb58d6dd2f4bdddefa2b05eaa60dac0a6eaababfb936a19f683"
},
"downloads": -1,
"filename": "khx_publish_pypi-0.1.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8ef4e481b4115545787cf919d2348c04",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 29006,
"upload_time": "2025-09-07T05:22:11",
"upload_time_iso_8601": "2025-09-07T05:22:11.184806Z",
"url": "https://files.pythonhosted.org/packages/6e/a3/668cfc84f5fe7c283040082127370bbf8aa1eded0de5f8bfd414a1abfed7/khx_publish_pypi-0.1.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ea04f17b923c162e27fc0b9dab79689db8c7c019c52dcb17f9fae25f788141a2",
"md5": "4c2716919b5933614d39f8db261035ea",
"sha256": "071cba17c4ce0693522efaf0db709f0d8bfbe5f748cfa8458f446d64c12b9a1c"
},
"downloads": -1,
"filename": "khx_publish_pypi-0.1.12.tar.gz",
"has_sig": false,
"md5_digest": "4c2716919b5933614d39f8db261035ea",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 32493,
"upload_time": "2025-09-07T05:22:12",
"upload_time_iso_8601": "2025-09-07T05:22:12.694165Z",
"url": "https://files.pythonhosted.org/packages/ea/04/f17b923c162e27fc0b9dab79689db8c7c019c52dcb17f9fae25f788141a2/khx_publish_pypi-0.1.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-07 05:22:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Khader-X",
"github_project": "khx-publish-pypi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "khx-publish-pypi"
}
