178 lines
3.7 KiB
Markdown
178 lines
3.7 KiB
Markdown
# Building and Publishing Guide
|
|
|
|
This guide explains how to build and publish the microscopy-object-detection package.
|
|
|
|
## Prerequisites
|
|
|
|
```bash
|
|
pip install build twine
|
|
```
|
|
|
|
## Building the Package
|
|
|
|
### 1. Clean Previous Builds
|
|
|
|
```bash
|
|
rm -rf build/ dist/ *.egg-info
|
|
```
|
|
|
|
### 2. Build Distribution Archives
|
|
|
|
```bash
|
|
python -m build
|
|
```
|
|
|
|
This will create both wheel (`.whl`) and source distribution (`.tar.gz`) in the `dist/` directory.
|
|
|
|
### 3. Verify the Build
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
pip install -e .
|
|
```
|
|
|
|
### Install from Built Package
|
|
|
|
```bash
|
|
pip install dist/microscopy_object_detection-1.0.0-py3-none-any.whl
|
|
```
|
|
|
|
### Test the Installation
|
|
|
|
```bash
|
|
# Test CLI
|
|
microscopy-detect --version
|
|
|
|
# Test GUI launcher
|
|
microscopy-detect-gui
|
|
```
|
|
|
|
## Publishing to PyPI
|
|
|
|
### 1. Configure PyPI Credentials
|
|
|
|
Create or update `~/.pypirc`:
|
|
|
|
```ini
|
|
[pypi]
|
|
username = __token__
|
|
password = pypi-YOUR-API-TOKEN-HERE
|
|
```
|
|
|
|
### 2. Upload to Test PyPI (Recommended First)
|
|
|
|
```bash
|
|
python -m twine upload --repository testpypi dist/*
|
|
```
|
|
|
|
Then test installation:
|
|
|
|
```bash
|
|
pip install --index-url https://test.pypi.org/simple/ microscopy-object-detection
|
|
```
|
|
|
|
### 3. Upload to PyPI
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```yaml
|
|
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](https://packaging.python.org/)
|
|
- [setuptools Documentation](https://setuptools.pypa.io/)
|
|
- [PyPI Publishing Guide](https://packaging.python.org/tutorials/packaging-projects/) |