Metadata-Version: 2.4
Name: pawpyrus
Version: 2025.2.27.0
Summary: A minimalist paper data storage based on QR codes
Project-URL: Repository, https://codeberg.org/screwery/pawpyrus
Project-URL: Issues, https://codeberg.org/screwery/pawpyrus/issues
Project-URL: Changelog, https://codeberg.org/screwery/pawpyrus/src/branch/main/CHANGELOG.md
Author-email: Ellie Viesná <snowboard_refinery@proton.me>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: ArUco,QR,data storage,paper
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: argparse
Requires-Dist: bitarray
Requires-Dist: more-itertools
Requires-Dist: numpy
Requires-Dist: opencv-contrib-python
Requires-Dist: opencv-python
Requires-Dist: pyzbar
Requires-Dist: qrcode
Requires-Dist: reportlab
Requires-Dist: svglib
Requires-Dist: tqdm
Description-Content-Type: text/markdown

![Logo](https://codeberg.org/screwery/pawpyrus/raw/branch/main/logo.svg)

## Description

![PyPI - Version](https://img.shields.io/pypi/v/pawpyrus?style=flat-square)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pawpyrus?style=flat-square)
![PyPI - Status](https://img.shields.io/pypi/status/pawpyrus?style=flat-square)
![PyPI - Downloads](https://img.shields.io/pypi/dm/pawpyrus?style=flat-square)
![PyPI - License](https://img.shields.io/pypi/l/pawpyrus?style=flat-square)
![Gitea Issues](https://img.shields.io/gitea/issues/open/screwery/pawpyrus?gitea_url=https%3A%2F%2Fcodeberg.org&style=flat-square)
![Gitea Last Commit](https://img.shields.io/gitea/last-commit/screwery/pawpyrus?gitea_url=https%3A%2F%2Fcodeberg.org&style=flat-square)

Pawpyrus is a minimalist open-source paper data storage based on QR codes and ArUco.
It generates a PDF from any small-sized binary file (recommended size <100kb).
Further, the paper data storage can be scanned and decoded (recommended resolution 300dpi).

It can be useful if you need to backup data on paper:

* Encryption keys (e.g. [GnuPG](https://gnupg.org))
* File-based password databases (e.g. [KeePassXC](https://keepassxc.org))
* Cryptocurrency wallets

## Installation

The script is pure Python and a part of [PyPI](https://pypi.org/project/pawpyrus), so can be installed via *pip*:

```bash
python3 -m pip install pawpyrus
```

## Usage

Encoder:

```bash
pawpyrus Encode -n "Description" -i  "input.file" -o "output.pdf"
```

Also, pawpyrus can read data from stdin.
For example, encoding GPG public keys:

```bash
gpg --export 0xDEADBEEF | pawpyrus Encode -n "My pubkey" -i - -o "my-pubkey.pdf"
```

Decoder:

```bash
pawpyrus Decode -i "scan1.jpg" "scan2.png" "scan3.jpg" "masked/too/*.png" -o "output.file"
```

## Data Format

Pawpyrus uses a custom alphanumeric encoding, which is designed to store information in QR code quite effectively.
For now, that makes 4.3kb per A4 page (pixel size 0.6 mm).

## Got a Trouble?

**QR and ArUco detectors may fail on one or several blocks.**
The situation is totally normal, although uncomfortable.
It's fixed for now, with two detectors ([opencv](https://github.com/opencv/opencv-python) and [pyzbar](https://github.com/NaturalHistoryMuseum/pyzbar)) instead of one, but the bug may reappear in some circumstances.
That's why Debug Mode was implemented:

```bash
pawpyrus Decode -d "debug_dir" -i "scan1.jpg" "scan2.jpg" "scan3.jpg" -o "output.file"
```

With Debug Mode, you can inspect undetected QR codes, read them manually with any device you have, and create a file with text blocks which can be processed as well:

```bash
pawpyrus Decode "scan1.jpg" "scan2.jpg" "scan3.jpg" -t "unrecognized_codes.txt" -o "output.file"
```

If you have any idea how to fix the bug better, [give me a clue](https://codeberg.org/screwery/pawpyrus/issues).

## Similar Projects

1. [intra2net/paperbackup](https://github.com/intra2net/paperbackup)
2. [Paperback by Olly](https://ollydbg.de/Paperbak/) and [Wikinaut/paperback-cli](https://github.com/Wikinaut/paperback-cli)
3. [colorsafe/colorsafe](https://github.com/colorsafe/colorsafe)
4. [Twibright Optar](http://ronja.twibright.com/optar)
5. [Paperkey](https://www.jabberwocky.com/software/paperkey)
6. [4bitfocus/asc-key-to-qr-code](https://github.com/4bitfocus/asc-key-to-qr-code)
