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 a named profile in 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

# Publish everything in output/ (wheel + docs zip)
cal-publish-python --set-latest output/

# Publish only the PyPI package
cal-publish-python --pypi-only output/

# Publish only the documentation
cal-publish-python --docs-only --set-latest output/

# Specify a profile explicitly
cal-publish-python --profile internal --set-latest output/

# Specify individual files
cal-publish-python output/my-package-1.0.0-py3-none-any.whl output/my-package-1.0.0-docs.zip

CLI Arguments

Configuration

Profiles

Configuration uses named profiles. Each profile contains the full set of publishing settings (PyPI credentials, documentation targets, etc.). This allows the same config file to serve both public and internal publishing.

Create a JSON config file at ~/.config/cal-publish-python/config.json:

{
    "profiles": {
        "public": {
            "pypi": {
                "token": "pypi-xxxxxxxxxxxx",
                "username": "__token__",
                "repository_url": "https://upload.pypi.org/legacy/"
            },
            "docs": {
                "mode": "gitlab-pages",
                "gitlab_pages": {
                    "token": "glpat-xxxxxxxxxxxx",
                    "url": "https://gitlab.com",
                    "group": "mygroup/public/docs"
                }
            }
        },
        "internal": {
            "pypi": {
                "token": "nexus-xxxxxxxxxxxx",
                "username": "deploy-user",
                "repository_url": "https://nexus.internal/repository/pypi/"
            },
            "docs": {
                "mode": "ssh",
                "ssh": {
                    "host": "docs.internal",
                    "base_path": "/var/www/docs"
                }
            }
        }
    }
}

Profile Selection

A profile is required when a config file is present. The profile is resolved in this order:

1. --profile NAME CLI argument
2. CAL_PUBLISH_PROFILE environment variable
3. [tool.cal-publish-python] in pyproject.toml:

[tool.cal-publish-python]
profile = "public"

This means each project can declare which profile it uses, and make publish just works without any extra arguments.

Config File Location

The config file is resolved in this order:

1. --config FILE CLI argument
2. CAL_PUBLISH_CONFIG environment variable
3. ~/.config/cal-publish-python/config.json (default)

If no config file exists at the default path, the tool runs in environment-variable-only mode (useful for CI).

Environment Variables

All configuration values can be overridden by environment variables, regardless of what the config file/profile contains:

Integration with Makefile

Add a publish target to your project's Makefile:

.PHONY: publish
publish: check-dependencies
	uv run cal-publish-python --set-latest output/

And declare the profile in pyproject.toml:

[tool.cal-publish-python]
profile = "public"

Documentation Zip Filename

The docs zip filename is used to determine the project name and version:

project-name-VERSION-docs.zip

Examples: myproject-1.0.0-docs.zip, my-lib-2.3.4.post5+gabcdef-docs.zip

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