queue-py/README-dev-publish.md

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:

cd ~/Code/@packages/queue-py
pip install -e . --break-system-packages

Usage

Basic Publishing

# From package directory
cd @ml/content-understanding
dev-publish

# From anywhere
dev-publish /path/to/package

Options

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

# 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:

   cd @ml/content-understanding
   # Edit src/lilith_content_understanding/processor.py
   

2. Fast publish with dev version (~15 seconds):

   dev-publish
   # Output: Published lilith-content-understanding@0.1.0-dev.1768416890
   

3. Update consumer app:

   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:

   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:

   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:

[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

source ~/.bashrc
# Or set manually:
export FORGEJO_PYPI_TOKEN="your-token-here"

Build Failed

# Check build system
python -m build --help

# Try with verbose output
dev-publish --verbose

Publish Failed

# Check twine installation
twine --version

# Check registry connectivity
curl -I http://forge.black.lan/api/packages/lilith/pypi

ModuleNotFoundError

# 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 for the full specification.

See Also

• TypeScript CLI
• PROTOCOL.md
• Workspace Scripts