Metadata-Version: 2.4
Name: ghpy
Version: 0.2.99
Summary: A lightweight GitHub release command-line tool
Author: callmetango
License-Expression: AGPL-3.0-only
Project-URL: Repository, https://github.com/callmetango/ghpy
Project-URL: Issues, https://github.com/callmetango/ghpy/issues
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dargpy>=0.3.1
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-describe; extra == "test"
Dynamic: license-file

# ghpy

A lightweight command-line tool for working with GitHub releases.

`ghpy` provides reliable release asset uploads, downloads, and availability
checks, with built-in connection pooling and configurable retry handling for
transient network and HTTP failures.

## Requirements

- Python 3.11 or newer
- A GitHub personal access token

Set the token in `GH_TOKEN`:

```sh
export GH_TOKEN=...
```

## Installation

Install from the source tree:

```sh
python -m pip install .
```

This installs the `ghpy` command.

## Usage

### Upload assets

Upload one or more files to a release:

```sh
ghpy release upload --repo OWNER/REPO TAG FILE...
```

For example:

```sh
ghpy release upload --repo sonicde-arch/beta x86_64-staging \
	*.pkg.tar.zst
```

Use `--clobber` to replace existing assets:

```sh
ghpy release upload --repo OWNER/REPO --clobber TAG FILE...
```

Use `-v` or `--verbose` to show informational messages.

### Download assets

Download release assets:

```sh
ghpy release download --repo OWNER/REPO TAG
```

Restrict the download to matching asset names with `-p` or `--pattern`:

```sh
ghpy release download --repo OWNER/REPO -p '*.pkg.tar.zst' TAG
```

The option can be specified more than once.

### Wait for assets

Wait until release assets become available:

```sh
ghpy release await-assets --repo OWNER/REPO TAG ASSET...
```

For example:

```sh
ghpy release await-assets --repo sonicde-arch/beta x86_64-staging \
	x86_64-staging.pkg.tar.zst
```

Use `-v` to show the assets being checked.

## Retries

Network and transient HTTP failures are retried automatically.

Retries are controlled by both a retry count and a time budget. The configured
timeout limits the time available for retry delays; request time itself does
not consume that retry-delay budget.

The retry behavior can be configured with:

```text
--retries N
--delay SECONDS
--increment SECONDS
--max-delay SECONDS
```

For example:

```sh
ghpy release upload --repo OWNER/REPO \
	--retries 8 --delay 1 --increment 1 --max-delay 300 \
	TAG FILE...
```

Each retry delay is added to the retry time budget. Delays are capped by
`--max-delay`, and GitHub's `Retry-After` and rate-limit information is honored
when available.

## License

ghpy is licensed under the GNU Affero General Public License,
version 3 only. See `LICENSE` for the full license text.
