timed-pypi-uploader

A lightweight Python tool for scheduling automated builds and uploads of Python packages to PyPI at specified times or on recurring intervals.

Features

• One-time or recurring scheduling using cron expressions or specific dates/times
• Automatic build backend detection (Hatch, Poetry, setuptools, flit)
• Secure token storage via system keyring
• Dry-run mode for testing without actual uploads
• Git change detection to skip releases when no changes exist
• TestPyPI support for pre-production testing

Installation

pip install timed-pypi-uploader

Quick Start

1. Configure your PyPI token

# Store PyPI token securely
timed-pypi-uploader config --pypi-token pypi-XXXXXXXXXXXX

# Or for TestPyPI
timed-pypi-uploader config --test-pypi-token pypi-XXXXXXXXXXXX

2. Run an immediate release

# Build and upload to PyPI
timed-pypi-uploader run --project-dir .

# Dry run first
timed-pypi-uploader run --dry-run

# Upload to TestPyPI
timed-pypi-uploader run --test-pypi

3. Schedule a release

# One-time release at specific time
timed-pypi-uploader schedule --at "2026-02-01T09:00:00" --project-dir .

# Recurring release (daily at 3am)
timed-pypi-uploader schedule --cron "0 3 * * *"

# Only release if git changes exist
timed-pypi-uploader schedule --cron "0 3 * * *" --check-git-changes

Commands

Configuration

Create a .timed-uploader.toml file in your project:

[general]
project_dir = "."
build_backend = "auto"  # auto, hatch, poetry, build, flit
test_mode = false
clean_before_build = true

[schedule]
type = "cron"  # or "one-time"
cron = "0 3 * * *"  # Daily at 3am
# at = "2026-02-01T09:00:00"  # For one-time
check_git_changes = true

[tokens]
# Tokens stored via keyring, not in this file
pypi_keyring_service = "timed-pypi-uploader-pypi"

Or initialize with:

timed-pypi-uploader config --init

Examples

Build only (no upload)

timed-pypi-uploader build --project-dir /path/to/project

Upload existing dist files

timed-pypi-uploader upload --project-dir /path/to/project

Schedule with verbose logging

timed-pypi-uploader schedule --at "2026-02-01T09:00:00" --verbose

Run in background

nohup timed-pypi-uploader schedule --cron "0 3 * * *" &

Security

• Tokens are never stored in plaintext files
• Uses system keyring (macOS Keychain, Windows Credential Manager, Linux Secret Service)
• Always test with --dry-run and TestPyPI first

Dependencies

• typer - CLI framework
• apscheduler - Job scheduling
• keyring - Secure credential storage
• build - PEP 517 package building
• twine - PyPI uploading

License

MIT

Support