Metadata-Version: 2.4
Name: mneme-storage
Version: 1.0.0
Summary: Official Mneme SDK: encrypted file storage on Filecoin, with an API key.
License-Expression: MIT
Project-URL: Homepage, https://mneme-blockchain-app.online
Keywords: mneme,filecoin,storage,encryption,icp
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: System :: Archiving :: Backup
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: cryptography>=41

# mneme-storage (Python)

Official Python SDK for [Mneme](https://mneme-blockchain-app.online): encrypted file storage on Filecoin.

Files are encrypted on your computer and sent straight to Filecoin storage providers (2 copies). They never pass through Mneme or any other server.

## Install

```bash
pip install mneme-storage
```

Needs Python 3.9 or newer.

## Use

Create an API key in the Mneme web app (**API Keys**), then:

```python
from mneme_storage import Mneme

mneme = Mneme(api_key="mnm_live_...")

file = mneme.upload("video.mp4")             # returns when stored on Filecoin
print(file["id"], file["status"])            # file-42 stored_on_filecoin

mneme.download(file["id"], "copy.mp4")       # verified and decrypted
print(mneme.list()["files"])                 # your files, 100 per page
mneme.delete(file["id"])
```

| Method | What it does |
|---|---|
| `upload(path, wait=True, on_progress=None)` | Uploads one file. `wait=False` returns as soon as the bytes reached Filecoin; Mneme finishes on its own. |
| `upload_many(paths)` | Uploads many files in as few uploads as possible (cheaper). |
| `download(file_id, path)` | Downloads, checks every chunk, decrypts. |
| `list(offset=0, limit=100)` | One page of your files. |
| `get(file_id)` | One file's details. |
| `wait_until_stored(file_id)` | Waits until a file is stored on Filecoin. |
| `delete(file_id)` | Deletes a file. |
| `find_by_name(name)` · `find_by_hash(sha256_hex)` | Find your file by its name or by the SHA-256 of its content. |
| `filecoin_info(file_id)` | Where the file lives on Filecoin: providers, data sets, piece CIDs. |
| `account()` · `storage_stats()` · `list_keys()` | Quota and usage, vault totals, your API keys (names only). |
| `upload_status(upload_id)` · `cancel_upload(upload_id)` | State of an upload; cancel one that was started but not finished. Files returned by `upload` carry their `"uploadId"`. |

Errors raise `MnemeError` (with `.status`, the HTTP status code).

## Mainnet or testnet

The SDK uses **mainnet** (the live Mneme backend, real Filecoin) by default.
`network="testnet"` uses a Mneme test backend running on your computer
(`npm run local` in the Mneme project), which stores on the Filecoin
Calibration testnet with free test coins. The same code runs on both:

```python
mneme = Mneme(api_key="mnm_live_...", network="testnet")   # or "mainnet"
```

or, without touching the code: `export MNEME_NETWORK=testnet`. Use an API key
from the backend you talk to (the local site's API Keys page for testnet).
`base_url=` (or `MNEME_BASE_URL`) points the SDK at any other backend address.

Uploads count towards your plan exactly like uploads in the web app. Files you upload here open in the web app, and the other way round.
