Metadata-Version: 2.4
Name: dockerhub-status
Version: 0.0.1
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
that an organization access token is allowed to read, either set
`DOCKERHUB_TOKEN` or pass the token explicitly:

```bash
export DOCKERHUB_TOKEN='your-token'
dockerhub-status
```

```bash
dockerhub-status --token 'your-token'
```

The token is sent as a bearer token to Docker Hub's modern namespace API.
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.
