cal-publish-python 0.2.3

CLI tool to publish Python packages and documentation with external configuration

cal-publish-python

CLI tool to publish Python packages and documentation with external configuration.

Overview

cal-publish-python is designed to keep sensitive configuration (tokens, registry URLs, SSH keys) outside of build jobs. The project being published defines the "what" (name, version), while the publishing configuration defines the "where" (registry, documentation platform).

Installation

pip install cal-publish-python

Or with uv:

uv pip install cal-publish-python

Usage

Publishing to PyPI

cal-publish-python pypi --output-dir output/

Or specify a wheel directly:

cal-publish-python pypi --wheel output/my-package-1.0.0-py3-none-any.whl

Publishing Documentation

GitLab Pages Mode

cal-publish-python docs --project my-project --doc-version 1.0.0 --html html/

With options:

cal-publish-python docs -p my-project -V 1.0.0 -H html/ --set-latest --force

SSH Mode

Configure SSH mode in your config file, then:

cal-publish-python docs -p my-project -V 1.0.0 --output-dir output/

Configuration

Config File

Create a JSON configuration file:

{
    "pypi": {
        "token": "pypi-xxxxxxxxxxxx",
        "repository_url": "https://upload.pypi.org/legacy/"
    },
    "docs": {
        "mode": "gitlab-pages",
        "gitlab_pages": {
            "token": "glpat-xxxxxxxxxxxx",
            "url": "https://gitlab.com",
            "group": "docs"
        },
        "ssh": {
            "host": "docs.example.com",
            "base_path": "/var/www/docs",
            "ssh_key": "~/.ssh/id_rsa",
            "user": "deploy",
            "port": 22
        }
    }
}

Set the config file path via environment variable:

export CAL_PUBLISH_CONFIG=/path/to/config.json

Or pass it directly:

cal-publish-python -c config.json pypi --output-dir output/

Environment Variables

All configuration values can be overridden by environment variables:

Variable	Description
CAL_PUBLISH_CONFIG	Path to JSON config file
CAL_PUBLISH_PYPI_TOKEN	PyPI API token
CAL_PUBLISH_PYPI_REPOSITORY_URL	PyPI repository URL
CAL_PUBLISH_DOCS_MODE	Documentation mode (gitlab-pages or ssh)
CAL_PUBLISH_GITLAB_TOKEN	GitLab personal access token
CAL_PUBLISH_GITLAB_URL	GitLab instance URL
CAL_PUBLISH_GITLAB_GROUP	GitLab group for docs
CAL_PUBLISH_SSH_HOST	SSH host
CAL_PUBLISH_SSH_BASE_PATH	Base path on remote server
CAL_PUBLISH_SSH_KEY	Path to SSH private key
CAL_PUBLISH_SSH_USER	SSH user
CAL_PUBLISH_SSH_PORT	SSH port

Integration with Makefile

Add a publish target to your project's Makefile:

.PHONY: publish
publish: build
	cal-publish-python pypi --output-dir output/
	cal-publish-python docs -p $(PROJECT_NAME) -V $(VERSION_STR) --output-dir output/ --set-latest

Development

# Clone the repository
git clone <repo-url>
cd cal-publish-python

# Set up development environment
make dev

# Run checks
make check

# Build
make build

Licence

MIT License — Copyright (c) 2026 Cyber Assessment Labs