Publish bead to PyPI for pipx installation

[korenmiklos]

Goal

Make bead installable via pipx install bead by publishing to PyPI.

Current Status

✅ Good News:

• Package name "bead" is available on PyPI
• Modern packaging setup with pyproject.toml using flit_core
• CLI entry point configured
• Basic metadata present (name, version, description, author, license)

Required Steps

1. Complete Project Metadata in pyproject.toml

• Add readme = "README.md"
• Add homepage or repository URL
• Add keywords for discoverability
• Add classifiers (Python versions, development status, topic)
• Add project.urls for documentation, bug tracker

2. Prepare Documentation

• Clean up README.md (remove inactive CI badges)
• Add installation instructions for pipx install bead
• Add quick start guide
• Consider adding CHANGELOG.md

3. Build Configuration

• Verify MANIFEST.in includes all necessary files
• Consider removing tests from packages in pyproject.toml
• Evaluate if tracelog.py should be in distribution

4. Create PyPI Account & API Token

• Register at https://pypi.org
• Create API token for uploads
• Store token securely (GitHub secrets for CI)

5. Test on TestPyPI First

# Build the package
pip install build
python -m build

# Upload to TestPyPI
pip install twine
twine upload --repository testpypi dist/*

# Test installation
pipx install --index-url https://test.pypi.org/simple/ bead

6. Upload to Production PyPI

# Upload to PyPI
twine upload dist/*

# Verify installation
pipx install bead

7. Post-Upload Tasks

• Set up GitHub Actions for automated releases
• Add PyPI badge to README
• Implement semantic versioning
• Configure pre-commit hooks for version bumping

Considerations

• ⚠️ Unusual dependency: pip>=25.1.1 - verify if intentional
• ⚠️ Consider if tests directory should be in package distribution
• ℹ️ .bumpversion.cfg exists - use for version management

Quick Reference

# One-time setup
pip install build twine

# For each release
python -m build
twine check dist/*
twine upload dist/*

Benefits

• Easy installation: pipx install bead
• Automatic dependency management
• Version pinning support
• Wide distribution and discoverability

[korenmiklos]

Package Name Analysis: No Conflict with "pybeads"

✅ No Conflict Between "bead" and "pybeads"

I've investigated the potential naming conflict, and there is no issue:

1. Different package names: bead vs pybeads are completely separate packages on PyPI
2. PyPI treats them as distinct: Each package has its own namespace
3. "pybeads" is unrelated: It's a "Baseline estimation and denoising algorithm using sparsity" - completely different domain from our linked frozen computations tool

📋 PyPI Package Naming Rules

No manual review for most packages:

• PyPI registration is automated - no human review for package names
• Packages are published immediately upon upload
• Only blocked if name conflicts with:
  • Python standard library modules
  • Existing packages (exact match)
  • Confusingly similar names to popular packages
  • Explicitly prohibited names

Name normalization:

• PyPI normalizes names (e.g., my-package, my_package, My.Package → all treated similarly)
• But bead and pybeads are sufficiently different - no normalization issue

✅ "bead" is Clear to Publish

• No conflict with pybeads
• No standard library conflict
• Not confusingly similar to any major package
• Clean, short, memorable name

The only minor consideration: users might occasionally type pip install beads by mistake, but this would just fail with "package not found" (no package called "beads" exists).

Conclusion: We can proceed with publishing under the name "bead" without any naming conflicts.

[korenmiklos]

Prerequisites Identified

Before publishing to PyPI, we should first verify the package structure using direct GitHub installation:

Test with pipx from GitHub (#5)

Created issue #5 to track testing via:

pipx install git+https://github.com/codedthinking/bead.git

This will help us:

1. ✅ Validate package structure and entry points
2. ✅ Confirm all dependencies are correctly specified
3. ✅ Test the CLI works in isolated environment
4. ✅ Ensure build configuration is correct

Once #5 confirms everything works via GitHub installation, we can proceed with confidence to PyPI publication.

Updated Order of Operations

1. First: Test pipx installation from GitHub (Enable pipx installation from GitHub repository (pre-PyPI testing) #5)
2. Then: Publish to PyPI (Publish bead to PyPI for pipx installation #1)
3. After: Enable conda-forge (Publish bead to conda-forge for conda/mamba installation #2) and document other installation methods (Support installation via uv tool for modern Python workflow #3)

[korenmiklos]

Updated Status Check & Step-by-Step Guide for PyPI Publishing

✅ Already Completed (from main branch):

1. Project metadata - All required fields present in pyproject.toml
2. Project URLs - Homepage, Repository, Bug Tracker, Documentation added
3. README.md - Exists with project description, pipx installation instructions
4. LICENSE - The Unlicense license file present
5. Build backend - Switched from flit_core to setuptools for proper packaging
6. Classifiers - Would benefit from adding more, but basic ones work
7. Distribution files - bead-0.8.2-py3-none-any.whl already built

📋 Step-by-Step Guide to Publish

Step 1: Install Required Tools

python -m pip install --upgrade pip build twine

Step 2: Clean & Rebuild Distribution

# Clean old builds
rm -rf dist/ build/ *.egg-info

# Build both wheel and source distribution
python -m build

# Verify the build
ls -la dist/
# Should show:
# - bead-0.8.2-py3-none-any.whl
# - bead-0.8.2.tar.gz

Step 3: Check Package Quality

# Check for common issues
twine check dist/*

# Test local installation
pip install dist/bead-0.8.2-py3-none-any.whl
bead version
pip uninstall bead -y

Step 4: Create PyPI Accounts

1. TestPyPI (for testing):

   • Register at: https://test.pypi.org/account/register/
   • Create API token: https://test.pypi.org/manage/account/#api-tokens
   • Scope: "Entire account"
   • Save token starting with pypi-...

2. PyPI (for production):

   • Register at: https://pypi.org/account/register/
   • Create API token: https://pypi.org/manage/account/#api-tokens
   • Scope: "Entire account"
   • Save token starting with pypi-...

Step 5: Configure .pypirc (Optional but Convenient)

Create ~/.pypirc:

[distutils]
index-servers =
    testpypi
    pypi

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = <your-test-pypi-token>

[pypi]
repository = https://upload.pypi.org/legacy/
username = __token__
password = <your-pypi-token>

Step 6: Upload to TestPyPI First

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

# Test installation from TestPyPI
pipx install --index-url https://test.pypi.org/simple/ bead
bead version
pipx uninstall bead

Step 7: Upload to Production PyPI

# Upload to PyPI
twine upload dist/*

# Or if using token directly (without .pypirc):
# twine upload dist/* --username __token__ --password <your-pypi-token>

Step 8: Verify Production Installation

# Wait 1-2 minutes for CDN propagation
pipx install bead
bead version
bead --help

Step 9: Update Documentation

• Add PyPI badge to README.md:

  [![PyPI version](https://badge.fury.io/py/bead.svg)](https://pypi.org/project/bead/)

• Update installation instructions to mention pipx install bead

⚠️ Pre-Flight Checklist

• Version is 0.8.2 in pyproject.toml
• All tests pass locally
• No sensitive information in code
• Dependencies are reasonable (note: pip>=25.1.1 is unusual)
• Package name "bead" is still available on PyPI

📦 What Will Be Published

• Package name: bead
• Version: 0.8.2
• Modules: bead, bead_cli, tests, tracelog
• Entry point: bead command
• Dependencies: appdirs, argcomplete, attrs, cached-property, pip

🚀 After Publishing

1. Check package page: https://pypi.org/project/bead/
2. Test with: pipx install bead (from anywhere)
3. Consider removing tests from packages in future releases
4. Set up GitHub Actions for automated releases
5. Use bumpversion for future version updates

📝 Notes

• The package is already properly configured and tested via pipx from GitHub
• TestPyPI is optional but recommended for first-time publishers
• After first successful publish, future releases are simpler
• Consider using GitHub Actions for automated releases in the future