211 lines
4.3 KiB
Markdown
211 lines
4.3 KiB
Markdown
# dev-publish (Python CLI)
|
|
|
|
Fast local build+publish utility for Python packages in the `@packages` workspace.
|
|
|
|
## Installation
|
|
|
|
The `dev-publish` CLI is included in the `lilith-queue-cli` package:
|
|
|
|
```bash
|
|
cd ~/Code/@packages/queue-py
|
|
pip install -e . --break-system-packages
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Publishing
|
|
|
|
```bash
|
|
# From package directory
|
|
cd @ml/content-understanding
|
|
dev-publish
|
|
|
|
# From anywhere
|
|
dev-publish /path/to/package
|
|
```
|
|
|
|
### Options
|
|
|
|
```bash
|
|
dev-publish [OPTIONS] [PACKAGE_PATH]
|
|
|
|
Options:
|
|
-d, --dry-run Show what would be done without executing
|
|
-s, --skip-build Skip build step, only publish
|
|
-v, --verbose Detailed logging output
|
|
--registry TEXT Override registry URL
|
|
--skip-version-check Don't check if version already exists
|
|
--help Show this message and exit
|
|
```
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Dry run - see what would happen
|
|
dev-publish --dry-run
|
|
|
|
# Verbose output
|
|
dev-publish --verbose
|
|
|
|
# Skip build (only publish)
|
|
dev-publish --skip-build
|
|
|
|
# Custom registry
|
|
dev-publish --registry https://test-pypi.org/
|
|
|
|
# Combine options
|
|
dev-publish --dry-run --verbose
|
|
```
|
|
|
|
## Co-Development Workflow
|
|
|
|
**Scenario**: Updating `lilith-content-understanding` while working on a consumer app
|
|
|
|
1. **Make changes to library**:
|
|
```bash
|
|
cd @ml/content-understanding
|
|
# Edit src/lilith_content_understanding/processor.py
|
|
```
|
|
|
|
2. **Fast publish with dev version** (~15 seconds):
|
|
```bash
|
|
dev-publish
|
|
# Output: Published lilith-content-understanding@0.1.0-dev.1768416890
|
|
```
|
|
|
|
3. **Update consumer app**:
|
|
```bash
|
|
cd ~/Code/@applications/my-app
|
|
pip install lilith-content-understanding==0.1.0-dev.1768416890
|
|
```
|
|
|
|
4. **Test changes immediately**
|
|
|
|
5. **Iterate** (repeat steps 1-4)
|
|
|
|
6. **When satisfied, publish stable version**:
|
|
```bash
|
|
cd @ml/content-understanding
|
|
# Update version in pyproject.toml: 0.1.0 → 0.1.1
|
|
git commit -am "feat: add new feature"
|
|
git push # Forgejo CI publishes stable 0.1.1
|
|
```
|
|
|
|
7. **Update consumer to stable**:
|
|
```bash
|
|
cd ~/Code/@applications/my-app
|
|
pip install --upgrade lilith-content-understanding
|
|
```
|
|
|
|
## How It Works
|
|
|
|
1. **Detects** Python package (checks for pyproject.toml)
|
|
2. **Reads** metadata from `[project]` and `[tool.lilith]` sections
|
|
3. **Creates** dev version: `{version}-dev.{timestamp}`
|
|
4. **Builds** package using `python -m build`
|
|
5. **Publishes** to PyPI registry using `twine`
|
|
|
|
## Dev Version Format
|
|
|
|
Format: `{base_version}-dev.{timestamp}`
|
|
|
|
Examples:
|
|
- `0.1.0` → `0.1.0-dev.1768416890`
|
|
- `1.2.3` → `1.2.3-dev.1768420000`
|
|
|
|
## Environment Variables
|
|
|
|
### Required
|
|
|
|
- `FORGEJO_PYPI_TOKEN` - PyPI registry authentication token
|
|
|
|
### Optional
|
|
|
|
- `LOCAL_PUBLISH_PYPI_REGISTRY` - Registry URL
|
|
Default: `http://forge.black.lan/api/packages/lilith/pypi`
|
|
|
|
## Package Metadata
|
|
|
|
The CLI reads configuration from `pyproject.toml`:
|
|
|
|
```toml
|
|
[project]
|
|
name = "lilith-package-name"
|
|
version = "1.0.0"
|
|
|
|
[tool.lilith]
|
|
registry = "forgejo" # Optional, default: "forgejo"
|
|
publish = true # Optional, default: true
|
|
```
|
|
|
|
## Exit Codes
|
|
|
|
| Code | Meaning |
|
|
|------|---------|
|
|
| 0 | Success |
|
|
| 1 | Invalid arguments |
|
|
| 2 | Package detection failed |
|
|
| 3 | Metadata validation failed |
|
|
| 4 | Build failed |
|
|
| 5 | Publish failed |
|
|
| 10 | Registry error |
|
|
|
|
## Troubleshooting
|
|
|
|
### Error: FORGEJO_PYPI_TOKEN not set
|
|
|
|
```bash
|
|
source ~/.bashrc
|
|
# Or set manually:
|
|
export FORGEJO_PYPI_TOKEN="your-token-here"
|
|
```
|
|
|
|
### Build Failed
|
|
|
|
```bash
|
|
# Check build system
|
|
python -m build --help
|
|
|
|
# Try with verbose output
|
|
dev-publish --verbose
|
|
```
|
|
|
|
### Publish Failed
|
|
|
|
```bash
|
|
# Check twine installation
|
|
twine --version
|
|
|
|
# Check registry connectivity
|
|
curl -I http://forge.black.lan/api/packages/lilith/pypi
|
|
```
|
|
|
|
### ModuleNotFoundError
|
|
|
|
```bash
|
|
# Reinstall in editable mode
|
|
cd ~/Code/@packages/queue-py
|
|
pip install -e . --break-system-packages
|
|
```
|
|
|
|
## Performance
|
|
|
|
- **Build + Publish**: ~15-20 seconds
|
|
- **vs Forgejo CI/CD**: 2-5 minutes
|
|
- **Speedup**: 10-15x faster iteration
|
|
|
|
## API Parity
|
|
|
|
This Python implementation follows the same protocol as the TypeScript version:
|
|
- Identical CLI interface
|
|
- Same exit codes
|
|
- Same logging format
|
|
- Same dev version algorithm
|
|
|
|
See [PROTOCOL.md](../../../@cli/dev-publish/PROTOCOL.md) for the full specification.
|
|
|
|
## See Also
|
|
|
|
- [TypeScript CLI](../../@cli/dev-publish/)
|
|
- [PROTOCOL.md](../../@cli/dev-publish/PROTOCOL.md)
|
|
- [Workspace Scripts](../../scripts/publishing/)
|