Metadata-Version: 2.4
Name: pypi-status
Version: 0.0.1
Summary: Report projects and releases published by a PyPI organization or user.
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

# PyPI Status

`pypi-status` lists projects and releases published by a PyPI organization or
user. The owner defaults to `kaizten`.

The report includes verified ownership, project and release publication dates,
latest versions, summaries, licenses, Python requirements, distribution files,
yanked releases, vulnerabilities, and recent package downloads.

## Requirements

- Python 3.10 or newer
- Network access to `pypi.org` and `pypistats.org`

The package has no third-party runtime dependencies.

## Usage

Run the source-tree script with the default owner:

```bash
./pypi-status.py
```

Select another PyPI organization or username:

```bash
./pypi-status.py --organization pypi
```

Print structured JSON:

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

After installation, use the same options with:

```bash
pypi-status --organization kaizten
```

## Ownership discovery

The command first checks for a public PyPI Organization with the requested
slug. When no organization exists, it treats the value as a PyPI username. The
default `kaizten` value currently resolves to the user account that owns the
Kaizten projects.

Organization projects are discovered from their public PyPI profile. Username
projects use PyPI's `user_packages` XML-RPC method because PyPI does not provide
a replacement user-project listing API. That method is deprecated by PyPI but
remains available. Every discovered project is checked against the verified
ownership fields in PyPI's project JSON response. Stale names for deleted
projects can remain in that legacy response; the command filters them out by
checking that the current project JSON still exists.

## Download counts

PyPI's project JSON contains a legacy `downloads` field whose values are always
`-1`. This command ignores it and uses the public PyPI Stats API to report
last-day, last-week, and last-month package totals excluding known mirrors.

PyPI Stats does not provide downloads by release version, so release rows do
not claim a per-version download count. A project that has not entered the
PyPI Stats dataset yet is reported with zero recent downloads. Transient API
rate-limit and server responses are retried before being reported as errors.

## Build and publish

Build and validate the wheel and source distribution:

```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.
