Metadata-Version: 2.4
Name: dockerhub-status
Version: 0.0.2
Summary: Report repositories and image versions published in a Docker Hub organization.
Author: Kaizten Analytics
License-Expression: LicenseRef-Proprietary
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Docker Hub Status

`dockerhub-status` lists all repositories and image tags published in a Docker
Hub organization. The organization defaults to `kaizten`.

The report includes repository creation and update dates, total pulls, stars,
visibility, status, storage size, and every tag. Tag details include the last
push, update and pull timestamps, compressed size, status, digest, and
platforms.

Docker Hub exposes pull counts per repository, not per tag. Because tags can be
overwritten, the tag publication value is the latest push timestamp supplied by
Docker Hub rather than an immutable first-publication date.

## Requirements

- Python 3.10 or newer
- Network access to `hub.docker.com`

The package has no third-party runtime dependencies.

## Usage

Run the source-tree script with the default organization:

```bash
./dockerhub-status.py
```

Select another organization:

```bash
./dockerhub-status.py --organization docker
```

Print structured JSON:

```bash
./dockerhub-status.py --format json
```

Skip tag requests for a faster repository-only summary:

```bash
./dockerhub-status.py --no-tags
```

After installing the package, use the same options with the console command:

```bash
dockerhub-status --organization kaizten
```

## Authentication

Anonymous requests list public repositories. To include private repositories,
provide a Docker Hub personal access token (PAT) or organization access token
(OAT).

Docker Hub does not accept a PAT or OAT directly in an `Authorization: Bearer`
header. Doing so returns:

```text
Docker Hub API request failed with HTTP 401: A personal access token or organization access token cannot be used as a bearer
```

`dockerhub-status` avoids this error by exchanging the PAT/OAT for a short-lived
access token at `/v2/auth/token`. Only that returned access token is sent as a
bearer to the namespace API.

### Organization access token

For an OAT, the value passed to `--organization` is also used as the
authentication identifier by default:

```bash
export DOCKERHUB_TOKEN='your-organization-access-token'
dockerhub-status --organization kaizten
```

The token can instead be supplied directly on the command line, although an
environment variable is less likely to expose it in shell history or process
listings:

```bash
dockerhub-status \
  --organization kaizten \
  --token 'your-organization-access-token'
```

### Personal access token

For a PAT, set the authentication identifier to your Docker Hub username. The
username can differ from the organization being inspected:

```bash
export DOCKERHUB_IDENTIFIER='your-dockerhub-username'
export DOCKERHUB_TOKEN='your-personal-access-token'
dockerhub-status --organization kaizten
```

The same configuration can be provided with command-line options:

```bash
dockerhub-status \
  --organization kaizten \
  --identifier 'your-dockerhub-username' \
  --token 'your-personal-access-token'
```

Docker Hub can also restrict deep anonymous pagination for organizations with
many repositories. In that case, authentication is required even when all the
requested repositories are public; the command reports the API error instead
of silently returning an incomplete list.

## Build and publish

Build the wheel and source distribution and validate their metadata:

```bash
./build-package.sh
```

Publish an already built version to PyPI:

```bash
./publish-pypi.sh
```

PyPI does not allow an existing filename/version to be uploaded again. Increase
the version in `pyproject.toml` before publishing a replacement release.
