Metadata-Version: 2.4
Name: pincushion
Version: 0.5.0
Summary: An archiving tool for Historypin
Requires-Python: >=3.9
Requires-Dist: click>=8.1.7
Requires-Dist: jinja2>=3.1.4
Requires-Dist: requests>=2.32.3
Requires-Dist: tqdm>=4.66.5
Requires-Dist: yt-dlp>=2024.9.27
Description-Content-Type: text/markdown

# pincushion

[![Test](https://github.com/historypin/pincushion/actions/workflows/test.yml/badge.svg)](https://github.com/historypin/pincushion/actions/workflows/test.yml)

*pincushion* is a command line tool for creating archives for resources on [Historypin]. It reads data from the [Historypin API] and writes a static website to a given directory. The resulting file structure looks something like:

```
archive
├── collections
│   ├── my-collection
│   │   ├── image.jpg
│   │   └── index.html
│   ├── my-other-collection
│   │   ├── image.jpg
│   │   └── index.html
│   └── my-last-collection
│       ├── image.jpg
│       └── index.html
├── data.json
├── index.html
├── pins
│   ├── 123 
│   │   ├── image.jpg
│   │   └── index.html
│   ├── 456
│   │   ├── image.jpg
│   │   └── index.html
│   ├── 789 
│   │   ├── image.jpg
│   │   └── index.html
│   ├── 1001 
│   │   ├── index.html
│   │   └── media.mp3
│   └── 2112
│       ├── index.html
│       └── media.mp4
└── user.jpg
```

Each pin has its own directory, which contains the uploaded media (image, audio or video). The `data.json` file is an aggregation of JSON data collected from the Historypin API, which is used to create the static site.

## Install

```shell
pip install pincushion
```

## Use

Create an archive for user 11670:

```
pincushion user --user-id 11670 --archive-path my-archive
```

Open the `my-archive/index.html` file in your browser.

Similarly you can create an archive for a "collection" as long as the collection contains sub-collections:

```
pincushion collection --slug 2025-summer-institute --archive-path my-collection
```

[Historypin]: https://historypin.org
[Historypin API]: https://historypin.github.io/api-docs/
