Metadata-Version: 2.4
Name: simple-repository-generator
Version: 0.1.0
Author-email: Phil Elson <philip.elson@cern.ch>
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: simple-repository
Requires-Dist: packaging
Requires-Dist: httpx
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Provides-Extra: doc
Provides-Extra: dev
Requires-Dist: simple-repository-generator[doc,test]; extra == "dev"

# simple-repository-generator

Generate a static [PEP 503](https://peps.python.org/pep-0503/) HTML index from
local directories of wheels and sdists, or from an existing HTTP simple
index. The output tree is a plain set of files suitable for uploading to
GitHub Pages, S3, or any other static host.

Built on [`simple-repository`](https://github.com/simple-repository/simple-repository).

## Install

```
pip install simple-repository-generator
```

## CLI

```
simple-repository-generator [--output OUT] [--copy] [--force] SOURCE [SOURCE ...]
```

- `SOURCE`: either a local directory (crawled recursively for wheels and
  sdists) or an HTTP simple-index URL. Multiple sources are collapsed via
  `PrioritySelectedProjectsRepository`: the first source listed wins on
  conflicts.
- `--output OUT`: destination directory (default `./build/simple-repo`).
- `--copy`: copy distribution files into the output tree and rewrite
  hrefs to relative paths, producing a self-contained tree. Without
  `--copy`, hrefs point at the source (a `file://` URL for a local
  directory, or the upstream URL for an HTTP source).
- `--force`: allow writing into a non-empty output directory.

Local sources do not need to be pre-arranged: filenames are parsed per
PEP 427 (wheels) and PEP 625 (sdists) to infer the project name, and files
are grouped accordingly. Anything whose name doesn't parse is skipped.

### Example

```
$ simple-repository-generator --copy dist/
Wrote simple index to build/simple-repo
  sources:      dist/
  projects:     1
  files:        2
  repo size:    2.8 KiB
  referenced:   2.0 KiB
```

Output tree:

```
build/simple-repo/
  simple/
    index.html                                          # project list
    some-project/
      index.html                                        # project page
  packages/
    some-project/
      some_project-0.1.0-py3-none-any.whl
      some_project-0.1.0-py3-none-any.whl.metadata          # PEP 658 sidecar
      some_project-0.1.0.tar.gz
```

Point pip or uv at the `simple/` subdirectory. Any URL scheme pip
supports for `--index-url` works, including `file://` for a local
sanity check (the path after `file://` must be absolute):

```
pip install --index-url "file://$(pwd)/build/simple-repo/simple/" some-project
```

The output is a plain directory of static files, so it drops straight
into a GitHub Pages site, an S3 bucket, or anything served by
`python -m http.server`.

### Metadata exposed to clients

The emitted project pages carry every attribute the source repository
provides: `data-requires-python`, `data-yanked`, `data-gpg-sig`. In
`--copy` mode the generator additionally wraps the source in
`MetadataInjectorRepository`, extracts each wheel's `*.dist-info/METADATA`
into a `.metadata` sidecar next to the copied wheel, and advertises
`data-core-metadata="true"` on the page, so pip and uv can resolve
dependencies without downloading the full wheel.

Without `--copy` the pages are passed through unchanged. In particular
`data-core-metadata` is not injected, because there is no matching
`.metadata` file to serve alongside the source URL.

File size and upload time are recorded in the `File` model and appear in
the JSON representation. The HTML PEP 503 index does not carry a
data-size attribute (that field is JSON-only in PEP 691), so it is not
surfaced in the emitted HTML.

## Possible future extensions

- A JSON simple-index emitter (PEP 691) for hosts that can serve the
  registered vendor MIME types (e.g. S3, nginx). Pip enforces MIME
  strictly, so this is unusable on GitHub Pages today.
- Allow-list / deny-list / merge composition on the CLI, once HTTP
  sources make config-file input worthwhile.
- Recording `data-size` / upload-time in whatever future PEP extends
  HTML with those attributes.
- Incremental / retention-aware builds. Each run currently writes a
  fresh tree.
