Metadata-Version: 2.4
Name: offlickr
Version: 0.1.0
Summary: Turn a Flickr 'Your Flickr Data' export into a self-contained offline website.
Project-URL: Homepage, https://github.com/yaniv-golan/offlickr
Project-URL: Issues, https://github.com/yaniv-golan/offlickr/issues
Project-URL: Changelog, https://github.com/yaniv-golan/offlickr/blob/main/CHANGELOG.md
Author: Yaniv Golan
License-Expression: MIT
License-File: LICENSE
Keywords: archive,flickr,offline,photography,static-site
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: System :: Archiving
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: nh3>=0.2.18
Requires-Dist: pillow>=10.3
Requires-Dist: pydantic>=2.7
Requires-Dist: python-dotenv>=1.0
Requires-Dist: python-slugify[unidecode]>=8.0
Requires-Dist: rich>=13.7
Provides-Extra: dev
Requires-Dist: beautifulsoup4>=4.12; extra == 'dev'
Requires-Dist: commitizen>=3.28; extra == 'dev'
Requires-Dist: diff-cover>=9; extra == 'dev'
Requires-Dist: freezegun>=1.5; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: syrupy>=4.6; extra == 'dev'
Provides-Extra: heic
Requires-Dist: pillow-heif>=0.16; extra == 'heic'
Description-Content-Type: text/markdown

# offlickr

![offlickr banner](docs/banner.png)

[![CI](https://github.com/yaniv-golan/offlickr/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/yaniv-golan/offlickr/actions/workflows/ci.yml)
[![Release](https://github.com/yaniv-golan/offlickr/actions/workflows/release.yml/badge.svg)](https://github.com/yaniv-golan/offlickr/actions/workflows/release.yml)
[![PyPI](https://img.shields.io/pypi/v/offlickr.svg)](https://pypi.org/project/offlickr/)
[![Python](https://img.shields.io/pypi/pyversions/offlickr.svg)](https://pypi.org/project/offlickr/)
[![Coverage](https://codecov.io/github/yaniv-golan/offlickr/graph/badge.svg)](https://codecov.io/github/yaniv-golan/offlickr)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

**offlickr** turns a Flickr [*Your Flickr Data*](https://www.flickrhelp.com/hc/en-us/articles/4404079675156-Downloading-content-from-Flickr) export into a self-contained static website — a browsable offline archive of your photostream, albums, galleries, and profile. Zero runtime dependencies, works from `file://`, USB stick, or any static host.

> **Status:** alpha (v0.1.0). Ingest, derive, render, and external asset fetch are all working.
>
> **New to the command line?** Copy this prompt into Claude, ChatGPT, or any AI assistant:
>
> ```text
> Read https://raw.githubusercontent.com/yaniv-golan/offlickr/main/llms.txt and guide me, step by step, how to archive my Flickr account for safe-keeping.
> ```

## Quickstart

```bash
pipx install offlickr        # or: uv tool install offlickr

# Request your Flickr data from https://www.flickr.com/account
# (delivers ~5 zip files by email — put them in one folder)

offlickr build ~/Downloads/flickr-export -o ~/my-flickr-archive
offlickr serve ~/my-flickr-archive    # opens http://127.0.0.1:8000
```

## Why

Flickr accounts outlive Flickr's business decisions. If you care about your photos, comments, and the decade-plus of conversations attached to them, you want a local archive you can browse exactly like the site, without depending on Flickr being up.

The data layer (`data/model.json` + `originals/`) is independent of the rendered site — thumbnails and HTML are fully regeneratable. See [What to keep](docs/getting-started.md#what-to-keep) for what actually needs to go into cold storage.

## Features

- Replicates the structure of `flickr.com/photos/<you>/`: photostream, albums, galleries, groups list, faves, tags, geo map, about, testimonials.
- Per-photo detail pages with description, comments, EXIF, notes, and links back to flickr.com.
- Two themes (`minimal-archive` default, `flickr-classic` alternative).
- Private by default: Flickrmail, contacts, followers, and non-public photos are excluded unless you opt in with `--include-private` and `--include-private-photos`.
- Optional external-asset caching (`--archive-external`) to include avatars and fave thumbnails from other Flickr accounts. Requires a free Flickr API key — see [external fetching](docs/external-fetching.md). No API key is needed for the core archive.

## Screenshots

| Photostream | Albums | Map | Photo detail |
| --- | --- | --- | --- |
| [![Photostream grid](docs/screenshots/photostream.png)](docs/screenshots/photostream.png) | [![Albums index](docs/screenshots/albums.png)](docs/screenshots/albums.png) | [![Geo map](docs/screenshots/map.png)](docs/screenshots/map.png) | [![Photo detail](docs/screenshots/photo-detail.png)](docs/screenshots/photo-detail.png) |

## Documentation

- [Getting started](docs/getting-started.md)
- [CLI reference](docs/cli-reference.md)
- [Data model](docs/data-model.md)
- [llms.txt](llms.txt) — LLM-friendly doc index

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md). This project is strictly test-driven.

## License

[MIT](./LICENSE).
