object-segmentation/BUILD.md

Building and Publishing Guide

This guide explains how to build and publish the microscopy-object-detection package.

Prerequisites

pip install build twine

Building the Package

1. Clean Previous Builds

rm -rf build/ dist/ *.egg-info

2. Build Distribution Archives

python -m build

This will create both wheel (.whl) and source distribution (.tar.gz) in the dist/ directory.

3. Verify the Build

ls dist/
# Should show:
# microscopy_object_detection-1.0.0-py3-none-any.whl
# microscopy_object_detection-1.0.0.tar.gz

Testing the Package Locally

Install in Development Mode

pip install -e .

Install from Built Package

pip install dist/microscopy_object_detection-1.0.0-py3-none-any.whl

Test the Installation

# Test CLI
microscopy-detect --version

# Test GUI launcher
microscopy-detect-gui

Publishing to PyPI

1. Configure PyPI Credentials

Create or update ~/.pypirc:

[pypi]
username = __token__
password = pypi-YOUR-API-TOKEN-HERE

2. Upload to Test PyPI (Recommended First)

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

Then test installation:

pip install --index-url https://test.pypi.org/simple/ microscopy-object-detection

3. Upload to PyPI

python -m twine upload dist/*

Version Management

Update version in multiple files:

• setup.py: Update version parameter
• pyproject.toml: Update version field
• src/__init__.py: Update __version__ variable

Git Tags

After publishing, tag the release:

git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

Package Structure

The built package includes:

• All Python source files in src/
• Configuration files in config/
• Database schema file (src/database/schema.sql)
• Documentation files (README.md, LICENSE, etc.)
• Entry points for CLI and GUI

Troubleshooting

Import Errors

If you get import errors, ensure:

• All __init__.py files are present
• Package structure follows the setup configuration
• Dependencies are listed in requirements.txt

Missing Files

If files are missing in the built package:

• Check MANIFEST.in includes the required patterns
• Check pyproject.toml package-data configuration
• Rebuild with python -m build --no-isolation for debugging

Version Conflicts

If version conflicts occur:

• Ensure version is consistent across all files
• Clear build artifacts and rebuild
• Check for cached installations: pip list | grep microscopy

CI/CD Integration

GitHub Actions Example

name: Build and Publish

on:
  release:
    types: [created]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: actions/setup-python@v2
      with:
        python-version: '3.8'
    - name: Install dependencies
      run: |
        pip install build twine
    - name: Build package
      run: python -m build
    - name: Publish to PyPI
      env:
        TWINE_USERNAME: __token__
        TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
      run: twine upload dist/*

Best Practices

1. Version Bumping: Use semantic versioning (MAJOR.MINOR.PATCH)
2. Testing: Always test on Test PyPI before publishing to PyPI
3. Documentation: Update README.md and CHANGELOG.md for each release
4. Git Tags: Tag releases in git for easy reference
5. Dependencies: Keep requirements.txt updated and specify version ranges

Resources

• Python Packaging Guide
• setuptools Documentation
• PyPI Publishing Guide